DOCSEARCHbyAlgolia
Submit Docs

Anthropic Sandbox Runtime (ASRT)

repository·main·Indexed 26 days ago

https://github.com/anthropic-experimental/sandbox-runtime

A general-purpose tool for wrapping security boundaries around arbitrary processes at the OS level. ASRT enforces filesystem and network restrictions to enable safer AI agents and MCP servers without requiring full containers. It provides a CLI tool (`srt`) and a TypeScript/JavaScript library via the `SandboxManager` class to programmatically manage sandboxing environments.

Tokens
8.6K
Snippets
15
Records
54
Agent score
90%

What's inside Anthropic Sandbox Runtime

  2. Set up the Anthropic Sandbox Runtime on Windows (alpha)

    main

    Windows support is in alpha. The sandbox runs under a dedicated srt-sandbox local user account. To provision the account, local groups, and Windows Filtering Platform (WFP) egress fences, run the following command once per machine. This requires elevation (UAC prompt).

    npx @anthropic-ai/sandbox-runtime windows-install

    This command is idempotent. After installation, SandboxManager.initialize() and the srt CLI will function normally. No logout is required as the WFP filters key on the dedicated sandbox account's SID, leaving your own user session unaffected.

  3. Configure TLS termination on Windows

    main

    When using network.tlsTerminate on Windows, the MITM CA must be installed in the sandbox user's CurrentUser\Root certificate store (schannel). This is a separate step from the initial Windows setup.

    You can use the windowsTrustCa function or the CLI helper to install the certificate:

    import { windowsTrustCa } from '@anthropic-ai/sandbox-runtime'
windowsTrustCa('/path/to/mitm-ca.crt')

    CLI equivalent:

    srt-win user trust-ca <path>

  4. Uninstall the Anthropic Sandbox Runtime on Windows

    main

    To remove the srt-sandbox account, the sandbox-runtime-users group, and the WFP filter set, run the following command (requires elevation):

    npx @anthropic-ai/sandbox-runtime windows-uninstall

    Note: The %LOCALAPPDATA%\sandbox-runtime\state.db file is left behind with broker-only permissions. Delete the directory manually for a complete removal.

  5. Use the srt CLI to sandbox commands

    main

    The srt command wraps any command with security boundaries. By default, it uses a secure-by-default philosophy where network access is denied unless domains are explicitly allowed, and write access is denied unless paths are explicitly allowed.

    Common CLI flags:

    • --debug: Enables debug logging.
    • --settings <path>: Specifies a custom settings file instead of the default ~/.srt-settings.json.
    # Run a command in the sandbox
srt echo "hello world"

# With debug logging
srt --debug curl https://example.com

