Sandbox
Run an agent with its permission checks off without handing it your machine. Ouijit's sandbox limits a command to its task's worktree, and you choose what runs inside it: a whole terminal, a hook, or one command.
Where things run
Each project has a Default under Project Settings → Sandbox: Host, Sandbox, or Custom. Task terminals, hooks, Run, and scripts all run there unless something more specific says otherwise:
- One terminal. Right-click a task and use Resume in. It lists every place, with the default checked. Plain Resume uses the default. When there is only one other place, the item names it, as in Resume in Sandbox.
- One run of a hook. The dialog that appears when you move a task starts on the hook's setting and can change it for that run.
- One Run or script. Run in at the top of a terminal's + menu.
- A hook, every time. Each of start, continue, review, and done has its own setting, which starts on Default. Set it when a hook must always run somewhere else, such as a done hook that pushes with credentials only the host has.
- Part of a command.
ouijit sandbox -- <command>runs just that command in the sandbox, from a host terminal. See below.
A sandboxed terminal carries an outlined status dot and a suffix on its label, and so does a host terminal
while a command started with ouijit sandbox is running. A sandboxed runner's tab dot is
outlined too.
If the chosen sandbox cannot start, the terminal says why and Ouijit raises an error. It never runs the command on the host instead, and a restored terminal whose sandbox is gone fails the same way.
Sandboxing one command
ouijit sandbox runs a single command in the sandbox with the same access its task's terminal
would have, while the rest of the line stays on the host. A start hook can pull on the host and contain only the
agent:
git pull origin main && ouijit sandbox -- claude --dangerously-skip-permissions "$OUIJIT_TASK_NAME"
Add --custom to use the Custom sandbox. The command gets an API token of its own at the
project's CLI access level, never the host terminal's, and loses it when it exits. A host
step that runs after a sandboxed one can still execute files the agent changed, such as tests it edited. The
sandbox protects your machine while the agent works, rather than from what it leaves behind.
The Ouijit CLI inside a sandbox
Set it under Project Settings → Sandbox → Ouijit CLI access. At every level a sandboxed command reaches only its own project, and it edits only the comment drafts a sandbox wrote, never yours:
- Read only, the default. A sandboxed command can read its own task, its diff notes and pull requests, draft pull request and Linear comments, print links to places in Ouijit, and ask you to run a command. On its own terminal it can read the screen, add tags, read panels, and open markdown files from its worktree.
- Its own task. It can also move, rename and describe its own task, link it to a pull request or issue, and add to-do tasks. It can read every sandboxed terminal on its task. Moving a task runs that column's hook as usual, but a hook that would run on the host waits for you to open it, even with
--run-hook. A one-off--hook-commandor--sandboxis refused. - Everything. It can do anything a host terminal can, which includes having Ouijit run commands on the host. Choose this only for agents you would run unsandboxed anyway.
Ouijit's sandbox
Ouijit's sandbox is nono, which runs a command in place on the host worktree under kernel-level access limits (Seatbelt on macOS, Landlock on Linux). It is a kernel access policy on a host process rather than a separate machine, so it starts instantly with no file sync.
What it grants
Filesystem access is limited to the worktree and the repository's git data. .git is read-only
apart from read/write overlays at objects/, refs/, logs/, and
worktrees/, so commits land while hooks/ and config stay read-only.
Ouijit also grants a per-project package cache and keeps its status port reachable, so agent status reports
back even when the network is blocked. All of this is derived from the task at spawn time.
The profile
Everything else is a nono profile file. Each project gets its own, at
~/.config/nono/profiles/ouijit-<project>-<id>.json, written once to extend Ouijit's
base profile, which lets Claude Code, Codex, OpenCode, and Pi sign in and run, and then left to you. Open it
from Sandbox profile in settings to block the network, open ports, or grant folders, in
nono's own profile format. Change… points the project at another profile
file, such as one your team shares, and Reset goes back to the project's own. Profiles live
outside the repository, where a sandboxed agent cannot edit its own permissions.
Requirements
Ouijit bundles the nono binary and the agent packs it uses. There is nothing extra to install.
- macOS. Seatbelt (
sandbox-exec). - Linux. Landlock, which needs kernel 5.13 or newer.
Custom
The Custom backend runs a task's terminals under a launcher you provide: a reviewed script in your team's
control, with its own pinned sandbox binary, committed policy, and preflight checks. Ouijit grants nothing
itself. The launcher owns the boundary. Set the command under Project Settings → Sandbox →
Custom launcher or with ouijit sandbox-command set.
Don't start the launcher by hand from a task terminal. That terminal's OUIJIT_API_TOKEN has
host access and would go into the sandbox with the launcher. An agent inside could then rewrite hooks and
this setting so the next spawn runs on the host. Configure the launcher here, or use ouijit sandbox
--custom -- <command>, which gives the command a sandbox-scoped token of its own.
What Ouijit passes
Ouijit runs <launcher> [args] -- <shell> [shell args] with the working directory set
to the task worktree and the full terminal environment: OUIJIT_API_URL and a
sandbox-scoped OUIJIT_API_TOKEN, OUIJIT_PTY_ID,
OUIJIT_WRAPPER_DIR, OUIJIT_CLI_PATH (when the bundled CLI is present),
OUIJIT_SHELL_INTEGRATION_DIR,
and the shell integration's ZDOTDIR. The launcher's argv is exactly the configured command,
split on whitespace with shell-style quoting. Nothing is expanded except a leading ~/ on the
launcher path, and nothing is added except the -- and the shell.
Everything Ouijit would otherwise have granted is exported as advisory hints. They are computed on the host from the project path and Ouijit's own directories, never from the worktree, and a launcher is free to ignore them.
| Variable | What Ouijit's other backends do with it |
|---|---|
OUIJIT_SANDBOX_WORKTREE | The task worktree, read+write. |
OUIJIT_SANDBOX_GIT_DIR | The repository's .git, read-only. |
OUIJIT_SANDBOX_GIT_WRITABLE_DIRS | Colon-separated objects, refs, logs, worktrees under it, writable so commits land while hooks/ and config stay read-only. |
OUIJIT_SANDBOX_HOOK_PORT | The localhost port that must stay reachable for agent status to report back. |
OUIJIT_SANDBOX_CACHE_DIR | A per-project package-manager cache outside any worktree, read+write. Shared by every task of the project. |
OUIJIT_SANDBOX_WRAPPER_DIR | Ouijit's agent shims and CLI reference, read-only. Its bin/ is first on PATH. |
OUIJIT_SANDBOX_CLI_DIR | The bundled ouijit CLI the shim runs, read-only. Set only when the bundled CLI is present. |
What the launcher is responsible for
- Exec the argv after
--with the inherited environment intact: at leastPATH,ZDOTDIR, everyOUIJIT_*variable,TERM,HOME,SHELL, and the locale. Shell integration, the status dot, and theouijitand agent shims are all carried by the environment. A launcher that scrubs it starts a bare shell. - Own the boundary. Ouijit adds no
--allowor--readflags. - Keep the hook port reachable if you block the network.
- Exit non-zero to refuse. Whatever the launcher wrote to stderr appears in the terminal, the exit line prints red, and Ouijit raises a "sandbox failed to start" notice. Ouijit never falls back to an unsandboxed shell.
Where the launcher may live
An absolute path or a bare name resolved on PATH. Relative paths are refused, and so is any
absolute path inside the worktree or the spawn directory. The sandboxed agent can write there, and a
launcher it can edit is one it can turn off. Keep a versioned launcher in the repo if you like, but install
it from a reviewed checkout to somewhere the sandbox cannot write, such as ~/.local/bin, and
point the setting there. If your PATH contains relative entries, use an absolute path.