Permissions and the sandbox.

Kaitoi Code checks workspace trust, mode, permissions and any applicable saved approval before acting. A tool may run under a prior grant, ask for approval, or be refused. Local file reads inside a trusted workspace normally do not ask; external tools and sensitive actions have their own rules. This page explains those controls and what keeps an approved command contained.

#Trusting a folder

Code works inside one folder, its workspace. When a session starts, Code asks whether you trust the folder:

• Yes, I trust this folder turns on the local file tools inside it, the project's instructions, skills and commands, and the Crew.
• No local file access keeps the session away from your files. This is the default answer.

Code never reads or writes outside the trusted folder with its file tools. /workspace <path> switches to another folder and asks again, and /workspace alone shows the current one.

For a headless run, name the folder and how far to trust it:

• --trust-workspace-read-only allows reading only.
• --auto-approve-edits also approves file writes and edits. It does not grant deletes, moves, commands or transfers; other applicable saved approvals remain independent.
• --auto-approve lets a reviewer model approve routine actions, below.

#Approval cards

When an action needs approval, Code shows a Permission needed card with what it wants to do. For a file edit, the card names each file with its added and removed line counts and shows the diff, cut to fit your terminal; press v to see the whole diff.

Most cards offer:

• Allow once (a): do it this one time.
• Always allow this operation (s): allow this kind of action for the rest of the session.
• Deny (d): refuse it. Code is told it was declined.

A few cards only ever allow once, because each one costs money or starts something you should see: a media generation shows its price, and a Crew run or a background agent shows exactly what will happen.

#Rules you save for a project

A command card can also offer Always allow npm test in this project (p). That saves a rule: later sessions in this project, headless ones included, run that command with any arguments without asking. For a program Code does not know, the card first offers the exact command, then the same program with any arguments.

• A rule saved without network access does not cover the same command when it asks for the network.
• Some commands can never be remembered, such as ones that delete files, and the card says why.
• Rules are kept with your Kaitoi Code settings, not in the repository, so a repository cannot add rules for itself.

/permissions lists the session's approvals and this project's saved rules. /permissions remove 2 removes rule 2, /permissions clear clears the session's approvals, and /permissions clear project removes this project's saved rules.

#Auto-approve

/auto on, or kaitoi code --auto-approve, lets a cheap reviewer model approve routine actions for you, so a long task does not stop at every step. It is never saved: each session starts with it off. /auto off turns it off.

Some actions are never approved this way, whatever the reviewer says. Among them: anything that spends credits, Crew runs, MCP tool calls you have not allowed, changes through Kaitoi's built-in MCP server, starting a Claude Code or Codex agent, uploading your files to Kaitoi, and any command that runs outside the sandbox or that Code cannot check. In a terminal those still show the card; a headless run denies them. Each decision is logged, and /cost shows what the reviewer's checks cost. The autoApprove section of agent.json chooses the reviewer model.

#Kaitoi's own files

Code's tools refuse Kaitoi's own settings, your login, saved sessions and MCP data, even when the trusted folder contains them, such as when you trust your home folder. Those folders are also left out of listings and searches.

#The command sandbox

/commands on and /commands off control the model's command tools. On macOS and Linux, those tools run commands inside an operating system sandbox when one is available (see the table below):

• it can write only inside the workspace and temporary folders;
• it cannot read credentials, Kaitoi's settings or .env-style secret files;
• it has no network access unless the command asks for it, and the card says when it does.

System	Sandbox
macOS	Built in (Seatbelt).
Linux	Bubblewrap, which must be installed, on a system that allows unprivileged user namespaces.
Windows	None yet.

The session banner, /status and /doctor say whether the sandbox is on and why not when it is off.

An explicit operator command entered with /cmd runs outside this sandbox and the model's approval flow. It is independent of /commands and Plan mode; see Commands and processes.

A command can run for up to 10 minutes. Inside the sandbox it can be a full shell line, with pipes and &&. Without a sandbox, a command must be a single program with its arguments, no shell, and the card warns that it runs with your full permissions. Code keeps a bounded output log for the session, so it can read back more than the initial preview without rerunning the command. Saved output is capped at 20 MiB; a storage failure can leave only the output tails. Check the reported truncation and storage status before treating a log as complete. Esc stops a running command and what it started: on macOS and Linux they are first asked to stop and get a short grace period. A program that detached itself, such as a daemon in its own session, keeps running on macOS and on Linux without the sandbox. In the Linux sandbox it is ended when the command ends.

#Adjusting the sandbox

In the sandbox section of agent.json:

{
	"sandbox": {
		"mode": "auto",
		"extraWritablePaths": ["~/data/exports"],
		"extraDeniedReadPaths": ["~/clients"]
	}
}

• extraWritablePaths adds folders commands may write to.
• extraDeniedReadPaths adds folders commands may not read.
• "mode": "off" turns the sandbox off. Commands then run with your full permissions, so only do this when something you need cannot run inside it.

#When a command fails in the sandbox

• On macOS, a command that writes to /tmp by name fails, because the writable temporary folder is your own. Most tools use the right one on their own.
• Git cannot write a repository whose .git folder is outside the workspace, such as a linked worktree. Open the repository's main folder, add the .git folder to extraWritablePaths, or turn the sandbox off.
• Some macOS tools need more than the sandbox allows, such as GPU work, xcodebuild or keychain credential helpers. Turn the sandbox off for them.
• Inside a Docker dev container, the sandbox needs the container started with --security-opt systempaths=unconfined.
• Package caches are kept per session inside the sandbox, so some downloads happen again in a new session.

Hooks you write yourself are your own automation and run outside the sandbox: see MCP servers, skills and commands.

#Current limitations

• Windows has no command sandbox yet.
• In the Linux sandbox, anything a command or a background process leaves running when it exits is ended at once, a program that detached itself included. On macOS, or on Linux without the sandbox, what a background process leaves running is first asked to stop and gets a short grace period, apart from a program that detached itself, such as a daemon in its own session, which keeps running.
• A saved rule is a convenience, not a security boundary. The sandbox is what limits what an approved command can reach.