Sandboxes | Cellar

Requires Docker Engine (Linux) or Docker Desktop (macOS). Sandboxes run under Docker's default OCI runtime (runc) with CapDrop: ALL, no-new-privileges, a pids limit, and default seccomp/AppArmor. Egress is enforced by topology (internal Docker networks + shared egress gateway). On macOS, cellard stages cellar-agent under the data directory (~/.cellar by default) before bind-mounting it — Docker Desktop cannot mount paths like /usr/local/bin that sit outside its shared directories.

Each sandbox runs with cellar-agent as the container entrypoint (PID 1 init + job supervisor). There is no create-time --entrypoint / command; the sandbox stays up until stop/rm. Workloads run via sandbox exec (Docker exec). Use --detach for background jobs.

# Create an isolated sandbox (no external network)
sudo cellar sandbox create --image alpine
# or a language runtime preset (resolves to an Alpine image):
sudo cellar sandbox create --runtime node-26
# or from YAML:
sudo cellar sandbox create -f examples/sandbox.yaml

# Allowlisted egress (topology gateway — see internal/egress/README.md).
# At most one of --domain-allow-list / --network-allow-list / --network-block-all:
sudo cellar sandbox create --image curlimages/curl \
  --domain-allow-list 'example.com'
# or: sudo cellar sandbox create -f examples/sandbox-allowlist.yaml
sudo cellar sandbox create --image curlimages/curl \
  --domain-allow-list 'example.com,*.openai.com' --essential-services
sudo cellar sandbox create --image alpine --network-block-all
sudo cellar sandbox create --image alpine \
  --network-allow-list '208.80.154.232/32,192.168.1.0/24'
# Live update (blockall/allowlist/denylist; not none):
sudo cellar sandbox network <id> --domain-allow-list 'example.com'
sudo cellar sandbox network <id> --network-block-all=false

sudo cellar sandbox exec <id> -- uname -a
sudo cellar sandbox exec --detach <id> -- sleep 3600
sudo cellar sandbox job ls <id>
sudo cellar sandbox job stop <id> <job-id>
sudo cellar sandbox stop <id>
sudo cellar sandbox rm <id>

Security model. Isolation is runc + dropped capabilities + no-new-privileges + pids limit + Docker seccomp/AppArmor + topology-based egress. Sandboxes share the host (or Docker Desktop VM) kernel. For production Linux hosts, enable dockerd userns-remap.