Sandbox the agent's shell commands

Prismor's rules decide whether a shell command may run. The sandbox decides what that command, and every process it starts, can touch while it runs. With it on, an allowed npm install can still write to the project, but its postinstall script cannot change your git hooks, your shell startup files, or Prismor's own policy. It cannot read your cloud credentials either. Your OS enforces this: Seatbelt on macOS, bubblewrap on Linux.

This guide turns the sandbox on, shows what it stops when a script misbehaves, and shows what happens when the sandbox cannot start. Each step was recorded in a real Claude Code session.

You'll need

  • Prismor hooked into Claude Code (prismor setup). The fail-closed behavior shown in step 4 ships in the release after 1.78.0.
  • macOS, or Linux with bubblewrap (apt install bubblewrap).

1. Check that the sandbox can start

In the project, run:

prismor sandbox check

PASS means the engine works on this machine. On Ubuntu 23.10 and later, AppArmor blocks bubblewrap by default, and check names the setting. An admin must add an AppArmor profile for /usr/bin/bwrap before the sandbox can start.

2. Turn it on

prismor sandbox on

This sets settings.sandbox.enabled: true and mode: enforce in .prismor/policy.yaml. The next shell command the agent runs is sandboxed. You don't need to restart the agent.

Terminal: prismor sandbox check passes on macOS, then prismor sandbox on writes the setting to .prismor/policy.yaml

prismor sandbox status shows what each part of the sandbox controls:

Terminal: prismor sandbox status shows the sandbox on in enforce mode, with files, credentials and network enforced

ControlWhat the sandbox does
FilesWrites go only to the project, temp dirs and package caches. Git hooks, .git/config, agent and editor config, shell startup files and .prismor are read-only.
CredentialsCloud, registry and Prismor key stores are hidden (~/.aws, ~/.kube, ~/.docker, ~/.npmrc and others).
NetworkHTTP(S) goes through a proxy that checks settings.egress. With the allowlist off, it can reach any host.

To hold commands to an allowlist, turn it on and set it to block:

prismor egress enable
prismor egress default deny
prismor egress allow registry.npmjs.org github.com
prismor egress mode enforce

Terminal: prismor egress enable, default deny, allow registry.npmjs.org and github.com, then mode enforce, which warns that calls outside the policy will now be blocked

Without prismor egress mode enforce, the allowlist only logs hosts that are not on the list. It doesn't block them.

3. See what the sandbox stops

The project in this demo has a setup script, like the postinstall script a dependency can bring. It does one normal thing: it writes dist/config.json. Then it tries five things it should not:

  • read ~/.aws/credentials,
  • write a git hook that runs on your next commit,
  • add a line to ~/.zshrc,
  • edit .prismor/policy.yaml to turn the sandbox off,
  • upload data to example.com.

Start Claude Code as usual and ask it to run npm install:

Press ctrl+o to see the command's full output:

Claude Code detailed view: ok write dist/config.json; four FAILED lines with EPERM operation not permitted for the credentials, git hook, ~/.zshrc and policy file; then "[prismor] sandbox: blocked example.com:443 (not on the egress allowlist)" and curl CONNECT tunnel failed, response 403

The hook saw only npm install, and the policy allowed it. The bad actions came from the script that npm install started, which the hook never sees. The sandbox stopped all five as they ran:

What the script triedWhat stopped it
Read ~/.aws/credentialsCredential stores are hidden: EPERM
Write .git/hooks/pre-commitGit hooks are read-only, even inside the project: EPERM
Add a line to ~/.zshrcShell startup files are read-only: EPERM
Edit .prismor/policy.yaml.prismor is read-only: EPERM
Upload to example.comThe egress proxy refused it with a 403, because the host is not on the allowlist

The write to dist/config.json worked, so the install finished. Afterwards, none of the five files had changed. In this demo, the agent's shell had its own HOME with a fake credentials file, so no real key was at risk on camera.

To try a single command yourself, run prismor sandbox try -- <command>. If the command fails, try tells you which setting to change.

4. When the sandbox can't start, nothing runs

In enforce mode, a command runs inside the sandbox or it does not run. On this Ubuntu machine, AppArmor stops bubblewrap from starting. prismor sandbox on and prismor sandbox status both say so:

Terminal on Ubuntu: prismor sandbox on warns that the sandbox cannot start because AppArmor blocks unprivileged user namespaces, and that agent shell commands are blocked until it can

Now ask Claude Code to run the build:

Claude Code: npm run build exits 126 with "Prismor sandbox: BLOCKED ... Nothing ran", and Claude tells the user what to run in their own terminal

The command is blocked, and nothing runs. The message tells the agent to stop and report, and tells you which two commands fix it. Prismor blocks the same way when:

  • the engine is missing or fails to start,
  • the OS has no sandbox (Windows),
  • the agent already runs inside its own sandbox, and Seatbelt can't nest inside it,
  • the agent's hooks can't rewrite a command (Codex and Qwen Code without PRISMOR_REWRITE_AUTO_APPROVE=1, Copilot CLI, OpenCode).

A bare cd and read-only commands such as prismor status still run, so the agent can help you find the cause.

5. The agent can't turn it off

Only a person can turn the sandbox off. Even when you tell the agent to do it, it can't:

Claude Code declines to run prismor sandbox off itself and tells the user to turn it off in their own terminal

Claude declined on its own here. If an agent tries anyway, three things stop it:

  • The prismor-self-edit rule blocks prismor sandbox off in any form: sudo, python -m, bash -c, eval and script included.
  • prismor sandbox off needs a terminal. An agent's shell has none. A ! command typed into Claude Code has none either, so it is refused too:

Claude Code: "! prismor sandbox off" is refused with "prismor sandbox off needs a terminal. Run it yourself, not through an agent"

  • Inside the sandbox, .prismor/ is read-only, so a command can't edit the policy file.

6. Turn it off yourself

Open a separate terminal window, outside the agent session, and run:

prismor sandbox off

Terminal: prismor sandbox off turns the sandbox off; commands now run unconfined, while policy screening, egress and cloaking still apply

Commands then run without the sandbox. Policy rules, egress and cloaking still apply. prismor sandbox on turns it back on, and keeps any ring or paths you set.

The whole flow on the Ubuntu machine, from turning the sandbox on to turning it off:

If you want to let an agent change the setting, open a short window with prismor unlock. It asks for your Prismor password.


Tune it

All settings live under settings.sandbox in .prismor/policy.yaml:

settings:
  sandbox:
    enabled: true
    mode: enforce        # observe: run unconfined when the sandbox can't start
    ring: "2"            # 0 read-only/no network · 1 no network · 2 egress proxy · 3 open network
    writable: [~/.cache/my-tool]
    hide: [~/.ssh]
  • A ring sets the network mode and whether the project is writable. Fields you set yourself override the ring.
  • writable adds paths a command may write. hide adds paths a command may not read.
  • mode: observe keeps the sandbox where it can start, and runs commands without it where it can't. Use it on machines where you can't install an engine, such as Windows, or with agents that can't rewrite commands.

See Prismor Sandbox for the full reference.