Skip to content
Ash

Sandbox

Ash runs command tools inside Docker containers. Tool calls do not execute directly on your host shell.

Sandbox In 30 Seconds

  • bash and file-adjacent execution run in a container runtime
  • mounts and network are controlled by [sandbox] config
  • security defaults are restrictive, with explicit opt-ins

Quick Start

Use default sandbox behavior first:

[sandbox]
image = "ash-sandbox:latest"
timeout = 60
memory_limit = "512m"
cpu_limit = 1.0
runtime = "runc"               # or "runsc"
network_mode = "bridge"        # or "none"
workspace_access = "rw"        # none | ro | rw
sessions_access = "ro"         # none | ro
chats_access = "ro"            # none | ro
source_access = "none"         # none | ro
mount_prefix = "/ash"

Verify runtime health:

Terminal window
uv run ash sandbox status

Configure Access And Isolation

Common hardening changes:

[sandbox]
network_mode = "none"          # Block outbound network
workspace_access = "ro"        # Prevent file writes to workspace
source_access = "ro"           # Allow source inspection without writes
runtime = "runsc"              # gVisor runtime if available

Package/runtime customization:

[sandbox]
apt_packages = ["jq", "ripgrep"]
python_packages = ["httpx"]
setup_command = "uv pip install --user rich"

Security Model

Sandbox execution applies:

  • process and resource limits
  • reduced Linux capabilities
  • no-new-privileges controls
  • configurable mount access for workspace/sessions/chats/source

Troubleshooting

Sandbox is unavailable

Terminal window
uv run ash sandbox status
uv run ash doctor

Command runtime fails repeatedly

Rebuild the sandbox image:

Terminal window
uv run ash sandbox build

Tool cannot reach the network

Check network_mode:

[sandbox]
network_mode = "bridge"

Tools can read but not write files

Set workspace mount mode intentionally:

[sandbox]
workspace_access = "rw"

Reference (Advanced)

Main config fields:

  • runtime: runc or runsc
  • network_mode: bridge or none
  • workspace_access: none, ro, rw
  • sessions_access: none, ro
  • chats_access: none, ro
  • source_access: none, ro
  • mount_prefix: bind mount prefix for internal paths

Related docs: