Sandbox service quickstart
In this quickstart, a coding agent on your laptop fixes something in one of your repositories. Every command it runs goes to the moca sandbox service, each one in a fresh VM. At the end you apply its work to your laptop as a patch.
Preview. The sandbox service is not yet declared Stable. Interfaces and limits may change.
What happens to your files​
mocactl sbx upcopies your working tree into the sandbox's/workspaceand writes your agents' configuration.- The agent reads, edits and tests the copy in
/workspace. - Your laptop's source files are untouched until you run
mocactl sbx pull --apply. - Nothing syncs on its own.
mocactl sbx pushsends edits you make later.
Before you start​
You need:
- Node.js 22 or later and
git. - A sandbox service deployment and its URL,
https://<api host>. Moca is self-hosted: deploy one, or ask whoever runs yours. - A GitHub account that whoever runs the deployment has added to its access list. If yours isn't on it yet, step 2 shows the ID to send them.
- Claude Code or OpenCode. (Codex and IBM Bob work too. See the user guide.)
1. Install mocactl​
curl -fsSL https://raw.githubusercontent.com/rossoctl/moca/main/scripts/install-mocactl.sh | sh
mocactl --version # v0.7.0 or later
The installer puts mocactl in ~/.local/bin. If that directory isn't on your PATH, it prints the
line to add. You can ignore its closing hint about SH_CONTROL_PLANE_URL: that's for the harness.
2. Log in​
Logging in uses GitHub's device flow. The URL is remembered, so this is the only time you pass it:
mocactl sbx login --control-plane-url https://<api host>
Open https://github.com/login/device and enter the code ABCD-1234 (valid for 15 minutes)
logged in to the sandbox service as <your GitHub login>
If you see this account (github:<id>) is not enrolled in the sandbox service, your
account isn't on the deployment's access list yet. Send that github:<id> (your numeric GitHub
user ID) to whoever runs the deployment, so they can add you. The operator calls this list the
allowed subjects.
3. Bring your repository up​
cd <your repository>
mocactl sbx up
sbx: not pushed, as they may hold secrets (--include-secrets pushes them): .env
created sbx-0f3a9c2e7b1d4a5f6e8c0b2d4a (default)
pushed 214 files (3.2 MiB) to sbx-0f3a9c2e7b1d4a5f6e8c0b2d4a
configured Claude Code, OpenCode and IBM Bob: .mcp.json, .claude/settings.json, opencode.json, .bob/settings.json, .bob/mcp.json, CLAUDE.md, AGENTS.md
…
What up does:
- It creates the sandbox from the
defaulttemplate.mocactl sbx templateslists the others, and--template <id>picks one. - It pushes your working tree, except files that may hold secrets (
.env*,*.pem,*.key,id_*). - It writes the agent configuration and records the binding in
.sbx/sandbox.json. - You can run
upagain at any time. It reuses this repository's sandbox while that sandbox is live.
4. Run your agent​
Start Claude Code or OpenCode in the repository root:
claude # or: opencode
Claude Code asks once whether to use the project's sandbox MCP server. Choose "Use this MCP
server": the highlighted default declines, and the agent is left with no tools. Then ask for
work as usual, for example "the tests fail, fix them".
The agent's tools are now the sandbox's: bash, read, write, edit, grep, find, ls and
sandbox_info. Its local tools are denied.
mocactl sbx claude is an alternative. It starts Claude Code with the sandbox server for that
one run, so you skip the MCP question.
5. Take the work back​
mocactl sbx pull # look at the patch first, if you like
mocactl sbx pull --apply
applied the sandbox's changes to 3 files (2814 bytes of patch)
The patch goes into your working tree, not your index. Review it with git diff, then commit as
usual. pull --apply refuses a patch that touches agent configuration or hooks (.mcp.json,
.claude/, .husky/, .envrc, and similar), and applies nothing in that case. See
Take the work back.
6. Check, and clean up​
mocactl sbx doctor # login, sandbox, agent config, exec, unpulled changes
mocactl sbx rm # delete the sandbox and the configuration `up` added
rm refuses to delete a sandbox that holds work you haven't pulled. If you don't remove it, a
sandbox ends after 7 days without use by default, and its files go with it.
What you just did​
- Your agent ran on your laptop, but none of its commands did.
- No process survives a call.
- The VM has no network device. It reaches only the hosts the deployment allowlists, through a proxy on the host.
- The VM holds no secrets.
Why this design is safer: Isolation and data handling.
Next​
- Do more: Use Codex or IBM Bob, Use egress credentials, Keep a guest between commands (lease mode).
- Understand: Limits.
- Look up:
mocactl sbxreference.