# Permissions and the sandbox

> How Kaitoi Code asks before it acts. Trusting a folder, approval cards with diffs, rules you save per project, auto-approve, and the sandbox around commands.

Source: https://kaitoi.io/docs/cli/permissions-and-sandbox/
Section: Kaitoi CLI / Working with Kaitoi Code
Written for: Anyone who wants to know what Kaitoi Code can do on their computer, and how to control it.
Prerequisites: Kaitoi CLI installed
Last reviewed: 2026-10-24

---

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](/docs/cli/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`:

```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](/docs/cli/mcp-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.