nd7 documentation
nd7 is an open-source tool that runs an AI coding agent inside a sandbox the operating system enforces, and keeps an append-only record of what the agent did. This page says what exists today, what is still planned, which platforms are tested, and which page to read next. Everything here comes from the nd7-core repository; where a thing is planned rather than built, it says so.
The pages#
Getting started#
- Quick start: install, sandbox and record, in five steps.
- Install nd7 on macOS: requirements, the one install command, where the two binaries must live, and how to remove them.
- A session, start to finish:
nd7 run claudefrom the first command to the first denial and back.
Sandbox#
- How sandboxing works: what a sandbox is, the layers of isolation from process sandbox to microVM, and why nd7 sits where it does.
- How the macOS sandbox works: Seatbelt, the exact rules, why nothing inside can loosen them, and the known limits.
- Change the rules while the agent works: what
nd7 allowandnd7 denydo, and when they take effect. - What happens when a command is denied: what the kernel, nd7-exec and the model each say, and how to respond.
Audit log#
- How the audit log works: hooks, entries, where logs live, the lock, and
nd7 verify. - The log format: the envelope, every entry body, the hash chain, and an example.
- Set up nd7 as a Claude Code hook: the settings snippet and which events are recorded.
- Ship sessions to a vault you run:
nd7 ship, the encryption, and what a vault operator can see.
Reference#
- Architecture: components, process model, data flow and trust boundaries.
- Benchmarks: what recording and verifying cost, measured.
- Design decisions (ADRs): one summary per decision record.
- Roadmap: the four phases, what is done, and the honest limits.
Compare#
- How nd7 compares to other ways of sandboxing a coding agent: nd7 beside Claude Code's own sandbox, Codex CLI, containers, gVisor, microVMs and more.
- How nd7 compares to nono: the closest comparable project, side by side.
- Frequently asked questions.
What nd7 is#
nd7 answers one question about an AI coding agent: what did it do? Today the only answer most people have is the agent's own transcript, which is the agent's account of itself. nd7 provides two things instead. A sandbox: nd7 run claude starts Claude Code with a set of rules the macOS kernel applies to it and to every process it spawns, so the agent can write in your project but not in your home directory, and can reach HTTPS but nothing else. An audit log: a small binary registered as a Claude Code hook appends one entry per hook event to a per-session file, each entry carrying a BLAKE3 fingerprint of the entry before it, so no entry can be changed or removed without the chain saying so.
The engine is open source under the MIT licence and written in Rust. It is pre-alpha.
What is built today#
- Kernel sandbox for Claude Code: command
nd7 run claude; state: built, macOS only. - Widen or narrow the rules mid-session: commands
nd7 allow,nd7 deny; state: built, applies to Bash commands. - Record a session from Claude Code hooks: command
nd7 record; state: built. - Check a session's chain: command
nd7 verify <session-id>; state: built. - Ship sessions to a vault you run: commands
nd7 enroll,nd7 ship; state: built on the machine side; the vault is a separate repository.
Recording is intent only. An entry says what Claude Code reported it was about to do and what it reported back, not what the operating system observed. The README and ADR-0001 are explicit about this, and so is the note nd7 verify prints on every success.
What is planned#
From VISION.md, in order:
- Effects from the kernel. Recording what actually happened, using the operating system's own facilities for observing processes and files (Endpoint Security on macOS; fanotify plus seccomp-notify or eBPF on Linux), attributed to the agent's process tree and written into the same log with a
sourceofeffect:*. Planned. - Cross-machine continuity. When an agent connects to another host, that host's nd7 records into the same session. Planned; the
session_idandhostfields exist for it already. - Enforcement derived from recorded sessions. Rules generated from what real sessions actually needed, rather than written by hand. Planned. The hand-written sandbox that exists today is the first piece of this.
- Undo. Reverting file contents first, then service and system state, with an honest account of what cannot be reversed. Planned.
Explicit non-goals for now, from the README: Endpoint Security, undo, remote hosts, a server, a user interface, and a background daemon.
Codex and other agents are planned, not built: the architecture describes a future nd7 record --from codex writing the same entries with a different source, and nothing for Codex exists in the repository today.
Supported platforms and tested versions#
The sandbox is macOS only. nd7 run and nd7-exec print only supported on macOS and exit 2 on any other platform, and the sandbox module is compiled on macOS alone. The README records the sandbox as tested on macOS 26 with Claude Code 2.1.x; the hook that rewrites Bash commands was measured against Claude Code 2.1.278.
Recording, verifying and shipping need no kernel facility and no privileges, and continuous integration runs the test suite on both macos-latest and ubuntu-latest. Linux is described in the README as Tier 2 and not yet built; the sandbox there is planned to use Landlock, the Linux kernel's own sandboxing facility.
The schema is a draft. Frames are written with v: 0, and the repository says fields may change until the schema is marked v1.
Where to get help#
Open an issue at github.com/nd7-dev/nd7-core, or write to info@nd7.dev. The repository's own documents are the source for everything on this site: the README, ARCHITECTURE.md, SCHEMA.md, VAULT.md, DECISIONS.md, BENCHMARKS.md and VISION.md.