Skip to main content
Version: v0.11.0

Sandbox service user guide

Preview. The sandbox service is implemented, but not yet declared Stable; interfaces and limits may change. Known limits: Limits.

This guide takes you from nothing installed to an agent's work applied in your own repository. You need no moca background. New here? The quickstart is the five-step version. Operators should read the runbook instead; to look into a member's problem, its Reproducing a member's issue.

What you get​

Your coding agent (Claude Code, OpenCode, Codex or IBM Bob) still runs on your laptop, but every command it runs runs in the sandbox service, each one in a fresh virtual machine (VM). It reads, edits and tests your code there, in a copy of your repository at /workspace. (IBM Bob has no deny list, so its local tools stay available: see IBM Bob.) Your laptop's source files are untouched, apart from the agent configuration mocactl sbx up adds, until you take the agent's work back as a patch and apply it (mocactl sbx pull --apply). The copy is not kept in sync: edits you make locally after mocactl sbx up reach the sandbox only when you send them with mocactl sbx push. /workspace is kept between commands, and the sandbox ends after a period without use (7 days by default).

This sandbox is not the one a bare mocactl session (moca's own server, SH_CONTROL_PLANE_URL) runs its tools in: the mocactl sbx commands neither see nor manage that one.

Why this is safer than letting the agent run on your laptop: Isolation and data handling.

Tasks​

PageWhat it covers
Install, log in and bring a repository upmocactl and sbx versions, login, sbx up, templates, lifetime, worktrees
Run your coding agentClaude Code, OpenCode, Codex CLI and IBM Bob against the sandbox
Take the work back, and send moresbx pull, pull --apply, and what a patch may not touch
What sbx up changes in your repositorythe agent configuration it writes, --cortex, and undoing it with sbx rm
Work with a sandboxpush, run, put, ls, the shell, and what persists between calls
Use credentialsegress credentials for GitHub and other allowlisted services
Make a template from a container imagea first template, step by step, from python:3.12-slim
Make your own templatesa template from an image pinned by digest
Keep a guest between commands (lease mode)--mode lease and lease+processes, sbx reset, tracked processes
Call the sandbox API from your own codesbx env, sbx token, and the sandbox/v1 gRPC API
Troubleshootsbx doctor and the common errors

Concepts and reference​