Sandboxing

Run CrabCode inside an OS sandbox to constrain which files it can write and which network it can reach.

What it is

A sandbox is OS-level process isolation. With it on, even a malicious command can't cross the allowed file/network boundary — a layer below the app-level permission prompts.

Platform support:

When to use it

• Before running scripts from an unfamiliar repo, turn it on with /sandbox
• Long-running on shared CI runners or multi-tenant machines
• When an untrusted MCP server is calling file ops

Enable and configure

Interactive menu:

/sandbox

/sandbox

Or in settings.json:

{
  "sandbox": {
    "enabled": true,
    "autoAllowBashIfSandboxed": true,
    "excludedCommands": ["npm run test:*"],
    "network": {
      "allowedDomains": ["api.github.com", "*.npmjs.org"],
      "allowUnixSockets": ["/var/run/docker.sock"]
    }
  }
}

{
  "sandbox": {
    "enabled": true,
    "autoAllowBashIfSandboxed": true,
    "excludedCommands": ["npm run test:*"],
    "network": {
      "allowedDomains": ["api.github.com", "*.npmjs.org"],
      "allowUnixSockets": ["/var/run/docker.sock"]
    }
  }
}

Fields:

• enabled — master switch. When true, every Bash tool call goes through the sandbox
• autoAllowBashIfSandboxed — auto-approve Bash permission prompts when the sandbox is on (the OS boundary already covers it)
• excludedCommands — command patterns to keep outside the sandbox (e.g. dev servers that need host access). Use /sandbox exclude "<pattern>" to add incrementally
• network.allowedDomains — network allow-list; matches by domain, bare-IP isn't covered
• network.allowUnixSockets — Unix socket allow-list

Enterprises can set sandbox.enabledPlatforms (e.g. ["macos"]) in policy settings to restrict sandbox to specific platforms.

Default allowed

When the sandbox is on, with or without overrides, these are always permitted:

• Read and write the cwd plus any additionalDirectories
• Read system binaries and the standard library
• Read this process's temp directory
• Reach the acosmi gateway and your configured MCP servers

Everything else (writes, network) is denied by default.

Excluding a command

Some commands must run on the host (e.g. spawning a GUI debugger):

/sandbox exclude "vite preview"

/sandbox exclude "vite preview"

This writes to the project's settings.local.json under sandbox.excludedCommands.

Limits and caveats

• Dependency check — /sandbox scans for required platform tools on first enable and shows install hints if anything is missing
• macOS — a few syscalls (e.g. GUI automation) can still escape; don't treat the sandbox as the only line of defense
• Linux — required tools vary by distro; the menu lists what's needed
• Windows Sandbox is an optional feature on Windows 10/11 Pro/Enterprise; CrabCode guides you through enabling it on first use
• Permission mode and the sandbox are independent — app-level bypassPermissions doesn't disable the OS-level sandbox (it still blocks what it would block)
• WSL — WSL2 only; WSL1 lacks the kernel capability

Related

• security
• iam