Glossary
Canonical definitions for the terms moca uses. session and turn are the two identity terms the
harness actually uses (see
#279 for the decision that produced
them); the rest name the parts of the runtime and its contracts. P6 and P4 are milestone IDs: P6 is
the process-manager runtime, P4 the microVM sandbox tier.
sessionโ
The durable, owned, resumable unit of work. session_id is the one identity the harness treats
as load-bearing: it is the Redis-backed idempotency key (MVP leaf-session contract
design ยง2.1), it survives process/pod
restarts (harness/src/run-leaf.ts), and it is the sole key in the multi-user ownership model
(multi-user control-plane design ยง7.2:
sh:cp:session:<sid>, sh:cp:owner:<subjectHash>:sessions).
turnโ
One exchange within a session โ POST /turn executes a single interactive turn and can stream
incrementally, as opposed to running a session to completion in one call. See the turn SSE
streaming design.
runโ
Not a harness concept. Historically the word was reused for three different things โ an
orchestrator-level batch id, a sandbox-lease field that duplicated session_id under a different
name, and the "run to completion" vs. "one turn" execution-mode distinction โ which is what #279
tracked down and eliminated. Batch grouping (e.g. "<run_id>/<item_id>" composed into a
session_id) remains a caller-side naming convention the orchestrator owns; the harness itself
treats session_id as opaque and holds no separate "run" identity.
run survives only:
- As an English verb ("run to completion" vs. "one turn").
- In the data-plane route names
POST /v1/runs, its supported, frozen aliasPOST /runsand the deprecatedPOST /run-leaf(packages/server/src/server.ts) โ kept as-is; a second rename cycle isn't worth the churn.
If a genuine grouping identity is ever needed inside the harness (e.g. parent/child lineage for a
leaf dispatching a child leaf), it should be named parentSessionId, not runId.
leafโ
One unit of agent work dispatched by an external orchestrator over POST /runs: parameterized, run
to completion in a tooled sandbox, returning a structured result. A leaf is addressed by a
session_id like any other session. The contract is re-entrant in the sense that a leaf can dispatch a
child leaf through /runs; re-invoking the same session_id re-runs and overwrites. See
the leaf-session contract. Contrast turn,
which is one interactive exchange on POST /turn. Under P6 a --role=leaf worker role is reserved for queued leaf work, but it is not
implemented yet (the worker exits 2 for any role but turn): async leaf dispatch runs instead in the
ordinary --role=turn workers' drain loop, opt-in behind SH_ASYNC_DRAIN=1 and single-tenant only
in v0.10.0.
archetypeโ
A dispatch pattern an orchestrator can use against the same backend. A is async fan-out (many
leaves queued at once and collected later), B is the human gate (a leaf pauses with status
paused and resumes on an external verdict), C is scheduled dispatch (a cron trigger posts async
leaves). B is served by the P6 runtime. A runs on P6 again, opt-in behind SH_ASYNC_DRAIN=1 and
single-tenant only in v0.10.0 (multi-tenant is targeted for v0.12.0), submitted to the control
plane's POST /v1/sessions/{id}/turns; the data plane's async: true stays removed. C was removed
with the Knative/KEDA path and has no P6 design yet
(#536). See dispatch archetypes.
brain and handsโ
The agent's reasoning and session logic (the brain: model calls, the conversation, tool selection) run in a worker process; every tool or command executes in a separate sandbox (the hands). The agent never executes tools in its own process.
supervisorโ
The P6 process manager. It accepts connections on an L4 listener and hands each accepted socket to a worker, and never touches a response byte (ADR-0034).
workerโ
A process forked by the supervisor that runs the model loop and serves many sessions, with a bounded
number of concurrent turns each (SH_TURNS_PER_WORKER). Workers and the supervisor are the same
image. The worker entry point lives in packages/server/src/worker.ts. Not to be confused with a sandbox worker (below).
sandboxโ
Two different things share the word, and neither sees the other.
- A harness session's sandbox: the isolated environment where a harness session's tools run.
Two tiers exist: a container, and (P4) a Firecracker microVM per
Exec. A sandbox runs aremote-workerprocess that dials out to the relay, so it needs no inbound route (ADR-0024, ADR-0035). On the removed Knative path a sandbox was the single pod reached withkubectl exec(sandbox-0). - A sandbox-service sandbox: a workspace on the sandbox service, made from
a template, where a coding agent's commands run in isolated VMs. You
drive it with
mocactl sbx; its files persist in/workspacebetween commands.
The mocactl sbx commands neither see nor manage a harness session's sandbox.
relayโ
The sandbox relay (packages/sandbox-relay) bridges a worker's Exec calls to the sandbox's
outbound Attach gRPC stream and mirrors connected sandboxes into the Redis pool. Sandboxes attach
to one port; the harness's workers call SandboxExec on a separate listener (loopback on a VM, the
brain network in Compose, a cluster service on Kubernetes).
tier and affinityโ
A tier is an operator-defined sandbox class (for example container and microvm), advertised
by a sandbox worker as the moca.dev/tier label and declared with SH_SANDBOX_TIERS and
SH_SANDBOX_DEFAULT_TIER. A session picks its tier once, at creation, and never changes it.
Affinity keeps a session on the same sandbox as its previous turn; if that sandbox is gone longer
than a grace period the turn moves within the tier and a workspace reset is recorded
(P6.3 design).
control planeโ
The multi-user service (MU1) that handles login, session ownership and credential issuance, and
exchanges a user's session token for the credentials a turn needs. mocactl is its terminal client
(ADR-0033).
It is one package, @moca/control-plane, with three route profiles (SH_ROUTE_PROFILE):
harness (the default: login, sessions, credentials, config bundles), sandbox (the
sandbox service: login, sandboxes and templates), and combined (both in one
process). So "the control plane" of a sandbox-service deployment is the same package on the
sandbox profile.
harnessโ
The moca harness is the capability that runs agent sessions: the supervisor hands each connection to a warm worker, sessions are durable in Redis, and the agent's tools run in a harness sandbox. Its sibling capability is the sandbox service.
Narrower uses of the word: the @moca/harness package (harness/) is the turn-execution library
the worker (@moca/server) and the sandbox relay import: runTurn, run-leaf, turn streaming,
the audit log, pool records and sandbox selection (the Pi session-log adapter,
BufferedRedisBackend, is one module in it); and names such as
~/.serverless-harness, /etc/serverless-harness and the SH_* variables keep the project's
historical prefix.
sandbox serviceโ
moca's other capability: a coding agent stays on the user's machine, and every command it runs
goes to a sandbox-service sandbox, each in a fresh VM, through mocactl sbx. It is
deployed as a control plane on the sandbox route profile, the relay, Redis and
KVM hosts running microvm-worker; see
Install the sandbox service.
template, build and tagโ
A template is what a sandbox-service sandbox is made from (mocactl sbx templates lists
them). A build is one immutable snapshot of a template; a new build of a template does not
change the sandboxes made from an earlier one. A tag names a registered build
(ID:TAG, or ID@BUILD for a build itself); default is the tag used when none is given, and it
cannot be removed; moving a tag leaves the sandboxes made earlier on their build. See
Templates, builds and activation.
activation leaseโ
On a deployment with template host agents, a build's worker runs only while someone holds an
activation lease on it: mocactl sbx templates activate takes or renews one, and when the last
lease is released (deactivate) the worker drains and stops, after the host's idle grace.
sandbox modeโ
How a sandbox-service sandbox runs its commands: per-exec (the default, a fresh VM per
command), lease (the guest is kept between commands) or lease+processes (tracked processes
outlive a command too). The deployment decides which modes users may pick; see
Keep a guest between commands.
subjectโ
The identity a login maps to, written github:<numeric GitHub user id> or oidc:<provider sub>.
SH_ADMIN_SUBJECTS and, on the sandbox and combined profiles, SH_ALLOWED_SUBJECTS take subjects; a user who
is not enrolled is told their own subject by mocactl sbx login. See
Users, enrollment and roles.
config bundleโ
A content-addressed tar built by @moca/config-bundle from a user's .claude skills and commands,
the CLAUDE.md chain and the memory index and files (under context/), that a session or leaf runs
with, referenced by digest (configRef: sha256:โฆ). Built and credential-scanned client-side;
see Promoting a local Claude Code workflow.
human gateโ
A pause point in a leaf: it stops (status paused on /runs) and resumes or terminates on an external approve, reject or abort verdict
(human-gate design). Archetype B. The early archetypes
requirements doc describes B as an iterative role-based loop; this glossary follows the README and
the human-gate design. There is no human-gate path on /turn.
handlerโ
The HTTP request handler in packages/server/src/server.ts that serves /turn, /runs and
the other routes. The P6 worker serves the same handler.