Claude Code sandbox-runtime configuration experiments (Docker support)

0-CLAUDE-SANDBOX-RUNTIME-CONFIGURATION-EXPERIMENTS.md

Claude Code Sandbox Configuration Experiments

Experimenting with sandbox-runtime configuration for Claude Code on Linux.

Goals

• Enable sandbox per-project using /sandbox command in Claude Code CLI
• Allow Docker commands to run unsandboxed (so containers work)
• Allow sandboxed commands to communicate with Docker via /var/run/docker.sock

Quick Setup

1. Install sandbox-runtime

# Check if installed
which srt

# If not, install : https://github.com/anthropic-experimental/sandbox-runtime/

2. Global Claude settings (~/.claude/settings.json)

Add sandbox defaults that will be inherited when /sandbox is enabled per-project:

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "permissions": {
    "allow": [],
    "deny": []
  },
  "sandbox": {
    "excludedCommands": ["docker", "docker-compose"],
    "allowUnsandboxedCommands": true,
    "network": {
      "allowUnixSockets": ["/var/run/docker.sock"]
    }
  }
}

Note: We intentionally omit enabled and autoAllowBashIfSandboxed here - these get added per-project by /sandbox.

3. Sandbox-runtime settings (~/.srt-settings.json)

Fine-grained control over what the sandbox allows:

{
  "network": {
    "allowedDomains": ["github.com", "*.github.com", "registry.npmjs.org"],
    "deniedDomains": ["malicious.com"],
    "allowUnixSockets": ["/var/run/docker.sock"],
    "allowLocalBinding": false
  },
  "filesystem": {
    "denyRead": ["~/.ssh"],
    "allowWrite": [".", "/tmp"],
    "denyWrite": [".env"]
  },
  "enableWeakerNestedSandbox": false
}

4. Enable per-project

In Claude Code CLI, type /sandbox to add to $PROJECT/.claude/settings.json:

{
  "sandbox": {
    "enabled": true,
    "autoAllowBashIfSandboxed": true
  }
}

How Settings Merge

~/.claude/settings.json      (global defaults)
        +
.claude/settings.json        (project overrides via /sandbox)
        =
Final sandbox configuration

References

• Claude Code Sandboxing Blog Post
• sandbox-runtime Repository

Status

Experimental - Testing whether this configuration approach works as expected.

1-claude-settings-global.json

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "permissions": {
    "allow": [],
    "deny": []
  },
  "sandbox": {
    "excludedCommands": ["docker", "docker-compose"],
    "allowUnsandboxedCommands": true,
    "network": {
      "allowUnixSockets": ["/var/run/docker.sock"]
    }
  }
}

2-claude-settings-project.json

{
  "sandbox": {
    "enabled": true,
    "autoAllowBashIfSandboxed": true
  }
}

3-srt-settings.json

{
  "network": {
    "allowedDomains": ["github.com", "*.github.com", "registry.npmjs.org"],
    "deniedDomains": ["malicious.com"],
    "allowUnixSockets": ["/var/run/docker.sock"],
    "allowLocalBinding": false
  },
  "filesystem": {
    "denyRead": ["~/.ssh"],
    "allowWrite": [".", "/tmp"],
    "denyWrite": [".env"]
  },
  "enableWeakerNestedSandbox": false
}