docs blog library
github

Write confinement

Write confinement is an operating-system fence under execute_command and the write_file, edit_file, create_pdf and the rm, mv, cp and mkdir tools. With it on, a command can write only inside:

  • the session’s working directory;
  • when the working directory is inside a git repository, the repository’s top-level directory, so git add and git commit work from a subdirectory. For a linked worktree or a submodule, its git directory and the shared main .git are included too. A repository whose top level is your home directory or above it is ignored;
  • Jazz’s scratch directory (~/.jazz/workspace);
  • temp directories ($TMPDIR, /tmp, /var/tmp);
  • developer tool caches: ~/.cache, ~/.bun, ~/.npm, ~/.pnpm-store, ~/.yarn, ~/.cargo/registry, ~/.cargo/git, and ~/Library/Caches on macOS.

Everything else on disk stays readable and unwritable. Reads and the network are not confined. The rest of your home directory, including ~/.ssh, shell startup files and ~/.jazz itself, cannot be written by a confined command. Confinement covers file writes only: it does not stop a command from sending data over the network.

When it is on

Surface Default
Interactive chat with a person at the terminal off
jazz run in a terminal where its questions reach you off
jazz run piped, in CI or cron; bridge bots (Telegram, Discord, iMessage, WhatsApp) on
Peers, webhooks, goals, loops, daemon work on

The rule is whether a person is at the terminal who can type continue: when nobody is, the fence is on. Set shell.confinement in your global config to choose the mode yourself:

{ "shell": { "confinement": "on" } }

off is the only value that lets commands run unconfined. The project layer is applied after the global one: a project’s .jazz/config.json can turn confinement on even when your global config says off, but a project off is ignored (Jazz says so), so a project can only add the fence.

What Jazz needs from the machine

Platform Backend Needs
macOS /usr/bin/sandbox-exec Nothing to install.
Linux bwrap (bubblewrap) apt install bubblewrap and user namespaces.
Windows none Run Jazz in WSL, or set shell.confinement to off.

Jazz runs a real command under the backend once per process and reports what held:

  • full: a write outside the roots was refused and a write inside succeeded.
  • partial: confinement holds with a named gap. On Linux hosts whose kernel refuses a private /dev, device nodes under /dev stay writable.
  • none: no backend, or one that did not refuse the outside write.

When confinement is on and the level is none, commands are refused, not run unconfined. The message says why and what to install, or that shell.confinement: "off" is the way to opt out. The level appears in /info.

When a command is denied

A write outside the roots fails with Operation not permitted (macOS) or Read-only file system (Linux). Jazz recognizes it only when the command exited non-zero, a stderr line ends in one of those texts, and the path on that line lies outside the roots. The result then carries confinement.deniedPath and tells the model it may retry that exact command once with escalate set to a reason.

The retry goes through the approval prompt, which shows the denied path and the reason and is asked even when a policy would auto-approve the command. Approving runs that one call unconfined. Nobody is asked on a surface with no one to answer, so the model is told to write inside the roots instead. A command can be escalated once; a command that was never denied cannot be escalated.

The file tools do not escalate: a path outside the roots is refused with the roots named.

Limits

  • The fence covers writes, not reads or the network.
  • The file tools (write_file, edit_file, create_pdf, rm, mv, cp, mkdir) check their paths in-process. Each resolves the target’s real path, mutates that path rather than the original string, and re-checks the directory it relies on (its identity and that it is not a symlink) as the last step before the mutating call, refusing if it changed. Node and Bun have no openat or no-follow primitives, so a window of a few microseconds remains between that check and the syscall. Closing it needs a process that can swap a directory in that gap while a tool call runs: the realistic one is a confined shell command racing a file-tool call in the same batch. The confined shell itself cannot escape, because the operating system confines it.
  • manage_scratchpad writes only under Jazz’s own scratch directory, which is a writable root, so it needs no separate check.
  • Commands the daemon runs from a wait_for job and the operator’s ! escape run unconfined.
  • sandbox-exec is deprecated by Apple but ships on every supported macOS.
  • Linux support needs bwrap and unprivileged user namespaces; hosts without them report none.
  • Seatbelt and bwrap enforce at the kernel, so a command cannot lift the fence from inside; a process that is not a child of the command (a daemon you started earlier) is not fenced.

machine-readable: /jazz/docs/security/write-confinement.md · /llms.txt · /llms-full.txt