Run Code in Sandbox

The sandbox executor runs arbitrary code inside isolated containers (Docker or Podman) so agents can compute results, run tests, and execute scripts without risking the host system.

Tip

New to sandboxing? Read Sandboxing — Concepts first for the two-systems model, the file/mount model, and platform support. This page is the configuration walkthrough.

Configuring the sandbox

1. Open the Sandbox page from the Infrastructure section of the sidebar

2. Pick an Isolation Profile (the primary control):

   • Off — All commands run on the host. For fully trusted local dev.
   • Safe (default) — Host by default; risky commands auto-containerize based on a risk score, and arbitrary code (run_code) is always containerized. For everyday agent work.
   • Strict — Every command Snippbot runs (run_code, bash from API-model and claude-native agents (with the default contain gate), tool steps) is containerized, with no network. For untrusted code or shared machines.

   Advanced settings below the profiles fine-tune any field; changing one shows the profile as Custom.

3. Choose the scope mode (under Advanced):

   • SESSION — One container per conversation session, reset between sessions
   • AGENT — One container per agent, persists across sessions
   • SHARED — All agents share a single container (for collaboration workflows)

4. Set workspace access level:

   • NONE — Container has no access to agent workspace
   • RO — Container can read workspace files but not write
   • RW — Container can read and write workspace files

5. Save your settings

Expand

Resource limits

Each sandbox instance has configurable resource limits. On the Sandbox page, you can set the following per-instance limits:

Setting	Description
CPU Cores	Number of CPU cores allocated to the container
Memory (MB)	Maximum memory in megabytes
Disk (MB)	Maximum disk space in megabytes
Max Processes	Maximum number of concurrent processes
Timeout (seconds)	Maximum execution time before the container is killed

How agents use the sandbox

You don’t invoke the sandbox explicitly — for the paths Snippbot’s own tool executor runs, it’s automatic. Agent-generated code (run_code) is always containerized in Safe/Strict, and bash from API-model agents honours the profile. Ask the agent to write a Python script that processes a CSV and plots the result, and in Safe/Strict it runs in a container, writes the plot to a writable scratch dir, and the file is copied back so it renders inline in chat — your project files are untouched unless workspace access is rw.

claude-native agents honour the profile too

Agents whose model is the Claude CLI (claude-native:*) have their Bash governed by the Claude-native Bash setting (claude_native_bash_gate, default contain): with contain it routes through the sandbox exactly like API-model bash; with gate it is allowed/denied on the host per profile; with off it runs on the host (legacy). Installed marketplace tools (custom_python) are untrusted code — under any non-Off profile they are blocked rather than run on the host (containerized execution is a follow-up). The Sandbox page’s “Where commands run” panel states this per path.

Project mode is host-only

This applies to chat and workflow execution. Project-mode task execution runs on the host by design (the agent needs to write to your project and run at host speed), so the profile does not apply there. The Sandbox page’s “Where commands run” panel shows this for every context.

Expand

The Logs tab tracks every sandboxed command with exit codes, duration, and security scores.

For explicit control, you can direct the agent:

Example prompt: “Run this in an isolated container and give me the output”

Example prompt: “Execute the test suite in the sandbox and show failures”

Example prompt: “Run this script in a clean container so it can’t touch my files”

Language runtimes and the image

Whatever the container image provides is what the sandbox can run. The image is set once by the Default Image field (and by adopting a Template), not chosen per prompt — the base image ships Python and Node, and you can point at a custom image or add setup commands for other toolchains (Go, Rust, Ruby, …).

So the effective way to “use Python 3.12” is to configure an image that has it, not to ask for a version in the prompt.

Network policy

Network access is a flat, per-config setting — not tied to permission tiers:

• Network Enabled — master switch for outbound access. This is the part that’s enforced: on ⇒ the container gets bridge networking; off ⇒ no network.
• Allowed / Blocked Domains — captured for a future release; host-level domain filtering is not yet enforced, so today the switch is all-or-nothing.

Safe and Off enable the network by default; Strict disables it for maximum containment (no outbound access at all).

Caution

Per-domain allow/block lists are recorded but not currently enforced — only the on/off switch is wired. For guaranteed no-exfiltration, use Strict (or turn Network off), which gives the container no network namespace access.

Persistence and dependencies

With scope = session or agent, the same container is reused across commands, so software you install into it (e.g. pip install pandas) persists for the life of that container.

Note

This is about the container’s own filesystem, not your project. With the default read-only workspace the agent’s working directory is a writable scratch space; files it creates there are copied back to the conversation. Install once, reuse within the session — but note a fresh session container starts clean.

Requirements

• Docker ≥ 24 or Podman ≥ 4.x installed and running on the host
• The Snippbot daemon process needs socket access (/var/run/docker.sock)

To check whether a runtime is available, look at the runtime-status banner at the top of the Sandbox page (it shows live / not-running / not-installed and, in Safe/Strict without a runtime, a surfaced “running unsandboxed” warning).

Note

The sandbox does not require root privileges. Snippbot uses rootless containers by default.

Platform support

• macOS / Linux — Docker or Podman work natively (macOS via a Linux VM).
• Windows — container sandboxing requires Docker/Podman through WSL2; the daemon must run inside WSL2 and mount paths must be WSL2-visible (native C:\... paths are translated automatically). Without WSL2 there is no effective sandbox on Windows — the banner says so rather than silently running unprotected.

See Sandboxing — Concepts → Platform support for the full matrix (including the OS-level fence and GPU passthrough).

When to use each profile

Use Off for:

• Fast, trusted scripts and read-only file operations in a well-tested dev setup.

Use Safe (default) for:

• Everyday agent work — risky commands and all run_code are contained, the rest runs at host speed.

Use Strict for:

• Running untrusted or generated code, data processing with external inputs, and shared or production machines.

Troubleshooting

Docker not found

If the system health panel in Monitor shows Docker as unavailable, install Docker from docker.com/get-started (or via Homebrew on macOS).

Permission denied on docker.sock

Add your user to the docker group on Linux, then log out and back in. On macOS with Docker Desktop, ensure Docker Desktop is running.

Container out of memory

Increase memory limits on the Sandbox page by adjusting the Memory (MB) setting.