# Specify custom settings file
srt --settings /path/to/srt-settings.json npm install

  7. Install platform-specific dependencies for Anthropic Sandbox Runtime

    main

    Depending on your operating system, you must install specific dependencies to enable sandboxing features like containerization and path detection.

    Linux

    Requires bubblewrap (container runtime), socat (socket relay), and ripgrep (path detection).

    Ubuntu/Debian:

    apt-get install bubblewrap socat ripgrep

    Fedora:

    dnf install bubblewrap socat ripgrep

    Arch:

    pacman -S bubblewrap socat ripgrep

    Note for Ubuntu 24.04+: These releases may restrict unprivileged user namespaces by default. To allow bubblewrap and seccomp isolation to function, disable the restriction:

    sudo sysctl -w kernel.apparmor_restrict_unprivileged_userns=0

    Optional (for seccomp fallback on non-x86-64/arm architectures): If pre-generated seccomp filters are unavailable for your architecture, install a C compiler and seccomp development files:

    • Ubuntu/Debian: apt-get install gcc libseccomp-dev
    • Fedora: dnf install gcc libseccomp-devel
    • Arch: pacman -S gcc libseccomp

    macOS

    Requires ripgrep for deny path detection.

    brew install ripgrep

    Windows

    No additional dependencies are required. The srt-win.exe helper is bundled with the npm package, but a one-time elevated installation is required.

  8. Configure Unix Socket Restrictions on Linux

    main

    On Linux, the sandbox uses seccomp BPF to block the creation of AF_UNIX sockets to prevent unauthorized local IPC.

    If you are on an unsupported architecture (not x64 or arm64) or specifically need to allow Unix domain sockets, set allowAllUnixSockets: true in your configuration.

  9. Configure Unix Socket access

    main

    Unix sockets are blocked by default. Behavior varies by platform:

    SettingmacOSLinux
    allowUnixSockets: string[]Allowlist of socket pathsIgnored
    allowAllUnixSockets: booleanAllow all socketsDisable seccomp blocking
    • macOS: Specify paths in allowUnixSockets (e.g., ["/var/run/docker.sock"]) or set allowAllUnixSockets: true to allow all.
    • Linux: Uses seccomp filters. If seccomp is unavailable, sockets are unrestricted with a warning. Use allowAllUnixSockets: true to explicitly disable blocking.

  10. Configure Windows-specific sandbox settings

    main

    In addition to cross-platform filesystem and network configurations, Windows provides specific settings under the windows key:

    • windows.proxyPortRange: An inclusive [low, high] port range for the JS proxies. This must match the range used during windows-install (default is [60080, 60089]).
    • windows.sublayerGuid: The WFP sublayer GUID used for filters. Omit to use the default.
    • windows.srtWin.path: The path to the srt-win binary. Omit to use the bundled version. Use this when embedding srt-win's CLI into a custom binary.

  11. Configure srt restrictions via ~/.srt-settings.json

    main

    You can define persistent sandbox restrictions in a ~/.srt-settings.json file. This is particularly useful for sandboxing MCP servers by setting the command to srt and passing the server command as arguments.

    Filesystem Logic:

    • Read (denyRead / allowRead): Uses a deny-then-allow pattern. By default, read access is allowed everywhere. allowRead takes precedence over denyRead.
    • Write (allowWrite / denyWrite): Uses an allow-only pattern. By default, write access is denied everywhere. You must explicitly allow paths. denyWrite takes precedence over allowWrite.

    Network Logic:

    • Network (allowedDomains / deniedDomains): Uses an allow-only pattern. By default, all network access is denied. You must explicitly allow domains in allowedDomains.
    {
  "filesystem": {
    "denyRead": [],
    "allowWrite": ["."],
    "denyWrite": ["~/sensitive-folder"]
  },
  "network": {
    "allowedDomains": [],
    "deniedDomains": []
  }
}

  12. Configure Network restrictions

    main

    SRT uses an allow-only pattern for network access; all network access is denied by default.

    Network Options

    • network.allowedDomains: Array of allowed domains. Supports wildcards (e.g., *.example.com) and optional port suffixes (e.g., api.example.com:443). An empty array denies all network access.
    • network.deniedDomains: Array of denied domains. These are checked first and take precedence over allowedDomains. Supports wildcards and port suffixes. A bare * or *:22 acts as a deny-all.
    • network.allowLocalBinding: Boolean (default: false). If true, allows binding to local ports.

    TLS Termination (Experimental)

    When network.tlsTerminate is enabled, HTTPS CONNECTs are terminated in-process to allow request filtering via network.filterRequest.

    • network.tlsTerminate.excludeDomains: Domain patterns that are not terminated. These are tunneled opaquely. Use this for mTLS upstreams or certificate-pinning clients.
    • network.tlsTerminate.extraCaCertPaths: Paths to PEM CA certificate files to append to the trust bundle. This ensures tools inside the sandbox can verify internal or custom CAs.
    {
  "network": {
    "allowedDomains": ["*.example.com", "internal-mtls.example.net"],
    "deniedDomains": [],
    "tlsTerminate": {
      "excludeDomains": ["internal-mtls.example.net"],
      "extraCaCertPaths": ["/etc/internal-mtls-roots.pem"]
    }
  }
}