Skip to main content
Version: next

Build a client: interfaces, calls, errors and retries

Preview. The control-plane, sandbox and harness APIs are implemented but not yet declared Stable; interfaces and limits may change. Known limits: Known gaps.

This page is for a developer who writes their own client for moca: an SDK, a tool, a script or an agent's MCP server. It covers the interfaces a client talks to, which API calls each mocactl sbx command makes (so you can copy what it does), the error codes across REST, SSE and gRPC with what a client should do about each, the CLI's exit codes, and when to retry.

The contracts are the source of truth: openapi.yaml (control plane), harness-openapi.yaml (harness) and proto/sandbox/v1/sandbox.proto (sandbox execution).

The three interfaces​

┌─────────────┐ REST /v1, JSON (API token) ┌─────────────────────────┐
│ your client │──────────────────────────────────>│ control plane │
│ │ │ logins, sandboxes, │
│ │ │ templates, sessions │
│ │ └─────────────────────────┘
│ │ gRPC SandboxExec (sandbox token) ┌─────────┐ ┌───────────┐
│ │──────────────────────────────────>│ relay │<──│ worker │
│ │ │ routes │──>│ microVMs │
│ │ │ Exec │ │ (dials │
│ │ └─────────┘ │ out) │
│ │ └───────────┘
│ │ REST + SSE turns (session token) ┌─────────────────────────┐
│ │──────────────────────────────────>│ harness │
└─────────────┘ │ runs turns on workers │
└─────────────────────────┘
  • The control plane's REST API holds every resource: logins and tokens, sandboxes, templates, sessions, credentials and config bundles, under /v1, in JSON. Errors are {"error": "<stable code>", "message": "..."}. The caller is never in a path: /v1/sessions means the caller's sessions. GET /v1/discovery tells a client the rest, including the harness's URL (harnessUrl).
  • Sandbox execution is gRPC, service SandboxExec of sandbox.v1. The client dials the relay, which checks the sandbox token and routes the call to the worker serving the sandbox's template. Each call stands alone; there is no session. See Call the sandbox API from your own code.
  • The harness runs turns of a session: POST /v1/turn with a session token, answered as one JSON result or, with Accept: text/event-stream, as SSE frames. See the HTTP API guide.

Which credential each takes​

Lifetimes and rotation are in the security model and, for the sandbox token, in Tokens.

CredentialSent toHow a client gets a new one
Device codePOST /v1/auth/device/token, polled every interval s until its expiresInPOST /v1/auth/device again (start a new login)
API tokenevery control-plane /v1 call, as Authorization: BearerPOST /v1/auth/token with the refresh token; keep the rotated refresh token it returns
Refresh tokenPOST /v1/auth/token onlyrotated on each use; 400 invalid_grant means log in again
Session tokenthe harness's turn routes, for one sessionPOST /v1/sessions/{id}/token
Sandbox tokenSandboxExec calls on one sandbox, as gRPC metadataPOST /v1/sandboxes/{id}/token (owner only); send {"activity": false} when the mint runs no command
Set-mode tokenLeaseControl set_mode, onceanswered by PUT /v1/sandboxes/{id}/mode, or POST /v1/sandboxes/{id}/mode-token; re-mint once on PERMISSION_DENIED

A script that needs a token asks mocactl for it instead of reading its files: mocactl auth token for an API token, mocactl sbx token for a sandbox token.

The bridge table: mocactl sbx command to API calls​

What each mocactl sbx command sends, so a client can do the same. For the top-level mocactl commands (login, run, sessions, promote, doctor and the rest), see the mocactl command reference. The template routes are in openapi.yaml under /v1/templates, /v1/quota and /v1/policy.

