Skip to main content
Version: v0.11.0

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 alias POST /runs and the deprecated POST /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 a remote-worker process 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 with kubectl 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 /workspace between 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.