Custom environments

Every sandbox is customizable — agents install packages, pull images, and configure tools as they work, and those changes persist for the sandbox's lifetime. This page covers two things beyond that: a general-purpose shell sandbox for manual setup, and custom templates that capture a configured environment into a reusable image so you don't have to set it up again every time.

Shell sandbox

sbx run shell drops you into a Bash login shell inside a sandbox with no pre-installed agent binary. It's useful for installing and configuring agents manually, testing custom implementations, or inspecting a running environment.

$ sbx run shell ~/my-project

The workspace path defaults to the current directory. To run a one-off command instead of an interactive shell, pass it after --:

$ sbx run shell -- -c "echo 'Hello from sandbox'"

Set your API keys as environment variables so the sandbox proxy can inject them into API requests automatically. Credentials are never stored inside the VM:

$ export ANTHROPIC_API_KEY=sk-ant-xxxxx
$ export OPENAI_API_KEY=sk-xxxxx

Once inside the shell, you can install agents using their standard methods, for example npm install -g @continuedev/cli. For complex setups, build a custom template instead of installing interactively each time.

The shell sandbox uses the shell base image — the common base environment without a pre-installed agent.

Custom templates

Custom templates are reusable sandbox images that extend one of the built-in agent environments with additional tools and configuration baked in. Instead of asking the agent to install packages every time, build a template once and reuse it across sandboxes and team members.

Templates make sense when multiple people need the same environment, when setup involves steps that are tedious to repeat, or when you need pinned versions of specific tools. For one-off work, the default image is fine — ask the agent to install what's needed.

Note

Custom templates customize an existing agent's environment — they don't create new agent runtimes. The agent that launches inside the sandbox is determined by the base image variant you extend and the agent you specify in the sbx run command, not by binaries installed in the template.

Base images

All sandbox templates are published as docker/sandbox-templates:<variant>. They are based on Ubuntu and run as a non-root agent user with sudo access. Most variants include Git, Docker CLI, and common development tools like Node.js, Python, Go, and Java.

Each variant also has a -docker version (for example, claude-code-docker) that includes a full Docker Engine running inside the sandbox — no local Docker daemon required. The -docker variants are the defaults used by sbx run on macOS and Linux. These variants run in privileged mode inside the microVM (not on your host), with a dedicated block volume at /var/lib/docker, and dockerd starts automatically inside the sandbox.

The block volume defaults to 50 GB and uses a sparse file, so it only consumes disk space as Docker writes to it. On Windows, the volume is not sparse and the full 50 GB is allocated at creation time, which increases startup time. For this reason, the non-docker variants are the default on Windows.

To override the volume size, set the DOCKER_SANDBOXES_DOCKER_SIZE environment variable to a size string before starting the sandbox:

$ DOCKER_SANDBOXES_DOCKER_SIZE=10g sbx run claude

Use the non-docker variant if you don't need to build or run containers inside the sandbox and want a lighter, non-privileged environment. Specify it explicitly with --template:

$ sbx run claude --template docker.io/docker/sandbox-templates:claude-code

Build a custom template

Building a custom template requires Docker Desktop.

Write a Dockerfile that extends one of the base images. Pick the variant that matches the agent you plan to run. For example, extend claude-code to customize a Claude Code environment, or codex to customize an OpenAI Codex environment.

The following example creates a Claude Code template with Rust and protocol buffer tools pre-installed:

FROM docker/sandbox-templates:claude-code
USER root
RUN apt-get update && apt-get install -y protobuf-compiler
USER agent
RUN curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y

Use root for system-level package installations (apt-get), and switch back to agent before installing user-level tools. Tools that install into the home directory, such as rustup, nvm, or pyenv, must run as agent — otherwise they install under /root/ and aren't available in the sandbox.

Build the image and push it to an OCI registry, such as Docker Hub:

$ docker build -t my-org/my-template:v1 --push .

Note

The Docker daemon used by Docker Sandboxes pulls templates from a registry directly; it doesn't share the image store of your local Docker daemon on the host.

Unless you use the permissive allow-all network policy, you may also need to allow-list any domains that your custom tools depend on:

$ sbx policy allow network "*.example.com:443,example.com:443"

Then run a sandbox with your template. The agent you specify must match the base image variant your template extends:

$ sbx run --template docker.io/my-org/my-template:v1 claude

Because this template extends the claude-code base image, you run it with claude. If you extend codex, use codex; if you extend shell, use shell (which drops you into a Bash shell with no agent).

Note

Unlike Docker commands, sbx does not automatically resolve the Docker Hub domain (docker.io) in image references.

Template caching

Template images are cached locally. The first use pulls from the registry; subsequent sandboxes reuse the cache. Cached images persist across sandbox creation and deletion, and are cleared when you run sbx reset.