Work with a sandbox
Preview. The sandbox service is implemented, but not yet declared Stable; interfaces and limits may change.
-
Each call is a fresh VM. Files under
/workspacepersist from one call to the next; nothing else does. No process survives a call: a server, a watcher or a background job started in one call is gone in the next. Chain the steps into one command instead (make build && make test). -
No network of its own. A template with egress reaches only the hosts your operator allowlisted, through a proxy (anything else answers
403 destination_denied); one without egress reaches nothing. A package installs only from a registry on the allowlist: the default one carries the common registries (PyPI, npm, crates.io, the Go module proxy), but your operator may have changed it. The templates carry the toolchains:mocactl sbx templateslists them, with their tools, andmocactl sbx policylists each profile's egress. A refused request's body says that the host is not on the sandbox's egress allowlist; retrying does not help. That body shows only for plain-HTTP requests and clients that print it: an HTTPS request is refused at itsCONNECT, so most clients (curl, git, pip) show just403orCONNECT tunnel failed, and the agent learns the rule from its sandbox instructions instead. To have a host added, ask your operator and name the host:mocactl sbx egresslists the hosts your sandbox reached and the ones it was refused. The service's own URL, opened in a browser or withcurl, says the same and how to getmocactl. -
One command at a time per sandbox. The sandbox runs one call at a time, so batch the work: read several files in one call, run the whole test suite in one call. The agent's tools refuse a call that would wait more than 30 s behind another one with
sandbox busy: … retry later, and the service refuses a third call in flight on one sandbox (from another terminal, say) the same way. TheCLAUDE.md/AGENTS.mdblock tells the agent all of this. -
Your secrets are not pushed.
upandpushleave out.env*,*.pem,*.keyandid_*files, and say so (--include-secretspushes them; don't). Everything else that git would commit, plus your untracked files that are not ignored, is pushed. -
Push again after you change files locally:
mocactl sbx pushpushreplaces the sandbox's tree with yours. It refuses while the sandbox has changes you have not pulled; pull them first, ormocactl sbx push --forceto discard them.upon a sandbox with changes not yet pulled leaves it unpushed, with a warning, and still succeeds. What is sent is always the whole work tree, whatever directory you runuporpushfrom; run from a subdirectory, both say so before pushing. -
Run a command yourself:
mocactl sbx run -- python3 -m unittestmocactl sbx run -- sh -c 'cd src && ls | wc -l'echo 'make test 2>&1 | tail -20' | mocactl sbx runrun -- CMD…quotes each argument, so it runs exactly what you typed: use stdin or-- sh -c '…'for pipes, variables and globs. It exits with the command's own code, 124 when the command timed out, and 125 when the sandbox itself failed. A command the sandbox refused before starting it, for want of capacity (busy, or the template's worker at its memory budget), is sent again after a short backoff, up toMOCACTL_SBX_BUSY_RETRIEStimes (default 4, at most 20, 0 for none): nothing ran, so it still runs at most once. Refused every time,run(andput) exits 75; interrupted while waiting, 130. Likessh, it passes the remote side's terminal escape sequences through to your terminal. -
Write a file into the sandbox from stdin:
mocactl sbx put data/fixture.json < fixture.jsonputwrites only under/workspace(a relative path is taken from there).