Docker Sandbox

Every workspace runs in an isolated Docker container. Agents get full root access inside the container without affecting the host system. This provides a safe execution environment where agents can install packages, modify system files, and run arbitrary commands.

What's in the container

The base container image includes:

• Docker-in-Docker (DinD) — agents can build and run their own containers.
• Python 3.12 with pip and uv for dependency management.
• Node.js 22 with npm.
• Common tools — git, curl, jq, yq, openssh-client, and other standard utilities.

Workspace directory

The host's workspace_dir is mounted at /workspace inside the container. This is where agents read and write project files. Changes are bidirectional — edits made by agents appear on the host, and host changes are visible to agents.

workspace_dir: /home/user/projects/my-app

Home persistence

When docker.home_persistence is enabled, the agent's home directory (/root) is persisted across workspace restarts using a Docker volume. This preserves:

• Installed tools and global packages
• Shell history and configuration files
• Caches (pip, npm, uv)

docker:
  home_persistence: true

Without home persistence, agents start with a clean home directory each time the workspace restarts.

Mounts

Additional host paths can be bind-mounted into the container. This is useful for sharing credentials, SSH keys, or other files that agents need but shouldn't be part of the workspace directory.

mounts:
  - host_path: ~/.ssh
    container_path: /root/.ssh
    read_only: true
  - host_path: ~/.config/gh
    container_path: /root/.config/gh
    read_only: true

Use read_only: true for sensitive files to prevent agents from modifying them.

Resource limits

Configure compute resources via the docker section of the workspace config:

docker:
  network_mode: host
  ports:
    - "8080:8080"
  gpu: true
  memory: 8g
  cpus: 4

Container lifecycle

Further reading

For the full list of Docker configuration options, see Docker Settings.