Your first sandbox¶

With the CLI installed and the gateway running, create a sandbox for the project you want the agent to work on.

Set CAUTEM_USE_GHCR=1 if you want the base alias to use the published Quarshell image, and save a policy file as shown in the macOS or Linux walkthrough. The commands below assume that file is ~/.config/cautem/default-policy.yaml.

Create¶

Create a Gateway managed sandbox:

cautem sandbox create \
  --name demo \
  --gateway-workspace default \
  --from base \
  --policy ~/.config/cautem/default-policy.yaml \
  --upload "$PWD" \
  --memory 2g

Flag	What it does
`--name`	Sandbox name
`--gateway-workspace`	Workspace on the selected Gateway
`--from`	Image alias; `base` uses GHCR when `CAUTEM_USE_GHCR=1`
`--policy`	Sandbox policy YAML file
`--upload`	Copy a local project directory into `/workspace`
`--memory`	Sandbox memory limit

Work inside¶

cautem sandbox list
cautem sandbox exec demo -- uname -a
cautem sandbox connect demo

connect opens an interactive shell inside the sandbox. A Gateway workspace selects resource scope and does not mount a host folder.

Give it credentials¶

Optional. Secrets live in the gateway and never enter the sandbox — the agent only sees placeholders:

GITHUB_TOKEN=… cautem provider create --name gh --type github --credential GITHUB_TOKEN

cautem sandbox create \
  --name demo-with-gh \
  --gateway-workspace default \
  --from base \
  --policy ~/.config/cautem/default-policy.yaml \
  --provider gh

More: Credential providers · Cursor agent.

Watch, stop, clean up¶

cautem logs demo --tail --source proxy
cautem sandbox stop demo
cautem sandbox delete demo

delete removes the sandbox, its proxy sidecar, network and data volumes. Provider secrets stay in the gateway.

What's next¶

When the agent hits a blocked host, it gets a 403 with the reason. See Policy to approve a narrow rule without recreating the sandbox, and Recreate a sandbox for changes that do need a fresh container.