API changelog
The version is info.version in openapi.yaml for the control plane and in
harness-openapi.yaml for the data plane: the minor is bumped for additive
changes, the major only with a /v2 (change policy, decision 5).
Each section below is a control-plane version. A data-plane version is described in the section
that shipped it ("The data plane's twin … goes to"):
harness-openapi.yaml | Shipped with |
|---|---|
| 1.7.0 | 1.31.0 |
| 1.6.0 | 1.30.0 |
| 1.5.0 | 1.28.0 |
| 1.4.0 | 1.26.0 |
| 1.3.0 | 1.17.0 |
| 1.2.0 | 1.16.0 |
| 1.1.0 | 1.15.0 |
| 1.0.0 | the first document, 2026-10-09 |
1.34.0​
A client is told about turn state changes instead of polling for them (#392). Additive on the wire: one new route.
GET /v1/eventsstreams the caller's own turn transitions as Server-Sent Events, oldest first, resumable by the cursor each event carries (?since=<cursor>). Eachturnframe's data is the newTurnEvent: the session, the turn, the state, the attempt count, and the terminal reason or the gate when there is one. Withoutsincethe stream starts from now.- Events are retained as long as a turn record (
MOCA_TURN_RESULT_TTL_SECONDS) and bounded to the newest 500 per subject. A client whose cursor fell out of that window — including a subject idle long enough to lose the whole log — is told so by agapframe before any transition, rather than silently resuming with a hole.since=0-0asks for everything retained and is never a gap: it is not a cursor the service issues, so its holder cannot have missed one. - Deleting a session does not delete the events already emitted for its turns; they age out with the
rest of the subject's log. An event names a session that
GET /v1/sessions/{id}may 404. - A stream is scoped to the token's subject, and the server ends it after an hour.
1.33.0​
A retire no longer strands a template's default tag on a retired build
(#909). Additive on the wire: one field on three
answers.
- A retire (
DELETE /v1/templates/{id}/builds/{build}orPOST /v1/templates/{id}/retire) that ends the builddefaultnames movesdefaultto the newest registered build it leaves, writes atagrecord for the move (as an owner's tag does) and says so in the answer's newdefault(DefaultTagMove: the build it names now, the one before, the record). Before,defaultkept naming the retired build, and every create through a bare id was refused410 template_retiredwhile another build was registered. - A reject (
POST …/builds/{build}/reject) of the builddefaultnames moves it the same way, and its answer gainsdefaulttoo: a create naming a rejected build answers400 unknown_template, so leavingdefaultthere was worse than a retire. - With no registered build left,
defaultstays anddefaultin the answer is null, and the next build to register takesdefault, with atagrecord (until now only a template's first build did). - The
410 template_retiredfor a tag that names a retired build now names the tag and the fix (tag another build, or pin one). - A superseding rebuild is unchanged: it keeps the twin's id, so its tags already follow.
1.32.0​
An async turn's assistant reply is fetchable (#381). Additive: a second artifact kind on an existing route, no new route or field, and the data plane is untouched.
GET …/turns/{turnId}/artifacts/{kind}now servestextas well aspatch— the reply whole, astext/plain; charset=utf-8. Until nowTurnStatus.result.summarywas the only way to read a prompt turn's answer, clipped toMOCA_TURN_SUMMARY_BYTES(2048), so a longer answer could not be read back at all; #390 moved the text out of the polled body without giving it a route.TurnStatus.result.artifacts[].kindgainstext, listed afterpatch. Atextentry carries nosha256: nothing hashes the reply on the way in, and the fetch route hashes the bytes it serves for theETag. A client that readsartifacts[0]and assumespatchmust checkkind— a prompt turn that edited no files now has one entry, and it istext.- A capture refused for size (
workspace.patchRefused) previously had no artifacts at all; it now has itstext. The patch is still absent, for the same reason as before.
1.31.0​
A workspace reset on the session's own sandbox is reported (#338, option 2). Additive on the wire: no new field, route or frame, and no change to the sandbox protocol.
GET /v1/sessions/{id}/resources:placement.workspaceResetnow also records a workspace that was reclaimed where the session is. Itsfromis then the sandbox the session is still on, not one it left.
The data plane's twin, harness-openapi.yaml, goes to 1.7.0: the
workspace_reset frame's and TurnPlacement.workspaceReset's reason gains reclaimed. The
harness keeps a marker file (.moca-session, holding the workspace key) in the session's
workspace and records in the session's log that it wrote it; a later turn that finds the record
but not the file reports the reset before the agent runs, and tells the model in a separate
message (workspace_reset) beside the prompt, which is left as sent. A client that does not know reclaimed should treat it as any reset: the earlier
files are gone. mocactl before this release prints it as a gone sandbox.
1.30.0​
Per-turn budgets, and cancelling a turn that is already running
(#391), per the
async fan-out spec §4.3 and §4.5. The data plane's
twin goes to 1.6.0 with it. One narrowing on the wire, deliberate and named below — allowed
because /v1 is Preview (maturity), and recorded here
because that is what Preview requires.
caps.costUsdis removed fromPOST /v1/sessions/{id}/turns; a submission that names it is refused400 invalid_request, with a message pointing atcaps.tokens. It was accepted and recorded and never enforceable — nothing in MOCA prices a token — so every caller that set it got an unbounded turn and no warning. Refusing it is the honest answer; a caller wanting a spend bound usescaps.tokens.caps.tokensandcaps.wallClockare now enforced. A turn that reaches its token cap has its tool calls refused from that point and endsfailedwithresult.reason: "budget"; so does one that outrunswallClock, counted from the moment a worker dequeues it and clamped to the deployment'sMOCA_TURN_MAX_S. The data plane'sbudgetjoins the failed-reason enum, and itsTurnResultgainsbudgetExceeded(the loop reportsend_turnwhen every call was refused, so the cap firing is otherwise invisible). Both caps are per delivery: a worker that dies mid-leaf has its turn redelivered, and the retry gets a fresh token budget and a wall clock anchored at its own dequeue, because a retry must not fail on its predecessor's spend. Across a turn's deliveries the aggregate can therefore reach the cap times the delivery limit (three).subject_quota_exceededon the data plane's/v1/turnnow counts the caller's running queued turns too.SH_TURNS_PER_SUBJECTis one budget per subject across both paths, so a caller whose async fan-out is executing can be refused an interactive turn it would previously have been given. Nothing new on the wire -- the same 429, the same code -- but the condition is wider. On the queue side there is no refusal at all: an entry claimed past its owner's cap is handed back unrun and retried, with its attempt budget untouched. This bounds MIXED load only -- a worker runs one queued leaf at a time, so an owner's async-only fan-out never reaches the cap, and the queue is still one FIFO stream. A deep async backlog from one owner therefore still delays another owner's async turn. (Since then:MOCA_ASYNC_RUNNING_PER_OWNERbounds that one too, cluster-wide, and is off unless an operator sets it. No wire change, so it has no section of its own.)DELETE /v1/sessions/{id}/turns/{turnId}now cancels a running turn as well as a queued one. It answers202with{turnId, state: "running", cancelRequested: true}; the worker stops the leaf within a few seconds, releases its sandbox, and the turn reachescancelled.409turn_not_cancellableis now only for an already-terminal turn, and a leaf that finishes first stays finished — which is why both answers are202.TurnStatusgainscancelRequested(trueonly on a running turn whose cancel is in flight), and itsresultdocumentation is corrected: a leaf result ofabortedreadsstate: "cancelled", notfailed. That has always been the behaviour; cancel is what makes it load-bearing.POST /internal/turn-credentialsreturnsturnExpin every tenancy mode, not onlygrant: it is the deadline the worker enforces, so a single-tenant deployment got an unenforceablecaps.wallClockwithout it.caps.costUsdis gone from that body too.
1.29.0​
A per-source bound on login starts (#716). Additive.
POST /v1/auth/devicenow documents its429 quota_exceeded, which the oidc provider has answered since it shipped (the 10,000-state total cap) and which now has a second cause: one client address holdingSH_OIDC_MAX_PENDING_PER_SOURCE(default 20) live login states. The message tells the two apart ("...from this address"); the code and the status are the same. The address is the socket peer, or the X-Forwarded-For entrySH_TRUSTED_PROXY_HOPSnames (the socket peer when the header holds fewer entries than that). The GitHub provider is unchanged.- For a deployment with its own
PendingAuthStore(the control plane's extension point for a shared pending-login store):putnow answers which bound refused the entry ('parked','full'or'source_full') instead of a boolean. A store still answering the boolean keeps working:truereads as parked andfalseas the total cap's refusal. To enforce the per-source bound, a store answers'source_full'.
1.28.0​
A config bundle's format version, checked where a bundle is stored and where it is applied (#510), per the change policy (decision 7). Additive on the wire.
- POST /v1/config-bundles refuses a bundle whose
format.jsonnames a format newer than this release reads, or is not a format version, with400 invalid_requestand the reason inmessage. A bundle withoutformat.jsonis format 1, so every bundle stored before it existed keeps its digest and stays usable.
The data plane's twin, harness-openapi.yaml, goes to 1.5.0: POST /v1/turn
answers 422 config_bundle_unsupported when the session's bundle is stored and intact but in a
format the harness does not read, with the reason and what to upgrade in message, on the sync
path and before the first SSE frame alike; after it, the terminal error frame carries the same
reason.
1.27.0​
The base URL says what it is (#779). Additive on the wire.
GET /answers200with a shorttext/plainpage on every profile: that this is a Moca control plane, where its API is (/v1, andGET /v1/discovery), how to installmocactland log in, and that a sandbox's egress is an allowlist the operator extends. Before, it was the unknown-path404 not_found. The page names no URL of the deployment and echoes nothing of the request. Its wording is not a contract: a client reads/v1/discovery.
1.26.0​
Per-turn artifacts and a bounded status read
(#390), per the
async fan-out spec §4.4 and §9.2. The data plane's
twin goes to 1.4.0 with it. One narrowing on the wire, deliberate and named below — allowed
because /v1 is Preview (maturity), and recorded here
because that is what Preview requires.
GET /v1/sessions/{id}/turns/{turnId}no longer inlines the turn's OUTPUT.result.patchandresult.textare removed from that body: the route is polled, and a 4 MiB patch rode every poll. In their place, additively:result.summary(one line — the assistant's text, a gate's summary, the patch's diffstat or the failure's reason — clipped toMOCA_TURN_SUMMARY_BYTES, default 2048 bytes),result.artifacts([{kind, bytes, sha256?}]) andresult.workspaceon a solve result as well as arespondedone. The synchronousPOST /v1/runsandGET /runs/statusbodies are untouched — they still carrypatchandtextin full.- The same cap now holds every model-written string in that body, not just
summary:result.verdict.reasonandresult.gate.summary/proposed_actionare clipped toMOCA_TURN_SUMMARY_BYTESwith the same trailing…[truncated]. Nothing upstream caps them, so unclipped they kept adoneturn's polled body unbounded. The cap bounds each string's CONTENT, so a clipped one isMOCA_TURN_SUMMARY_BYTESplus that 14-byte marker.MOCA_TURN_SUMMARY_BYTES=0omits all four keys rather than returning a bare marker;verdictandgatekeep their shaped fields (item_id,verdict,gateId), so a client can still branch on them. GET /v1/sessions/{id}/turns/{turnId}/artifacts/{kind}serves the output whole: bytes, withtext/x-diffand anETag— always"sha256:<hex>", the one formatresult.artifacts[].sha256uses: the capture's own digest when the record carries one, else a digest of the bytes served.If-None-Matchis not honoured, so the ETag is for comparison, not for skipping a fetch.patchis the only kind. Every absence is 404 (unknown kind, a turn not yet terminal, no stored result, a capture refused for size).- The data plane's
TurnWorkspacegainsdiffstat({files, insertions, deletions}), counted from the diff's hunks and present even whenpatchRefusedleft the bytes behind;LeafResult'ssolvedbranch gainsworkspace, the descriptor (baseline,patchSha256,patchBytes,diffstat) for the patch inpatch.RunStatus'ssolvedbranch is unchanged. - Async results and turn records are kept for 7 days by default, up from 24 h
(
LEAF_RESULT_TTL_SECONDS604800), so a Friday turn is still readable on Monday. Not a wire change; it is what makes the two routes above worth polling.
1.25.0​
A sandbox's lifetime counts idle time (#770), per the idle-lifetime design §3 and §4.2. Additive on the wire.
- POST /v1/sandboxes takes
idleLifetimeS(integer, 3600 to the deployment's maximum; omitted is the default lifetime), and everySandboxcarries it. - Activity mints slide
expiresAt: POST /v1/sandboxes/{id}/token, POST /v1/sandboxes/{id}/mode-token and PUT /v1/sandboxes/{id}/mode move it to at least now plus the sandbox'sidleLifetimeS(clamped to the maximum as it is now), never backwards. Reads and lists do not. The move applies only when SH_SANDBOX_MAX_LIFETIME_SECONDS is configured; unset, the deadline stays fixed at creation as before. - POST /v1/sandboxes/{id}/token and /mode-token accept an optional body
{ "activity": false }: a mint that runs no command (a lease keepalive) leaves the deadline where it is. A non-booleanactivityis400 invalid_request; body validation precedes state, so that answer also holds on a terminated sandbox (not409 sandbox_terminated). - POST /v1/sandboxes/{id}/token returns
sandboxExpiresAt, the sandbox'sexpiresAtafter the mint; it moves, so track it. The token'sexpis capped at it. - PUT /v1/sandboxes/{id}/mode refuses a body naming
activity(400 invalid_request): a mode change always counts as activity. - Stored data: the record hash gains
idleLifetimeS, and a touch rewritesexpiresAt, thelivescore and the TTLs. An older control plane reads the movedexpiresAtcorrectly and ignores the field.
1.24.0​
Grants at dequeue under MOCA_TENANCY=multi
(#388), per the
multi-user isolation design §6.1 and the
async fan-out spec §5.4. Additive on the wire; the
one removal is an error code no caller can receive any more.
- POST /internal/turn-credentials returns MI1 §6.1 grants under
MOCA_TENANCY=multi:mode: grant, the inference grant asanthropicAuthToken, the inference listener asanthropicBaseUrl, plussandboxGrantandturnExp(unix seconds, anchored at the DEQUEUE and clamped tomin(caps.wallClock, MOCA_TURN_MAX_S)). No credential value leaves the control plane undermulti. Undersinglethe response is unchanged,directorplaceholder. async_tenancy_unsupported(501) is removed from the error taxonomy: no caller can receive it any more, on any route. Async submission and the dequeue claim both work undermulti. The refusal did not disappear, it changed shape — amultideployment withoutMOCA_GRANT_SIGNING_KEYandMOCA_INFERENCE_ADDRrefuses to BOOT, so an operator meets it once at startup instead of per turn.- The control plane listens on a SECOND port when
MOCA_INFERENCE_ADDRis set: a transparent inference proxy that accepts an inference grant as its bearer and swaps it for the session's credential. Not part of the REST surface and deliberately not described in this document's paths — it forwards whatever the model API sends, unchanged.
1.23.0​
A template create reuses a registered build only while a host holds its snapshot, and the
rebuild it admits otherwise supersedes the old build
(#816), as the
template lifecycle spec §4
(Reuse) and §6.1 ask. No route or error code changes, and one value is added (reason.step: superseded); when a create is answered reused: true changes, and so does what a rebuild of the
same snapshot registers as.
- POST /v1/templates and POST /v1/templates/{id}/builds: on a deployment with host agents, a
registered build with the same inputs is reused (
200,reused: true) only while a fresh host (its last inventory at most HOST_STALE_S, 360 s, old, as placement counts hosts) holds its manifest hash. When fresh hosts report and none holds it, the create is admitted as a new build (202, noreused), the old build's rebuild, with the usual quota and gate checks, instead of an answer naming a build whose sandbox create is refused409 template_unavailable. When no fresh host reports at all (right after a control-plane restart, or the only host silent), holding is unknown and the registered build is reused as before. A build on its way (queuedtobuilt) is reused as before, and a deployment without host agents is unchanged. - Registration: that rebuild has the old build's manifest hash. When the old build is still
registered, the host that claimed the rebuild did not already hold the snapshot, and no fresh
host holds the hash but the one reporting the rebuild (which has just built it), the rebuild
registers and supersedes the old build in the same update: the old build becomes
retiredwithreason: {step: superseded}and keeps its build id, its live leases move to the new build, and the tags that named it,defaultincluded, name the new build. Aretirerecord bypolicynames both builds. Otherwise the rebuild is rejected, ruleT.unique, as before: when another fresh host holds the hash, or when the claiming host already held it (it found the snapshot already built), the old build staying registered with its leases. Only that rebuild supersedes: any other build with the same hash (another profile or gate record) is rejectedT.unique, as before, whoever holds the snapshot. - GET /v1/templates/{id}/builds/{build}, DELETE /v1/templates/{id}/builds/{build}, POST
/v1/templates/{id}/builds/{build}/reject, activate
{build}, tags andid@<build>: a build id a superseded build shares names the build that took it over; the superseded build is found by its handle. A superseded build lists no tags.
1.22.0​
A retire, or an admin's reject, is refused while an active Moca Pi session is pinned to the build
(#817), per the
template lifecycle spec §5.1
and §5.2. No route, field or error code is added; 409 build_in_use gains a cause.
- POST /v1/templates/{id}/retire, DELETE /v1/templates/{id}/builds/{build} and
POST /v1/templates/{id}/builds/{build}/reject: refused
409 build_in_use("is pinned by an active session") while an active session created with a sandbox template is pinned to the build, as while a live sandbox runs on it. Deleting the session lets the retire or reject through. Before, only live sandboxes counted, so a retire could stop the worker and remove the snapshot a pinned session's next turn needs. - Stored data: a new sorted set per build,
sh:cp:build:<hash of the build id>:sessions, of the sessions pinned to it: added at session create, removed by the delete cascade, and pruned of members that are no longer active as a retire or reject checks it. An older control plane ignores it. Sessions created before it existed are not in it, so they never block a retire.
1.21.0​
Admins set template quotas per subject, and reject a registered build after the fact
(#748), per the
template lifecycle spec §5.2. Every
change is additive; the routes mount on both route profiles and need SH_PROVENANCE_DIR (else
400 invalid_request).
- New PUT /v1/quota/{subject} (admin):
subjectisdefault(the deployment default) or a subject,github:<numeric id>oroidc:<provider sub>(nevertest:<n>), for an override; the body is a Quota, ornullto remove a subject's override (the default is never removed). Each change is a newpolicyrecord naming the admin. Answers{target, subject, quota, before, policy, record}: the quota now and before (null: no override), the new policy's digest and the record's. Enforced at once on creates, queued builds and activations. A quota holdstemplates,buildsQueuedandactive, and optionallyowned(another key is400 invalid_request); a body withoutownedleaves the target'sownedas it is. An optional?expect=(JSON: the quota the client read,nullfor no override) makes the write a compare-and-set on all four counters (an unsetownedmatches only an unset one): when the target's quota is not that value now, nothing is written and the answer is the new code409 quota_changed. - Policy gains
quotaBySubject, the per-subject overrides ofquota, keyed by subject; a key that is not a subject, or a malformed quota, is400 invalid_request. An override'sownedis optional: without it, the subject'sownedis the default's (else 200). - PUT /v1/policy gains an optional
?expect=, thedigestGET /v1/policy answered: the write is made only if the policy's digest is that value now, else nothing is written or recorded and the answer is the new code409 policy_changed, whosedigestis the policy's now. So a policy written from an older read never drops a quota (or policy) another admin wrote since. Anexpectthat is notsha256:and 64 lowercase hex digits is400 invalid_request. Without it, the policy is stored as sent, as before. - GET /v1/quota answers the limits that apply to the caller (its override, else the default) and
gains
quotaSource,subjectordefault, andownedSource, the same forownedalone (an override may leaveownedto the default). - New POST /v1/templates/{id}/builds/{build}/reject
{reason}(admin; the reason is required): a registered build becomesrejectedwithreason.ruleadmin, its activation leases go, a host holding it finds it in the wanted state'sstop(as a retired build, but never inremove: its worker is stopped, not removed, and noremovedreport is taken for it) and itsdetachedreport is taken, and a sandbox create naming it answers400 unknown_template. Arejectrecord names the admin,from, the reason andbuildRecord(the digest of the build'sbuildrecord). Answers{templateId, subject, build, buildId, record, status: rejected}; idempotent (record: null). Refused409 build_in_usewhile a live sandbox runs on the build; any status butregisteredis400 invalid_request. Not reversible. - A rejected build (by policy or by an admin) keeps no snapshot or worker for a retired build that
shares it: the retired build is stopped and removed as any retired build is (no longer
shared), while the rejected build itself is only stopped.
1.20.0​
Enrollment and the admin role through the API
(#739), per the
enrollment and roles spec. Every change is
additive; without SH_PROVENANCE_DIR nothing changes.
- New GET /v1/subjects (every enrolled subject with its roles, each with
source: env | api), PUT and DELETE /v1/subjects/{subject} (enroll with{"enrolled": true}, unenroll), and PUT and DELETE /v1/subjects/{subject}/roles/admin (grant, with an optionaluntilin epoch seconds, at most 366 days ahead; revoke), on both route profiles. Any admin reads the list; only an admin named inSH_ADMIN_SUBJECTSchanges it (403 forbiddenotherwise). The same holds for a PUT /v1/policy that widens the policy (a trusted gate record, a registry or a repository added; a profile added or loosened: a rule dropped fromrequires,requireOfflineGateoff,selfAttestorselfAttestEgresson, an envelope bound raised or removed, itsexactsize changed or removed; or adefaultProfilethat accepts more): an admin by an API grant may narrow it (a profile removed is a narrowing) and change its quotas. Each change answers the subject with therecordit wrote (null when nothing changed). With no store the routes answer400 invalid_request. ASubjectcarriesstoreEnrolled(the store's own enrollment, apart from the settings and any role); enrolling a subject the settings enroll writes nothing (record: null). - A subject on these routes is
github:<numeric id>oroidc:<provider sub>(the sub pattern the OIDC login verifies);test:<n>and anything else is400 invalid_request. NewSubjectschema. - New error codes
bootstrap_subject(409: unenrolling or revoking a subject the settings enroll or make admin) andself_revoke(409: an admin revoking its own role). - With a store, roles and enrollment are evaluated per request: the control plane replaces a
verified token's
roleswith the subject's roles now, so a grant, a revoke or a lapseduntiltakes effect at the subject's next request. The login, the refresh and the egress owner check use the same evaluation. Without a store the token's claims stand, as before. - Each change is a record on a new
membersprovenance stream:member {subject, enrolled, before}androle {subject, role, state: granted | revoked | expired, until, before}, naming the acting admin (control-planefor anexpired, written once).verify-provenance.pyandverifyExportaccept the two kinds on that stream only.
1.19.0​
The host agent removes a retired build's worker and snapshot (#743), per the template lifecycle spec §6.1 step 7. Every change is additive.
- GET /v1/hosts/{host}/wanted gains
remove: the retired builds the host holds with no live sandbox and no pinned session's hold on their worker, each also instop; while a sandbox that ended on the worker is still inegressSids(less than 600 s ago), it is instoponly, so its last egress events are still taken. The agent stops a running worker, then uninstalls it (install-host.sh --uninstall --keep-shared: its own files only), deletes the snapshot and its template record, and reports it. A worker with a live sandbox is in no list, nor is a retired build whose build id or worker a build that is not retired shares (in any template): its snapshot or worker is still needed. - POST /v1/hosts/{host}/workers/report takes
removedfor a retired build the host holds: aretirerecord byhost:<id>withevent: removedandbuildRecord(the digest of the build'sbuildrecord). The host no longer holds the build, so TemplateBuild'sheldBydrops it at once, before the host's next inventory. Aremovedfor a build the wanted state leaves out because a build not retired shares it is refused409 build_in_use.
1.18.0​
Retire a template, or one build of it (#749), per the
template lifecycle spec §5.1. Every
change is additive; the routes mount on both route profiles and need SH_PROVENANCE_DIR (else
400 invalid_request).
- New POST /v1/templates/{id}/retire
{reason?}(the owner, or an admin): every build not yet retired becomesretired, its activation leases go, and each writes aretirerecord naming the caller,from(the status before),buildRecord(the digest of the build'sbuildrecord, null for one never built) and the reason; earlier records stay. Answers{templateId, subject, status, builds}, each build a newRetiredBuild{build, buildId, readiness, record}. Idempotent: an already retired build is listed withrecord: nulland no second record. Not reversible: a new build is the way back, and the id stays its owner's. - New DELETE /v1/templates/{id}/builds/{build}: retires one build, by build id or handle, answering
one
RetiredBuildwithtemplateId,subjectandstatus. - New codes:
409 build_in_use, a retire refused while a live sandbox runs on the build;410 template_retired, a sandbox create or an activation naming a retired build, a tag of one, or a template whose every build is retired (was400 unknown_templateor409 template_unavailable). - Readiness gains
retired(Template, TemplateBuild). TemplateBuild gainsheldBy, the hosts whose last inventory holds its snapshot, a host gone silent too (null without host agents). A retired build whose worker still holds a presence record reportscapacity{running, inUse}, as an active one does (null once its worker is stopped;running: nullwhen presence cannot be read). TemplateBuild gainsshared, true for a retired build whose snapshot or worker a build that is not retired also uses: its worker is kept for that build, and itscapacityis null. - GET /v1/hosts/{host}/wanted:
stopalso lists the retired builds the host holds with no live sandbox, except asharedone; and one worker id is never in bothrunandstop(two registered builds from one image share it); POST /v1/hosts/{host}/workers/report takesdetachedfor a retired build. Removing a retired build's worker and snapshot from its host is not part of this version.
1.17.0​
A session's seed from its build, its workspace's patch, its records, and its queued turns on its template (#751), per the session templates spec §5-§5.2 and the template lifecycle spec §7.1. Additive.
- POST /internal/credentials: for a session pinned to a manifest-hash build through the template
store,
sandboxSeedis that build's ownspec.seed(none when the build has none), andsandboxSeedSource(buildordeclared) is sent with any seed. - POST /internal/turn-credentials returns
sandboxTemplate,sandboxSeed,sandboxSeedSourceandsandboxBuildIdas POST /internal/credentials does, so a queued turn of a templated session runs on its template's workers, pinned to its build, and seeded. - GET /v1/sessions/{id}/turns/{turnId}: a
respondedresult of a templated session carriesworkspace(the patch after the turn) and, with a seed,seed({source, buildId?}). - With a template store, a session whose template resolved through it writes a
sessionrecord ontemplate/<id>at creation (state: created, with its build, manifest hash and lease) and at delete (state: terminated,reason: deleted,endedAt).
The data plane's twin, harness-openapi.yaml, goes to 1.3.0: a templated
session's turn result (and its terminal done and error frames) carries workspace
(TurnWorkspace: the patch from the seed's baseline commit, whole or refused over
SH_TURN_PATCH_MAX_BYTES, never cut) and sandbox.seed; a /v1/runs prompt run of a templated
session runs on its template and its responded result carries both too.
1.16.0​
Sessions and sandboxes from one combined control plane
(#750), per the
combined control plane spec. Additive: the
harness and sandbox profiles answer as before.
SH_ROUTE_PROFILE=combinedmounts every route of both profiles. Its GET /v1/discovery answersprofile: "combined"with the harness fields plusexecEndpointandexecCa.- On
combinedlogin is open, as onharness; the sandbox routes and the template writes need an enrolled subject (403 not_enrolledotherwise, test users included), and the template, policy and quota reads take any logged-in subject. Its API tokens carry the harness issuer. - With a template store (
SH_PROVENANCE_DIR), POST /v1/sessions resolvessandbox.templatethrough it as POST /v1/sandboxes does:id,id:tagorid@sha256:…, else 400unknown_template; the build is kept for the session's life.sandbox.activate(default true) and activation on first use apply: 409template_not_activewith Retry-After, orno_active_slot,template_unavailable. Only a subject enrolled for sandboxes starts an activation; oncombinedanother subject waits (409) on one already starting and is refused (403 not_enrolled) on a template nobody is starting. The activation is the create's last check, so a create refused for another reason holds no lease. - The
Sessionview addssandboxBuildIdandtemplateManifestHashbesidesandboxTemplate. - POST /internal/credentials returns
sandboxBuildIdfor a session pinned to a manifest-hash build. Each exchange of such a session (and of its queued turns) keeps that build's worker running for the hosts' idle limit from the turn, as a live sandbox does (GET /v1/hosts/{host}/wanted leaves it out ofstop), when the session's subject is enrolled for sandboxes; it starts no worker and takes no lease. A turn of a subject not enrolled runs while the worker is up but extends nothing.
The data plane's twin, harness-openapi.yaml, goes to 1.2.0: a session pinned
to a build runs only on workers labelled moca.dev/build with it, and its turn is refused (503
sandbox_unavailable) when none is attached.
1.15.0​
Sandbox templates for agent sessions
(#731), per the
session templates spec. Additive: a
deployment that does not set SH_SANDBOX_TEMPLATES on the harness profile answers exactly as
before.
- POST /v1/sessions accepts
sandbox.template, fixed for the session's life. A non-string is 400invalid_request; so is an id the deployment does not declare (the message lists the declared ids), and any template on a deployment that declares none. - The
Sessionview gainssandboxTemplate(null for none) on a deployment that declares templates, and for any session that named one. - GET /v1/discovery gains
sandboxTemplates: [{id, description, tools}], the declared templates without their seeds; absent when none are declared. - POST /internal/credentials returns
sandboxTemplateandsandboxSeedfor a session that named a template, and neither otherwise. A template the deployment no longer declares is still returned, without a seed, so its turns are refused rather than run on an untemplated worker.
The data plane's twin, harness-openapi.yaml, goes to 1.1.0: authenticated
turns take the session's template from the control plane, a failed seed is a 500, and
workspace_reset's retiered also covers a sandbox that now serves another template.
1.14.0​
Per-sandbox egress records (#752), per the egress records spec: what a sandbox reached through the KVM host's egress proxy, readable through the API and named in the sandbox's provenance. Every change is additive.
- New GET /v1/sandboxes/{id}/egress?after=&limit= (the owner or an admin, as GET /v1/sandboxes/{id})
gives
{events, next, summary}. The events are the proxy's audit events exactly as it wrote them (newEgressEventschema), in arrival order.summary(newEgressSummaryschema) is{byHost: {host: {count, decisions, bytesUp, bytesDown}}, total, dropped, droppedBy: {proxy, cap, budget, invalid}, complete, sealed, sha256}, on the first page (noafter); null on the pages after it. ?format=ndjsongives the whole log asapplication/x-ndjson: each event's canonical JSON, each followed by\n. Its sha256 issummary.sha256.- New POST /v1/hosts/{host}/egress
{events, cursor, oversized?}(host bearer): the host agent's batches of up to 1000 events and its journal cursor, idempotent by (host, cursor), answering{accepted, refused, capped, overBudget, invalid, dropped, cursor}. A log holds at most 10,000 events and 4 MiB of lines, and all logs together at most 64 MiB of lines; the rest count as dropped. - GET /v1/hosts/{host}/wanted gains
egressSids, the workspace keys whose events the host ships (the set the egress route accepts); the agent sends no other sandbox's or session's events. - The
sandboxprovenance record that ends a sandbox (state: terminated) gainsegress: {events, sha256, dropped, droppedBy, complete}. Events that arrive in the 600 s after the end are still taken; if any did, one moresandboxrecord withstate: egressnames the final log. No record kind is added.
1.13.0​
Pacing template workers' cold starts (#745), per the
template lifecycle spec §6.5: a
KVM host starts at most SBX_START_CONCURRENCY (default 4) workers at once, an activation waiting
for a start slot says so, and an optional idle grace (SBX_IDLE_GRACE_S, default 0, off) keeps a
released build's worker running for a while. The start limit is the host agent's, so it holds with
an older control plane too. Every change is additive.
GET /v1/hosts/{host}/wantedgainsstarting: [buildId]: the builds ofrunwhose worker is not attached to the relay (its presence, as readiness reads it), inrun's order.runis now in the wanted order, first leased first. Withoutstarting(an older control plane, or the presence unreadable) the agent counts its own starts of the lastSBX_START_WINDOW_S(default 300). Withstarting, a listed worker counts forSBX_START_WINDOW_Sat most: one not attached after it is stuck (an error line each run) and holds no start slot.POST /v1/hosts/{host}/inventory'slimitstake optionalstartConcurrency,startSeconds(the mean of the agent's last cold starts, start to attach) andidleGraceSeconds(0-86400). Without them (an older agent) nothing changes; an older control plane ignores them.- A build
activatingon such a host gainsqueuedandqueuePosition(1-based, among its host's placed, wanted builds not attached yet, first leased first);queuedis true beyond the host'sstartConcurrency. 409 template_not_active's Retry-After isceil(ceil(queuePosition / startConcurrency) × startSeconds)when the host reports both; else 30 s, as before. A queued activation staysactivatinglonger than before: a client polls with a timeout sized for the host's whole start line.- A build whose worker already runs on a holder needs no start: it stays there (1.12.0's sticky placement), whether or not the host reports memory figures; a graced build leased again too.
- The idle grace runs from the build's last lease end (a release's time, or an expired lease's
until), for a worker the agent reports running with no live sandbox, while the host has room underactiveLimitbeside the workers it counts (active.used: graced ones are counted apart) and its memory headroom (a graced worker counts as running there). A wanted build that needs the slot or the memory displaces the graced worker that ends soonest; the stop is re-checked for a lease, under the activation lock, when the wanted answer is made. The wanted answer gainsgraced: [buildId]for a host with a grace: the graced builds, kept inrunafter the wanted ones (the agent starts none of them). POST /v1/templates/{id}/deactivatetakes an optionalstopNow: true: with no lease left, the build skips the grace (stopped at the next poll); thedeactivaterecord carriesstopNow: true.- Builds gain
graced: trueandgracedUntil(epoch seconds) while in a grace; a create on a graced build takes the caller's lease and is served at once. GET /v1/templates' hosts gainstart: {concurrency, seconds, starting, queued}, only for a host whose agent reports it, andidleGraceSecondsandgraced(a count) for a host whose agent sets a grace.
1.12.0​
Placement of template workers by host memory (#744),
per the template lifecycle spec
§6.2: a new worker starts on a host only if the host has the memory for it, whatever its
activeLimit says. Nothing running is evicted. Every change is additive.
POST /v1/hosts/{host}/inventorytakes an optionalmemory: {memTotalMib, memAvailableMib, memFloorMib, memPressureFull10, memPressureLimit, runningWorkers, vmCommittedMib, memfileMismatch}. Without it (an older agent) the host is placed byactiveLimitalone, as before; an older control plane ignores it.- A build costs its guest RAM (
spec.guest_mb) plus 128 MiB, or 4096 + 128 with no recorded guest size. A host's headroom ismin(total − floor − used, available − floor − pending starts), whereusedcounts its running workers, their VMs' committed memory and the builds placed there not started yet. A host whose last inventory is older than 60 s, or whose PSIfull avg10is above its limit, takes no new start. A build in a host'smemfileMismatchis never placed there. 409 no_active_slotgainsreason: memorywhen a holder under its active limit lacks the memory (Retry-After unchanged); at the active limit it answers as before, with noreason.409 template_unavailablegainsreason: memfile_mismatchwhen every holder reports the build's memory file wrong.409 template_not_activewith readinessunavailablecarries the reason too.- Templates and builds gain
readinessReason(not_held | no_slot | memory | memfile_mismatch), present only with readinessunavailable; newReadinessReasonschema. GET /v1/templates' hosts gainmemory: {totalMib, availableMib, floorMib, usedMib, headroomMib, pressureFull10, pressureLimit, brake, runningWorkers, memfileMismatch, reportedAt}, only for a host whose agent reports it;floorMibis the effective floor.
1.11.0​
Activation leases and the hosts' wanted state (#742),
per the template lifecycle spec
§6.2-§6.4. Every change is additive; the template routes mount on both route profiles and need
SH_PROVENANCE_DIR (else 400 invalid_request).
- New POST /v1/templates/{id}/activate
{tag?, build?, leaseSeconds?}: takes or renews the caller's activation lease on a registered build (60-86400 s; default the largestidleLimitSecondsof the hosts that hold it, clamped to 60-86400, else 3600; renewed by calling again, without limit) and answers{templateId, buildId, leaseUntil, host}. A build is wanted running only while a lease stands; a leased build is never evicted. Each grant is anactivaterecord; the lease stores its digest. Refusals keep no lease:409 template_unavailable(no registered build under that reference, or no reporting host holds it),409 no_active_slotwithRetry-After(every holder at itsactiveLimitwith leased builds; the wait is until a build placed on one of its holders loses its last lease),429 quota_exceededwithquota: active. The quota and placement check, the record and the lease write run one activation at a time across all templates. - New POST /v1/templates/{id}/deactivate
{all?}: drops the caller's leases on the template (an admin withall: true, everyone's), answering{templateId, released}, with adeactivaterecord when any is dropped. - New GET /v1/hosts/{host}/wanted (host bearer):
run, the leased builds placed on this host within itsactiveLimit, andstop, the builds it holds with no lease and no live sandbox (and a leased build it runs while placement keeps it on another host); newWantedWorkerschema. Placement is sticky (a running build stays on its host) and counts every worker that stays running on a host: leased builds placed or running there, and unleased ones draining a live sandbox. - POST /v1/hosts/{host}/inventory: each
holdsentry gainsrunning(boolean, default false): whether the build's worker unit runs on the host. - New POST /v1/hosts/{host}/workers/report
{buildId, event, reason?}(host bearer):attached,refusedordetached, recorded asactivateordeactivaterecords byhost:<host>(arefusedrepeating the host's last one for a build still in itsrunis not recorded again:recorded: null); readiness still comes from the relay. - POST /v1/sandboxes: activation on first use. With
SH_TEMPLATE_HOSTSset, a create on a registered build that is notactivetakes the caller's lease (reason: first_useon its record; refused as activate would be) and answers409 template_not_activewithreadinessandRetry-After: 30; a caller already holding a live lease on the build is only answered the wait (no renewal, no record per retry). New body fieldactivate(default true; false starts nothing). No sandbox record is kept while waiting. Without template hosts, nothing changes. A template imported fromSH_SANDBOX_TEMPLATESis never gated, and activate refuses it with400 invalid_request: the deployment runs its worker, and its readiness is that worker's presence alone. Thesandboxrecord'sleaseis now the digest of the caller'sactivaterecord (null without a lease). - Readiness gains
activating,deactivatingandunavailable(Template, TemplateBuild); before any host reports it is the presence alone, as before. - GET /v1/templates:
hostslists each reporting host'sactive {limit, used}(used: the workers placement counts on it),idleLimitSecondsanddisk {freeGb, floorGb}. A host whose last inventory is over 6 minutes old is left out of it and of placement until it reports again. - GET /v1/quota:
active.usedcounts the builds the caller holds a live lease on. - New error codes
no_active_slot,template_unavailableandtemplate_not_active(409); the Error schema gainsreadiness, andquotathe valueactive.
1.10.0​
Template host agents and their routes (#741), per the
template lifecycle spec §6.1 and
§8.2. Every change is additive; the routes mount on both route profiles, need SH_PROVENANCE_DIR
for the builds (else 400 invalid_request), and answer only a host listed in SH_TEMPLATE_HOSTS
(else 401 unauthorized).
- New security scheme
hostToken: one template host's bearer,SH_HOST_TOKEN_<ID>. The host in the path must be the one whose token is presented; no user, admin, janitor or egress token is accepted. - New POST /v1/hosts/{host}/inventory: what the host holds (
holds, each atemplateand itsmanifestHash) and its limits (limits:activeLimit,idleLimitSeconds,buildConcurrency,diskFreeGb,diskFloorGb). - New POST /v1/hosts/{host}/builds/claim
{max}: up to 4 queued builds, oldest first and subjects in turn, each moved tobuildingand held by the host, with its job: the template id, the handle, the image and the spec astemplate-build.shreads it (the template's id and the create's image always win over the spec's own; the guest size is alwaysguest_ram_mb, the value the policy checked), and the gate record's path when the create had one. - New GET /v1/hosts/{host}/blobs/{digest}: a stored document (a gate record) by sha256, base64 of its exact bytes.
- New POST /v1/hosts/{host}/builds/{build}/log (at most 200 entries a call; a build keeps its
last 1000) and POST /v1/hosts/{host}/builds/{build}/report, whose
eventisbuildingorprobing;failedwithstepandmessage; orbuiltwithtemplateRecordandmanifest, each file as a string. A report answers only a build this host claimed (else404 not_found); a failed or cancelled build takes no more. Onbuiltthe control plane stores both files, writes abuildrecord, checks them against the create's request and registers the build (itsbuildIdbecomes the manifest hash; a template's first registered build takesdefault) or rejects it withreason.rule, writing acheckrecord (at: registration) either way.
1.9.0​
A subject's own gate record, trusted for its own templates, and repositories allowed per registry (#738), per the subject trust spec. Trust is decided by who submits a gate record, never by anything inside it. Every change is additive.
ProfileaddsselfAttest,selfAttestEgressandrequireOfflineGate. The default policy addsbenchmark-self(thebenchmarkrules, no network) andgeneral-self(no X11;spec.egressmay be true, the KVM host's allowlisted egress);benchmarkstays curated (its records must be intrustedGateRecords).- On a
selfAttestprofile, a record not intrustedGateRecordspassesX1.trustedfor the creating subject's own templates. New create rules, each in thecheckrecord and named by a422 policy_refused:X1.self.scope(another subject already self-attested the same sha256; a build made while the record was trusted claims nothing, and a build that failed releases its claim),X12.self(the record must show commits refused, whatever the spec),X1.self.egress(spec.egressfalse unless the profile allows it) andX1.offline. X1.offline: on a profile that requires X1 (unlessrequireOfflineGate: false, as ongeneral-self), a general-gate record needsgate.floor_checked_offline: true(fail closed); a curated family record predates the field and passes. The general-gate schema is the settingSH_GATE_RECORD_SCHEMA(defaultmoca-gate-record/1; a malformed value refuses to boot), and GET /v1/policy answers it asgateRecordSchema, so a client's dry run applies the rule as the deployment does (an older control plane without the field reads as the default).- The
gateprovenance record'ssourceaddsself, withscope: the subject the record counts for, the template's owner (the submitter, except on an admin's build for another subject's template). TemplateandTemplateBuildaddattestation(deployment | self), recomputed on every read from the current policy:selffor a build made on aselfAttestprofile whose record is not trusted now, whatever its trust at create.TemplateBuildaddsgateFloorCheckedOffline, andgateFloorMetOfflinefor a gate from anetwork_neededcontract. A template with a registered self-attested build readsvisibility: private, whatever is stored.- New error code
self_attested(409): a self-attested create asking fordeploymentvisibility, or a self-attested build added to a deployment-visible template. PATCH /v1/templates/{id} answers the same refusal forvisibility: deploymenton a template with a self-attested build, registered or on its way there, and PUT /v1/templates/{id}/owner for a transfer of such a template to another subject. - PUT /v1/policy: a removal from
trustedGateRecordsthat makes builds of deployment-visible templates self-attested names them asnarrowed: [{template, buildId}]in its answer and in itspolicyrecord; those templates read as private from then on, and their owners keep using them. Policyadds the optionalallowedRepositories: per registry host (as the policy reads it, Docker Hub asdocker.io), the repositories a create may name there, each an exact path (library/python) or a prefix (library/*), matched on whole path segments; a Docker Hub official name reads aslibrary/<name>. New create ruleregistry.repository, which also refuses there an image path outside the entries' grammar (uppercase, or an empty,.or..segment). A registry with no list allows every repository, as before; a registry listed there must also be inallowedRegistries. Its keys compare case-insensitively, asallowedRegistriesdoes.
1.8.0​
Template tags, edits and owner transfer through the API
(#747), per the
template lifecycle spec §5.1-§5.2.
Every change is additive; the new routes mount on both route profiles and need SH_PROVENANCE_DIR (else
400 invalid_request). Each change writes a provenance record naming the new value and the one before.
- New POST /v1/templates/{id}/tags
{tags, build}(the owner, or an admin): moves 1-16 tags onto a registered build of the template, by build id or handle, without a rebuild. New sandboxes and sessions namingid:tag(and the bareid, fordefault) get the new build; those already created keep theirs. Atagrecord per tag that changes ({tag, buildId, before}); a tag already on the build answersrecord: null. - New DELETE /v1/templates/{id}/tags/{tag} (the owner, or an admin): removes a tag; its build is not deleted.
defaultis moved, never removed (400 invalid_request); a tag name outside the tag grammar is400 invalid_requesttoo. Atagrecord withbuildId: null. - New PATCH /v1/templates/{id}
{description?, visibility?}(the owner, or an admin): avisibilityrecord ({field, value, before}) per field that changes. A description holding a lone surrogate is400 invalid_request. - New PUT /v1/templates/{id}/owner
{owner}(an admin): the new owner,github:<numeric id>oroidc:<provider sub>(nevertest:<n>), must be enrolled. A template the deployment declared (owner: null) can be handed to a subject the same way (before: null), who can then build, tag and edit it; a restart does not undo it. Anownerrecord ({owner, before}). - Every template change (a tag moved or removed, an edit, an owner transfer, a cancelled build) is stored only once its
records are on the chain: a record that fails to append refuses the change. The owner's check is made again under the
template's lock, so a change by an owner the template was transferred away from meanwhile is refused (
403).
1.7.0​
Session grants: the key ring, the token format and the two lifecycle endpoints of
MI1 §6.1-§6.2, which discharge
#388 items 1-2 and the turn_exp half of
#387's M2.
- New POST /internal/turn-grants, behind the existing
exchangeTokenscheme: a worker presents the session token it was handed with the turn and gets the turn's two grants. The response is two signed grants, the turn's absoluteturnExp, theexpto refresh at, and the session's bundle digest. No credential and no secret is in it — the inference grant names the session's credential and the sandbox grant names itssandbox-egresscredentials, by name (§7.2). A grant is a capability spent at an enforcement point, not a secret. - New POST /internal/grants/refresh: a worker presents either half mid-turn and gets a fresh pair.
turn_expis carried forward unchanged, so no number of refreshes extends a turn, and a refresh past it is refused outright rather than clamped. A fresh issue does start a new window:turn_expis anchored to the call, and nothing yet identifies a turn to anchor to, so the bound on a caller holding a live session token is that token's lifetime. Anchoring issuance to the turn record is the redeemer's slice, whereturn_expfirst enforces anything. The session is re-read rather than echoed, so a credential or bundle changed mid-turn takes effect at the next refresh and a session tombstoned mid-turn stops refreshing (404session_not_found, the same answer another user's session gives). - New
TurnGrantsschema and the error codegrant_invalid(401): one code for every way a grant can fail — bad signature, wrongtyp, unknownkid, wrong audience, wrong issuer, expired, or pastturn_exp— because a caller's only move on any of them is to get a new grant. Themessagedoes name the failed check, for whoever is debugging a verifier; the route is behind the shared bearer. - Both routes are unmounted unless
MOCA_GRANT_SIGNING_KEYis set, and 404 before the body is read (ADR-0045's shape). A deployment that has not generated the grant ring behaves exactly as before. New configuration:MOCA_GRANT_SIGNING_KEY,MOCA_GRANT_PUBLIC_KEYS,MOCA_GRANT_TTL_S(300) andMOCA_TURN_MAX_S(1800), in configuration.md. - The grants are signed by a separate key ring from session tokens, with header
typ: moca-grant+jwt, so a session token can never pass as a grant even where anaudcheck is forgotten (§6.1). Note for any out-of-tree verifier:aud: moca-sandboxnow names two different tokens — the sandbox grant and the sandbox service's sandbox access token — and onlytypseparates them. The cross-language vectors are atpackages/control-plane/test/fixtures/grant-vectors.json(§12.2); they pin the verifier side and carry the public key only.
Interim, and named as such: nothing redeems a grant yet. The moca-egress inference listener and
§6.3's /internal/token are a later slice, so /internal/credentials and /internal/turn-credentials
both stay (§6.2's "replaces /internal/credentials" lands with the redeemer), workers never verify a
grant, and MOCA_TENANCY=multi still refuses async turns. There is no revocation list by design:
MOCA_GRANT_TTL_S is the revocation latency.
1.6.0​
Sandbox modes (lease-mode spec §8.1–§8.2), served
only on the sandbox route profile.
Sandboxgainsmode(per-exec,leaseorlease+processes),idleTimeoutS(0 = the worker's default) andmodeEpoch. A sandbox createdper-execstarts at epoch 0, one created in a lease mode at 1.- POST /v1/sandboxes accepts
mode(defaultper-exec) andidleTimeoutS(30 toSH_SANDBOX_IDLE_CEILING_S, whose default is 1800; omitted, the worker's default of 300 s; an explicit 0 is 400invalid_request). - New PUT /v1/sandboxes/{id}/mode: changes the mode and the idle timeout, raises
modeEpochby 1 on every accepted call, auditssandbox_mode_changed, and returns the sandbox with asetModeTokenfor the client'sLeaseControl set_mode. - New POST /v1/sandboxes/{id}/mode-token: a
setModeTokenfor the mode and epoch the record holds now, raising nothing. - Both mode routes are owner only (an admin gets 404 on another user's sandbox) and take only the
owner's user API token; a sandbox token is a 401. A set-mode token is a JWT with
typ: moca-sandbox-mode+jwt, valid 300 s. - New error code
mode_not_allowed(403): a lease mode the deployment'sSH_SANDBOX_MODES_ALLOWED(defaultper-exec, so no lease mode until an operator lists one) does not list.per-execis always allowed. - Sandbox tokens gain the claims
mode,mode_epochandidle_timeout_s. A token without them reads asper-exec, epoch 0. - Narrowing the policy downgrades existing sandboxes at their next token mint. A sandbox token or
mode-tokenminted for a sandbox whose lease modeSH_SANDBOX_MODES_ALLOWEDno longer lists first sets it toper-execat the next epoch, audited assandbox_mode_changedwith the reasonmode_not_allowed. A loweredSH_SANDBOX_IDLE_CEILING_Sclamps theidle_timeout_sclaim; the storedidleTimeoutSand the epoch are unchanged.
1.5.0​
Self-serve template create, gated by policy (#737),
per the template lifecycle spec
§4 and §8. Every change is additive; all new routes mount on both route profiles and need
SH_PROVENANCE_DIR (else 400 invalid_request).
- New POST /v1/templates
{id, image, spec, gateRecord?, profile?, visibility?}: any enrolled client creates a template from an image pinned by digest. The deployment's policy checks it before anything is queued; an admitted create answers202 {templateId, buildId: null, build, status: queued},buildbeing the build's path under ab-<26 hex>handle, and writescreate,gate(with a gate record) andcheckprovenance records. A create with the same image, spec, profile and gate record sha256 as a build of the caller's own template that is registered or on its way answers that build withreused: true(200when registered,202before); a failed or rejected build is never reused. - New POST /v1/templates/{id}/builds (the owner, or an admin: a new image or spec, the same body and
answers) and POST /v1/templates/{id}/builds/{build}/cancel (the owner, or an admin: a queued,
building or probing build becomes
failedwithreason.stepcancelled, and abuildrecord). - New GET /v1/policy (any enrolled client) and PUT /v1/policy (an admin; each change a
policyrecord naming who), with thePolicy(moca-template-policy/1: profiles with their rules and size envelope, allowed registries, trusted gate records by sha256, quotas) andPolicyViewschemas. The default policy has abaseand abenchmarkprofile. - New GET /v1/quota: the caller's limits and use (
templates, owned with a build registered or on its way there, a new build of one that holds no slot checked like a new id;buildsQueued, queued, building or probing;active;owned, template ids owned in any status, a failed or cancelled-only one included, 200 when the policy does not set it), and on the sandbox profile the live-sandbox cap (sandboxes).ownedcounts retired ids too, and a retired id is never served again, so it is in effect a lifetime cap per subject: a user who retires as they go reaches it in time, and only an admin raises it. - New error codes
policy_refused(422, withrule, the gating rule's id fromdeploy/sbx/template-onboarding/governance/GATING-RULES.md) andtemplate_exists(409: ids are unique per deployment, the first creator owns one).quota_exceededon a create names the quota (quota:templates,buildsQueuedorowned). TheErrorschema addsruleandquota. TemplateBuildaddshandle(the create's handle; equal tobuildIdfor an imported build) andreason(why a build failed or was rejected), and GET /v1/templates/{id}/builds/{build} also finds a build by its handle.- A refused create is recorded as a
checkprovenance record only on an existing template's stream the caller may write; a refusal on an id no template holds writes one audit line instead (template_create_refused, with the subject,templateIdand the failedrules).
Upgrade note (the policy fails closed):
- X12 applies under every profile,
baseincluded: askip_git_identity_check: truethat no gate record backs is refused (422 policy_refused, ruleX12). Abaseclient sends a gate record showing commits refused (X5:agent_can_commit: "no",git_identity: "none"), or drops the skip: the build host's git identity check then needs git with an identity in the image, or no git at all once the build-snapshot change in #757 is in. - A stored policy (
<SH_PROVENANCE_DIR>/policy.json) that names a rule id outside the ones the check acts on (X1, X10, X11, X12, X14, X15), or anenvelope.exactthat is not two positive whole numbers, is refused when it is read: every create and every read of the policy or the quota fails until an admin PUTs a valid policy, instead of the policy silently enforcing nothing. So readGET /v1/policyand fix it before upgrading: afterwards onlyPUT /v1/policysucceeds (the file itself stays readable on the volume).
1.4.0​
The template store and its read API (#736), per the template lifecycle spec §3-§4. Every change is additive.
- GET /v1/templates mounts on both route profiles (it was
sandboxonly), so a Moca Pi brain and a stock agent read the same templates. Its first fields (id,description,tools) are unchanged; each template addsowner(null for one the deployment declared),visibility,onboarding,readiness,tagsandbuilds, and the list adds ahostsblock, empty until a later issue's host agent reports. - New GET /v1/templates/{id}, GET /v1/templates/{id}/builds, GET /v1/templates/{id}/builds/{build}
(each build with its own
spec, seed included) and GET /v1/templates/{id}/tags (each tag's build, and when and by whom it was set), on both profiles. - New
TemplateandTemplateBuildschemas. A build'sreadinesscomes from the relay's presence records:activewith itscapacity,inactive, orunknownwhen presence cannot be read. An imported build's id isimported:<12 hex>; a built one's issha256:<manifest hash>. - POST /v1/sandboxes takes
templateasid,id:tagorid@<build id>, resolved to one registered build at creation and kept for the sandbox's life; an unknown one is still400 unknown_template. TheSandboxschema addsbuildIdandtemplateManifestHash(null for an imported build, which names no snapshot). - New error code
template_not_found(404): an unknown template or build, or aprivatetemplate the caller does not own. SH_PROVENANCE_DIRkeeps the templates in a store on a persistent volume, with the provenance records (#730):SH_SANDBOX_TEMPLATESis imported into an empty store once and ignored after that. Unset, templates come from the env list at every start, as before.
1.3.0​
Async turns: the owner-scoped submission API
(#387) and the dequeue-time credential exchange
(#388), per the
async fan-out spec and
ADR-0047. The M1 slice: a working drain under
MOCA_TENANCY=single.
- New POST /v1/sessions/{id}/turns (202 with the turn id), GET /v1/sessions/{id}/turns/{turnId} and
DELETE /v1/sessions/{id}/turns/{turnId} (queued turns only). Owner-scoped: another user's session
answers 404.
idempotencyKeydefaults to the session id, so a resubmission is deduplicated rather than queued behind. Documented in 1.2.0's document by oversight; recorded here. - New
TurnStatusschema andturnIdpath parameter. The nine turn states are pinned against the server's own list by a contract test. - New POST /internal/turn-credentials, behind the existing
exchangeTokenscheme: a worker presents the turn id it read off the queue and gets back the credential resolved from the turn record. No credential and no bearer token ever travels in the work queue (MI1 §6.5). A pure read — it does not move the turn torunning. TheturnIdmust be thet-<uuid>shape the control plane mints; anything else is 400invalid_request, refused before Redis is read. The response also carries theenvelopethe worker runs, with the turn'ssessionIdattached, so a claim is one round trip. - New GET /metrics, admin-only:
counters.async_quota_refusals, the count of submissions refused with 429async_quota_exhausted. The control plane reports it because it is the side that refuses them — a worker never sees a submission that was never enqueued (§7). Process-local and reset by a restart; with more than one replica each request reports one replica's share. - New error codes
turn_not_cancellable(409, cancelling a turn that is not queued),turn_not_claimable(409, claiming a cancelled or terminal turn),turn_not_found(404),async_quota_exhausted(429,MOCA_ASYNC_QUEUED_PER_OWNERnon-terminal turns already held),async_tenancy_unsupported(501, async underMOCA_TENANCY=multi; removed in 1.24.0, see that section) andworkload_runs_unavailable(501, a submission naming aworkloadId). Either 501 is answered before the quota is touched, so a request that can never be served is never reported as a 429 and leaves no record, no queue entry and no quota slot behind (§4.2). async: trueon the harness's own turn route stays removed and still answers 400async_removed; these routes are its replacement.
Upgrade note: LEAF_RESULT_TTL_SECONDS is now read by the harness tier through the control plane's
own strict parse, because both write the same result keys and a drained turn's result must outlive
nothing less than its record. A value that is not a positive integer refuses to BOOT there, where a
lenient parseInt used to read it as NaN and fail every result write instead. Surrounding
whitespace is trimmed, so an env file's trailing space or CRLF still boots; blank still means the
default (86400).
Interim, and named as such: /internal/turn-credentials returns a resolved credential rather than the
MI1 S2 grants, there is no turn_exp, and MOCA_TENANCY=multi refuses async at both the submission
and the claim. M2 mints grants for both audiences with a turn_exp and lifts that gate.
1.2.0​
The sandbox service's routes (sandbox-service spec §5.1),
served only by a control plane on the sandbox route profile (SH_ROUTE_PROFILE=sandbox); a moca
control plane answers 404 for all of them.
- New GET /v1/templates; POST and GET /v1/sandboxes; GET and DELETE /v1/sandboxes/{id}; and POST /v1/sandboxes/{id}/token, which mints a sandbox token for Exec (owner only, admins included).
- New GET /v1/janitor/sandboxes for the host janitor, behind the new
janitorTokensecurity scheme (SH_JANITOR_TOKEN). - New
Sandboxschema andsandboxIdpath parameter (sbx-plus 26 lowercase hex characters). - New error codes
not_enrolled(403),sandbox_not_found(404),sandbox_terminated(409, withreason),name_conflict(409),quota_exceeded(429) andunknown_template(400). - Every sandbox route, the janitor's included, keeps its records in Redis and can answer
503 redis_unavailable; POST /v1/sandboxes can answer400 invalid_json. - GET /v1/discovery names the route
profile, and onsandboxanswersexecEndpointandexecCa. - POST /v1/auth/device/token and POST /v1/auth/token can answer
403 not_enrolledon thesandboxprofile (a subject not in, or since removed from,SH_ALLOWED_SUBJECTS); a refused refresh also revokes that login.
1.1.0​
Per-session model selection (spec).
- New error codes
model_unavailable(400) andmodel_catalog_unavailable(503). - /internal/credentials returns the session's
modelwhen it names one. - POST /v1/sessions accepts
model; the session view shows it; new PATCH /v1/sessions/{id} switches it. - New GET /v1/models and GET /v1/sessions/{id}/models.