Remote Control Handbook

Claude Code Sandboxing for Sessions You Leave Running

Written by

Ravindra Patil

in

Remote Control’s server mode accepts --sandbox, and it is off by default. If you are leaving a session running on a machine you are not watching, that default deserves a decision rather than a shrug. Here is what turning it on actually changes.

Open the panel with /sandbox in any session. It has Mode, Overrides and Config tabs, plus a Dependencies tab on Linux when something is missing.

Platform support first

On macOS there is nothing to install, because the sandbox uses the built-in Seatbelt framework. On Linux and WSL2 it needs two packages:

  • bubblewrap, the unprivileged sandboxing tool that enforces filesystem isolation
  • socat, the relay that routes network traffic through the sandbox proxy

Native Windows is not supported. Run Claude Code inside a WSL2 distribution instead.

The default failure behaviour matters for unattended work: if the sandbox cannot start because a dependency is missing or the platform is unsupported, Claude Code warns and runs commands unsandboxed anyway. Set sandbox.failIfUnavailable to true to make that a hard failure instead.

The two modes

ModeBehaviour
Auto-allowA command that can be sandboxed runs inside it and is approved automatically, with no prompt
Regular permissionsEvery Bash command goes through the normal permission flow even when sandboxed

Both enforce identical filesystem and network restrictions. The only difference is whether sandboxed commands need approval. For a session you are not watching, auto-allow is the point of the exercise.

Even in auto-allow, these still interrupt:

  • Explicit deny rules, always.
  • rm or rmdir targeting /, your home directory, or other critical system paths.
  • Content-scoped ask rules such as Bash(git push *).

What the sandbox actually restricts

Filesystem

  • Writes: the working directory, its subdirectories, and the session temp directory that $TMPDIR points to. Nothing else, including ~/.bashrc and system binaries.
  • Reads: the entire computer, minus a denied set.

Read that second line again. By default the sandbox still allows reading ~/.aws/credentials and ~/.ssh/. Filesystem isolation is about stopping writes, not about hiding secrets. Use sandbox.credentials to block those reads and unset secret environment variables, or add the paths to denyRead.

One useful special case: when the working directory is a linked git worktree, the sandbox permits writes to the main repository’s shared .git directory so git commit still works. Writes to hooks/ and config inside it stay denied.

Network

Traffic goes through a proxy running outside the sandbox, and no domains are pre-allowed. The first time a command needs a new domain, Claude Code asks. Approving allows that host for the rest of the session.

For unattended work this is the thing that will bite you. A prompt for a domain is still a prompt, and a session nobody is watching stops at it. Pre-allow what your build actually needs:

{
  "sandbox": {
    "allowedDomains": ["registry.npmjs.org", "github.com"]
  }
}

The escape hatch, and why it exists

Some commands simply cannot run sandboxed. Rather than failing the task, Claude analyses the failure and may retry with the dangerouslyDisableSandbox parameter. That retry runs outside the sandbox and goes through the normal permission flow, so you get a confirmation prompt in default mode, or a classifier check in auto mode.

If you would rather that never happen quietly, turn it off:

{
  "sandbox": {
    "allowUnsandboxedCommands": false
  }
}

Or keep it but force a prompt every time by adding an ask rule for Bash(dangerouslyDisableSandbox:true).

Turning it on properly

Selecting a mode in the /sandbox panel saves it to .claude/settings.local.json, which applies to that project only. Claude Code adds that file to your global gitignore when it does. For every project, set it in your user settings:

{
  "sandbox": {
    "enabled": true
  }
}

Organisations can enforce it for everyone through managed settings.

Using it with Remote Control

Server mode takes the flag directly:

claude remote-control --sandbox --spawn worktree

Two caveats worth holding onto. The flag is not available with the /remote-control slash command, only with server mode, so a session you converted mid-flight cannot pick it up. And sandboxing is not a substitute for permission mode: they solve different problems, and a sandboxed command can still be one you would rather approve.

For a machine that stays on and hosts sessions you are not watching, the combination worth reaching for is sandbox enabled, domains pre-allowed, and a permission mode chosen deliberately. See always-on machines and the security model.

More posts