Sandbox service quickstart
In this quickstart, a coding agent on your laptop corrects a fault in one of your repositories. The agent sends every command to the moca sandbox service, which runs each command in a new VM. At the end, you apply the agent's work to your laptop as a patch.
Preview. The sandbox service is implemented but not yet declared Stable; interfaces and limits may change. Known limits: Limits.
What happens to your files​
mocactl sbx upcopies your working tree into the sandbox's/workspace. It also writes your agents' configuration.- The agent reads, edits and tests the copy in
/workspace. - The source files on your laptop do not change until you run
mocactl sbx pull --apply. - The service does not copy files automatically. To send later edits, run
mocactl sbx push.
Before you start​
You need:
- Node.js 22 or later and
git. - A git repository to work on. This is your own project. Mocactl is a client, so you do not
need a clone of moca.
up,pushandpullrun in a git repository, and fail outside one. - A sandbox service deployment and its 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 your account is not on the list, step 2 shows the ID to send them.
- Claude Code or OpenCode. (Codex and IBM Bob work too. See the user guide.)
Set your variables​
This page uses two values that you supply. Set them in the shell you use for the steps below. You can then copy each later command without an edit.
# The API host of your sandbox service deployment, without the scheme.
export API_HOST=sbx.example.com
# The git repository you want the agent to work on. This is your own project,
# not a clone of moca. Use the repository root.
export REPO_DIR=~/src/my-project
Open a new shell, and set the two variables again. To keep them, add the two lines to your shell's
startup file (~/.bashrc or ~/.zshrc).
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 is not on your PATH, the
installer prints the line to add. Ignore the closing hint about SH_CONTROL_PLANE_URL, which
applies to the harness.
2. Log in​
Log in with GitHub's device flow. Mocactl remembers the URL, so this is the only step that uses
$API_HOST:
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>
The message this account (github:<id>) is not enrolled in the sandbox service shows that your
account is not on the deployment's access list. Send the github:<id> from the message to whoever
runs the deployment. The <id> is your numeric GitHub user ID. The operator calls this list the
allowed subjects.
3. Bring your repository up​
Go to the root of your repository, then create its sandbox:
cd $REPO_DIR
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. To list the other templates, runmocactl sbx templates. To select one, add--template <id>. - It pushes your working tree. It does not push files that can hold secrets (
.env*,*.pem,*.key,id_*). - It writes the agent configuration. It also records the binding in
.sbx/sandbox.json. - You can run
upagain at any time. It uses this repository's sandbox again while that sandbox is live. - Each clone and each git worktree gets its own sandbox. Two worktrees of one repository do not share one.
up checks your repository before it creates anything. A check that fails stops up with no
sandbox created, so you correct the cause and run up again. The two checks below stop up most
often in a repository that is already in use.
If up stops at a large file​
up pushes no file over 12 MiB, and no tree over 256 MiB. A file over the limit stops up, and
it creates no sandbox:
sbx: files over 12 MiB (12582912 bytes) are not pushed; remove them, or .gitignore them: usage.ndjson (16.4 MiB, 17176795 bytes)
The agent almost never needs such a file. Exclude it, then run up again. For a file only you
have, use .git/info/exclude, which stays on your laptop:
echo usage.ndjson >> .git/info/exclude
mocactl sbx up
To exclude the file for everybody, add the same line to .gitignore.
Both files work for an untracked file. A tracked file is pushed even when a rule ignores it,
so first run git rm --cached <file>. For a tree over 256 MiB, --max-push raises the limit. No
flag raises the 12 MiB limit for one file.
If up stops at your Claude Code permissions​
up denies the local built-in tools (Bash, Read, Edit, Write, and 13 more) in
.claude/settings.json, so that the agent can use only the sandbox's tools. A repository that
allows one of those tools contradicts the deny, and up stops:
sbx: .claude/settings.json: permissions.allow lists local built-in tools (Bash(git status:*), …),
which would act on this machine; edit it by hand, or run mocactl sbx up --no-agent-config
At run time the deny wins: an allow rule cannot carve an exception out of a deny, so the listed
commands do not run on your laptop. up stops because the two rules contradict each other. A
repository that keeps both says one thing and does another, and the allow rule is inert.
Delete the local-tool rules from permissions.allow in .claude/settings.json, then run up
again. Keep a rule that names a sandbox tool, such as mcp__sandbox__*.
The agent does not need those rules. It uses the sandbox's tools, which up allows for you.
If you want the rules for your own sessions outside the sandbox, put them in
.claude/settings.local.json, which up neither writes nor reads for permissions. Add that file
to .gitignore, or git reports it as a new file. The rules stay inert while the deny is in place.
Do not use --no-agent-config to get past this check. It writes no agent configuration, so
Claude Code gets no sandbox MCP server, keeps its local tools, and runs every command on your
laptop. It is for a setup you configure by hand.
4. Run your agent​
Start Claude Code or OpenCode in the repository root:
cd $REPO_DIR
claude # or: opencode
Claude Code asks one time whether to use the project's sandbox MCP server. Select "Use this MCP
server". The highlighted default refuses the server, and the agent then has no tools.
Then ask for work as usual, for example "the tests fail, fix them".
The agent now uses the sandbox's tools: bash, read, write, edit, grep, find, ls and
sandbox_info. The service denies the agent's local tools.
mocactl sbx claude is an alternative. It starts Claude Code with the sandbox server for one run,
and does not ask the MCP question.
5. Take the work back​
First, show the patch:
mocactl sbx pull
Then apply it:
mocactl sbx pull --apply
applied the sandbox's changes to 3 files (2814 bytes of patch)
pull --apply writes the patch to your working tree, not to your index. To examine the patch, run
git diff. Then commit as usual.
pull --apply refuses a patch that changes agent configuration or hooks (.mcp.json, .claude/,
.husky/, .envrc, and similar). It then applies no part of the patch. See
Take the work back.
6. Check, and clean up​
First, check the setup. doctor tests your login, the sandbox, the agent configuration, command
execution, and changes you did not pull:
mocactl sbx doctor
Then delete the sandbox and the configuration that up added:
mocactl sbx rm
rm refuses to delete a sandbox that holds work you did not pull. If you keep the sandbox, it ends
after 7 days without use by default. The service then deletes its files.
What you just did​
- Your agent ran on your laptop. Its commands ran in the sandbox.
- No process continues after a call.
- The VM has no network device. It reaches only the hosts that the deployment allowlists, through a proxy on the host.
- The VM holds no secrets.
To read why this design is safer, see Isolation and data handling.
Next​
- Do more: Use Codex or IBM Bob,
Use egress credentials,
Keep a guest between commands (lease mode). To set the control plane for
one shell instead of logging in again, use
MOCACTL_SBX_URL. - Understand: Limits.
- Look up:
mocactl sbxreference.