EN Providers Docker Create Sandbox

Create a sandbox (Docker)

Minimal create

whaleshell sandbox create \
  --name demo \
  --workspace "$PWD" \
  --policy whaleshell-cli/policies/default.yaml \
  --memory 2g

With an agent image and credential providers:

whaleshell sandbox create \
  --name cursor \
  --from cursor \
  --workspace "$PWD" \
  --policy /path/to/policy.yaml \
  --provider cursor \
  --provider gh \
  --memory 2g

Lifecycle

whaleshell sandbox list
whaleshell sandbox status demo
whaleshell sandbox exec demo -- uname -a
whaleshell sandbox connect demo          # interactive bash -il
whaleshell sandbox stop demo
whaleshell sandbox start demo
whaleshell sandbox delete demo

Delete removes the sandbox container, proxy sidecar, network, and labeled volumes.

What create does

1. Resolves image (--image / --from / default).
2. Ensures Engine images (sandbox + slim proxy base).
3. Creates whaleshell-net-<name> (internal when proxy is on).
4. Starts whaleshell-proxy-<name> from debian:bookworm-slim (override: WHALESHELL_PROXY_IMAGE).
5. Creates and starts whaleshell-<name> with policy, workspace bind, optional data volume, CPU/memory/PIDs limits.
6. Registers with the gateway when configured.

Templates

Bake sizing into a reusable template (OpenShell-style):

whaleshell sandbox template create \
  --name desk \
  --from cursor \
  --memory 2g \
  --cpu 2 \
  --pids-limit 2048

whaleshell sandbox create --template desk --name worker --workspace "$PWD"

Flag values override template fields. Soft defaults from config/env fill gaps only when flags and template omit them — see Resources.