This table is derived from packages/mocactl/src/sbx/*.ts and may lag the code. Admin-only commands (subjects, enroll, templates quota, and the like) are left out.

Every control-plane call below is retried once, after a token refresh, when it answers 401 with token_required, token_invalid or token_expired. Every Exec and LeaseControl call is preceded by POST /v1/sandboxes/{id}/token when no fresh sandbox token is held.

CommandAPI calls
sbx loginGET /v1/discovery (to refuse a control plane without the sandbox service), then POST /v1/auth/device and POST /v1/auth/device/token every interval s; a new code when one expires
sbx logoutPOST /v1/auth/revoke with the refresh token
sbx templates / templates showGET /v1/templates; GET /v1/templates/{id}, or GET /v1/templates/{id}/builds/{build} with --build
sbx hostsGET /v1/templates, its hosts block
sbx quota / sbx policyGET /v1/quota; GET /v1/policy
sbx templates create --dry-runGET /v1/policy only; the checks run locally, nothing is posted
sbx templates create / templates buildPOST /v1/templates (build ID: POST /v1/templates/{id}/builds), with no policy read first. On 429 quota_exceeded with quota: buildsQueued, the same POST again after Retry-After (30 s when none is sent), until --timeout. On 409 template_exists, GET /v1/templates/{id} to say whose the id is
sbx templates followwithout --build, GET /v1/templates/{id} for the newest build; then GET /v1/templates/{id}/builds/{build} every 5 s, polling through 5xx and an unreachable control plane
sbx templates cancelPOST /v1/templates/{id}/builds/{build}/cancel
sbx templates activate [--wait]POST /v1/templates/{id}/activate; with --wait, the same POST again on 409 no_active_slot after Retry-After (30 s when none is sent), then, without --timeout, GET /v1/templates for the host's start line, then GET …/builds/{build} every 5 s until active
sbx templates deactivatePOST /v1/templates/{id}/deactivate ({stopNow: true} with --stop-now)
sbx templates tag / untag / editPOST /v1/templates/{id}/tags; DELETE /v1/templates/{id}/tags/{tag}; PATCH /v1/templates/{id}
sbx templates retire [--build] [--wait]POST /v1/templates/{id}/retire, or with --build DELETE /v1/templates/{id}/builds/{build}; with --wait, GET …/builds/{build} every 5 s
sbx createPOST /v1/sandboxes; on 409 template_not_active, the same POST again after Retry-After (30 s when none is sent), for up to 10 minutes
sbx create --mode Mas create, then POST …/mode-token and LeaseControl set_mode with that set-mode token (re-minted once on PERMISSION_DENIED)
sbx create --seedas create, then GET /v1/templates/{id} for the served build's seed, an Exec of the seed, and an Exec that checks the workspace for a clean git tree
sbx ls [--all]GET /v1/sandboxes (?all=1)
sbx getGET /v1/sandboxes/{id}; for a lease mode, a token minted with {activity: false} and LeaseControl status, and, when the worker does not know the epoch, POST …/mode-token with {activity: false} and LeaseControl set_mode
sbx mode MGET /v1/sandboxes/{id} (to refuse an upgrade without a terminal and carry the idle timeout over), PUT /v1/sandboxes/{id}/mode, sent again without idleTimeoutS on 400 invalid_request when the timeout was carried, then LeaseControl set_mode
sbx resetLeaseControl status, then LeaseControl reset
sbx proc start / ls / logs / stopExecs with a process kind (lease+processes only; refused locally below that mode)
sbx token [--renew-every S] / sbx envPOST /v1/sandboxes/{id}/token (env: with {activity: false})
sbx run / sbx putSandboxExec.Exec, sent again as a new Exec after a refusal before start (see Retries)
sbx upGET /v1/sandboxes/{id} for the bound sandbox, or GET /v1/sandboxes for one labelled with this repository; else POST /v1/sandboxes as create; then Execs that send the tree and commit a baseline
sbx push / sbx pullExecs: the tree in; a git diff against the baseline out
sbx rmwithout --force, an Exec that checks for unpulled changes; GET /v1/sandboxes/{id} (to read its mode); a sandbox token ({activity: false}); for a lease sandbox, LeaseControl sandbox_deleted; then Release for every sandbox; best effort, capped at 15 s in all, any error ignored; then DELETE /v1/sandboxes/{id}
sbx mcp / sbx claude / sbx codexone Exec per tool call; in a lease mode, LeaseKeepalive every 30 s
sbx credentials / add / deleteGET /v1/credentials; PUT / DELETE /v1/credentials/{name}, with consumer: sandbox-egress
sbx egress [--ndjson | --verify]GET /v1/sandboxes/{id}/egress, paged by after (--ndjson: format=ndjson; --verify: the NDJSON log, then the first page's summary)
sbx doctorthe login check, GET /v1/sandboxes/{id}, and one Exec of true

Errors​

Control-plane and harness errors are {"error": "<code>", "message": "..."}; message is left out of internal_error by design. Branch on error, never on message. Retry-After comes on the control plane's 409 no_active_slot and 409 template_not_active only, and on every harness 503 and 429; a control-plane 503 carries none.

On the harness, a turn that fails before its first SSE frame answers with the HTTP status below, exactly as a non-streamed turn. Once the stream has begun, a failure is a terminal error frame instead (see Streaming frames), with no status and no Retry-After.

StatusCodeFromWhenWhat a client should do
400invalid_json, invalid_request, configRef_invalidcontrol planea malformed body or fieldfix the request; the message names the field
400invalid_grantcontrol planethe refresh token is unknown, revoked, expired or a replayed predecessorlog in again
400digest_mismatchcontrol planea config-bundle upload whose bytes do not hash to the digest it claimedrebuild the bundle and upload again
400unknown_templatecontrol planea sandbox or session names an unknown, invisible or rejected buildlist the templates and pick one
400credential_required, credential_ambiguous, model_unavailablecontrol planeno credential, several and none named, or a model the endpoint does not offername the credential or the model
400endpoint_unresolvedboththe inference credential has no endpoint, and the deployment sets no defaultgive the credential an endpoint
400session_mismatch, subject_conflictboththe session token names another session; X-SH-Subject contradicts the tokenmint the token for this session; drop the header
400prompt_required, sessionId_requiredharnessa turn without a prompt; an attach, cancel or status read without a sessionIdfix the request; never retry it as is
400tenant_not_allowedharnessan authenticated read named a tenant (the session token alone scopes it)drop the tenant parameter
401token_required, token_invalid, token_expiredbothno, a bad or an expired API or session tokenrefresh the token, then retry once
401unauthorizedcontrol planea device-flow start the identity provider refused, or a test user on the device flowdo not retry as is; show the message
403not_enrolledcontrol planethe subject is not enrolled for sandboxes; on a refresh, the login was endedsend the operator the subject the message names
403forbiddencontrol planenot the owner, or an admin-only routedo not retry
403mode_not_allowedcontrol planea lease mode the deployment does not allowuse per-exec, or ask the operator
404sandbox_not_found, template_not_found, session_not_found, not_foundbothunknown, or another user's (never 403, so ids cannot be probed)check the id
404credential_not_foundbothno credential with that name, or none the subject can resolveadd the credential, or name an existing one
404config_bundle_not_foundcontrol planea session names a digest nobody uploaded, or that expiredpromote the bundle again
404turn_not_foundharnessattach or cancel with no running or retained turn (an unknown async turn on the control plane is 404 not_found)do not retry; start a new turn
409sandbox_terminated (reason)control planea token or mode call on a sandbox deleted or expiredcreate a new sandbox
409name_conflictcontrol planeyou already have a live sandbox with that namepick another name
409template_exists, self_attestedcontrol planeanother subject's template id; deployment visibility for a self-attested templatepick another id; keep the template private
409template_not_activecontrol planethe build is not active; its activation has started unless you sent activate: falsesend the same call again after Retry-After
409no_active_slot (reason: memory when memory is the limit)control planeevery host holding the build is fullsend the same call again after Retry-After
409template_unavailablecontrol planeno registered build, or no host holds itdo not retry as is; tell the operator, or rebuild
409build_in_usecontrol planea retire or reject while a live sandbox runs on the builddelete those sandboxes first
409destination_conflictcontrol planeanother of your egress credentials already holds that destinationdelete or edit the other credential
409policy_changed, quota_changedcontrol planea PUT /v1/policy (or a subject's quota) sent with ?expect= after the stored one changed; nothing was writtenread it again, re-apply your change, write again
409bootstrap_subjectcontrol planean unenroll or role change for a subject the deployment's settings enroll (SH_ALLOWED_SUBJECTS, SH_ADMIN_SUBJECTS)change it in the settings instead
409admin_grantedcontrol planean unenroll of a subject that holds the admin role, which keeps it enrolledrevoke the role first, then unenroll
409self_revokecontrol planean admin revoking its own admin rolehave another admin revoke it
409turn_not_cancellablecontrol planea cancel of an async turn that is no longer queuedread the turn's result
409turn_in_progress (turnId)harnessthe session already runs a detachable turnattach to turnId, or wait for it to end
409turn_mismatch (turnId)harnessa cancel names a turn other than the session's running onecancel the turnId in the answer, if that is the turn you meant
410template_retiredcontrol planea use, activation or create through a retired buildchoose a live build, or move the tag
410device_code_expiredcontrol planethe login was not approved in timestart the login again
410config_bundle_not_foundharnessthe session's promoted bundle is gonepromote the same directory again; if it changed, start a new session
422policy_refused (rule)control planea template create failed a gating rulefix what the rule names; templates create --dry-run checks it first
422config_bundle_unsupportedharnessthe bundle's format is newer than this harness readsnot retryable as is: the harness must be upgraded
428authorization_pendingcontrol planethe user has not approved the device code yetpoll again after interval
429quota_exceeded (quota on a template quota)control planethe live-sandbox cap; templates, buildsQueued or owned on a create; active on an activation; on an OIDC deployment, too many sign-ins waitingfree one (sbx rm, retire) or ask an admin; for buildsQueued, wait for a queue slot; for a login start, back off
429bundle_quota_exceededcontrol planethe config-bundle byte budget is fulldelete bundles you no longer need, or ask the operator
429async_quota_exhaustedcontrol planeyou already hold your cap of queued async turnswait for one to finish
429subject_quota_exceededharnessyou already hold your share of in-flight turns on this workerretry after Retry-After
429overloadedsupervisorthe host is full; refused before the turn reached a worker (not in harness-openapi.yaml)retry after Retry-After
500internal_errorbotha server fault (on the harness, also a template seed that failed)not retryable as is; report it
501workload_runs_unavailablebotha run or async turn names a workload on a deployment without workloadsdo not retry; drop the workload
502identity_provider_misconfiguredcontrol planethe deployment's OAuth app is misconfigureddo not retry; tell the operator
503redis_unavailable, credential_unavailable, model_catalog_unavailablecontrol planea dependency is down; no Retry-Afterback off and retry
503sandbox_unavailable, credential_unavailable, redis_unavailableharnessno sandbox capacity now, the control-plane exchange failed, or Redis did not answerretry the same turn after Retry-After

A replayed refresh token that was superseded more than the grace window ago revokes the whole login; the server records that, and the client sees only 400 invalid_grant.

gRPC (SandboxExec). The status codes and their causes are in Outcomes versus failures. What a client does about them:

StatusWhat a client should do
UNAUTHENTICATEDmint a new sandbox token once and retry with the same req_id, only if no event of the call had arrived
RESOURCE_EXHAUSTED "sandbox busy"nothing ran: send it again as a new Exec with a new req_id, after a backoff
DEADLINE_EXCEEDED "sandbox token expired during the Exec"never retry as is: shorten or split the command
PERMISSION_DENIED, INVALID_ARGUMENT, ALREADY_EXISTSfix the request (sandbox_id, workspace_key, req_id); a LeaseControl set_mode re-mints its set-mode token once
an error event or a non-OK status after the first eventthe command may have run: report it, never run it again

Exit codes​

Per-command detail is in the generated references: mocactl sbx and mocactl. The exits of sbx.py are in The examples.

Codemocactl sbxmocactl
the command's ownsbx run: the command ran and exited with it
0okok
1failed (also a refusal of the control plane)failed (the turn, or the control plane refused)
2usage errorusage or setup problem, including not logged in
3log in firstauth token: log in first; promote: a credential would reach a shared store
4the control plane is unreachableauth token: the control plane is unreachable
5a wait timed out (templates follow, activate --wait, retire --wait, a create waiting for a queue slot); nothing was undone
75sbx run, sbx put: refused before it started, on every try; nothing ran
124sbx run: the command timed out, or was killed
125sbx run, sbx put: the sandbox failed; there is no exit status
130interrupted (Ctrl-C); a build already queued goes oncancelled (Ctrl-C)

Quotas and limits​

The defaults a client runs into are documented with what they bound:

  • Per sandbox: two Execs in flight (one running, one waiting; a third is refused as busy), 16 MiB per gRPC message, 8 MiB of stdout per call, and a longest command of one token lifetime minus 60 s (14 minutes by default) — Calling the sandbox API, Limits.
  • Per user: 3 live sandboxes by default, a 7-day idle lifetime, and how delete and removal take effect — Limits.
  • Templates: your template quotas (templates, buildsQueued, active, owned) and their use: GET /v1/quota (mocactl sbx quota); a refusal is 429 quota_exceeded naming the quota (above).

When to retry​

  • Send the same call again after Retry-After: 409 template_not_active and 409 no_active_slot on the control plane; every harness 503; the harness's 429 subject_quota_exceeded and the supervisor's 429 overloaded. mocactl waits 30 s when a control-plane refusal carries no Retry-After, and gives a sandbox create 10 minutes in all.
  • Back off and retry: a control-plane 503 (it sends no Retry-After) and an unreachable control plane, as mocactl's pollers do; 429 quota_exceeded with quota: buildsQueued, until your own timeout; a login start's 429 quota_exceeded, a few times, never in a tight loop.
  • Poll at the interval the server gave: 428 authorization_pending, every interval seconds until expiresIn runs out.
  • Refresh, then retry once: a 401 with token_required, token_invalid or token_expired; gRPC UNAUTHENTICATED if no event of the call had arrived (same req_id). A second 401 means the new token is no better: stop.
  • Send again as a new Exec, with backoff: a refusal before start (RESOURCE_EXHAUSTED "sandbox busy", or the worker's memory-budget:, max-runs:, busy: queue full). mocactl sbx run and put retry 4 times by default (MOCACTL_SBX_BUSY_RETRIES, at most 20), after about 1, 2, 4 and 8 s with jitter, then exit 75. Each wait spends the sandbox token's lifetime.
  • Never retry as is: anything after an Exec's first event (the command may have run); DEADLINE_EXCEEDED; a 4xx that names a rule, a quota you must free, or a conflict; 422 config_bundle_unsupported; 500 internal_error; 501 workload_runs_unavailable; 502 identity_provider_misconfigured.

A detachable turn whose stream dropped is not sent again: attach to it with GET /v1/turn and the last event id received, as in Detachable turns.