Sandboxing

Workers can run tool calls — bash, code-eval, filesystem access, and others — inside an ephemeral container. This ensures a run in project A cannot read the environment variables, files, or tokens belonging to project B running on the same worker.

Looking for the conceptual model? This page is the operator handbook for configuring the worker. For the architecture decision guide (Docker vs Kubernetes vs Lambda, mode and backend compatibility), see Architecture: Sandbox backends.

Modes

Mode	What it does	When to use
`none`	Tools run in the worker process with a scoped scratch directory and scrubbed env.	Local development, trusted single-tenant
`per_tool`	One container per tool call.	Untrusted tools, trusted workflow
`per_run`	One container per workflow run, reused across tool calls.	Production default.
`per_worker`	One long-lived container per worker, pinned to one project.	Very low-latency single-project fleets

Selection precedence

Highest takes effect:

Worker CLI flag --sandbox-mode
Worker config file (~/.sagewai/worker.yaml, not shipped in Plan 1)
Project environment default (production → per_run, staging → per_tool, development → none)
Hard default: none

Start a sandboxed worker

sagewai worker start \
    --pool default \
    --sandbox-mode per_run \
    --sandbox-backend docker \
    --sandbox-image ghcr.io/sagewai/sandbox-base:dev \
    --sandbox-network none \
    --sandbox-cpu 2 --sandbox-mem 4g --sandbox-pids 256 --sandbox-disk 10g \
    --project-environment production

Debugging

# Check backend health
sagewai sandbox doctor

# List live sandboxes on this host
sagewai sandbox list

# Force-kill orphaned containers
sagewai sandbox reap --older-than 10m

Fallback behavior

When the requested backend is unhealthy (for example, the Docker daemon is down):

Non-production projects fall back one mode (per_run → per_tool → none) and emit a WARN log.
Production projects refuse to start. The worker exits non-zero so the process supervisor can surface the outage.

Roadmap

Plan 2 — full sandbox image family (general, ml, ml-cuda, ops, erp, ecommerce, api), published to GHCR with SHA-pinned digests.
Plan 3 — fleet label advertisement for multi-tenant task routing, admin UI surfaces, Grafana dashboard row, egress-allowlist proxy.
Future — Sagewai Sealed will replace the minimal env-var secret provider with JIT credentials, redaction, workload identity, and HITL approval.