Sandboxes

A sandbox is a Linux machine next to a sleeve on its Dock, where the sleeve clones repositories, changes code, builds it and runs its tests. It is how a sleeve works as a developer, a tester or a reviewer. The sleeve drives it through tools (run a command, read and edit files, search, clone, pull and push), and code from a project only ever runs in the sandbox, never in the sleeve that holds your model key.

Sandboxes need Dock 0.6 or newer. To update a Dock, run its install command again.

Add a sandbox

In a stack's form on the Specs page, open Sandboxes and press Add a sandbox, or add a sandboxes list to the YAML:

sandboxes:
  - name: dev
    cpus: 4
    memoryMb: 8192
    git:
      - { host: github.com, secretRef: github-token }

The Developer (sandbox) template starts a stack with one sandbox named dev and a prompt for coding work.

Field	Default	Meaning
`name`	required	Lowercase letters, digits and dashes. Its tools are named `<name>__run`, `<name>__git_clone` and so on, so it must differ from your MCP servers' names.
`cpus`	2	0.5 to 8.
`memoryMb`	4096	512 to 16384.
`internet`	true	`false`: the sandbox reaches nothing but its sleeve, so it cannot clone, push or install packages.
`commandTimeoutSeconds`	600	The longest one command may run, 10 to 1800.
`git`	none	The key that clones and pushes for each host (below).
`tools`	all	Only these of its tools, for example `[run, read_file, search, git_clone]` for a sleeve that only reads and tests.

A stack can have up to three sandboxes. Each keeps its files (/work) across restarts, resleeves and new versions of the spec. Removing the sandbox from the spec, or the stack from its Dock, stops it and keeps its files on the Dock's disk.

Its tools

Tool	What it does
`run`	Runs a shell command in `/work` (or a folder under it) and returns the exit code, the duration and the output (the last 30,000 characters).
`read_file`, `write_file`, `edit_file`	Read a file with line numbers, create or replace one, or replace an exact piece of text in it.
`list_files`, `search`	A folder's tree, and a ripgrep search of the files.
`git_clone`	Clones a repository over https into `/work/<name>`, using the key for its host. Commits get the sleeve's name and address.
`git_pull`, `git_push`	Fetch and fast-forward the current branch; push a branch and set its upstream. The sandbox never force-pushes.
`status`	Its limits, disk use, installed tools and cloned repositories.
`wipe`	Deletes everything in `/work` (it asks for `confirm: "wipe"`).

Branches, commits, diffs and logs need no special tool: the sleeve runs git switch -c, git commit and git diff with run. Every process a command starts stops when it ends, so a sleeve that tests a web server starts it and calls it in the same command.

Git keys

Public repositories clone without a key. To clone private repositories or push, add a key:

Make a token at the host with access to the repositories the sleeve should work on. On GitHub, a fine-grained personal access token limited to those repositories, with Contents: read and write (and Pull requests: read and write if the sleeve opens pull requests).
On the Keys page, choose Token for an MCP server or tool, name it (for example github-token) and paste it. Your browser seals it to your Docks.
In the sandbox's Git keys, pick the host and the key.

The key reaches only the sandbox's git steps: clone, pull and push run as their own user on copies of the repositories that commands cannot change, so code from a project (its install scripts and tests) can never read the key. Pull requests are opened with the GitHub MCP server and the same key.

What is installed

Python 3.12 with uv, Node.js 24 with npm and npx, git, gcc and make, ripgrep, jq, curl, zip. Commands run as the user dev without root, so they install other tools for that user, and those stay in /work:

curl -sSL https://dot.net/v1/dotnet-install.sh | bash -s -- --channel 10.0      # .NET
curl -sSL https://go.dev/dl/go1.25.0.linux-amd64.tar.gz | tar -xz -C ~/          # Go

Isolation

A sandbox is its own container with the limits above, no root, a read-only system and a process limit.
It shares a private network with its sleeve only. It never reaches your Dock's message bus, other sleeves or their sandboxes.
With internet on, it reaches the internet the way the Dock's machine does, including your local network. Keep that in mind on a machine next to private services; an outbound allowlist is coming.
Everything the sleeve does in a sandbox is a tool call, so it shows in Observe with its arguments and results.

← MCP servers The Fleet and lifecycle →