Configuration reference
Preview. Describes the P6 runtime as of
mainon 2026-10-12. Variable names keep their historical prefixes (SH_*,KAGENTI_*,MOCA_*); they are listed as they exist in the code. Each row is taken from the code that reads it. The deployment READMEs (deploy/vm,deploy/k8s,deploy/compose,deploy/microvm) say how each path sets these; the env templates are indeploy/vm/env/*.env.example.
Conventionsโ
- Secret means the value is a credential. On a VM,
SH_EXCHANGE_TOKEN,SH_SESSION_TOKEN_PRIVATE_KEYandSH_CREDENTIAL_KEKare systemd credentials (LoadCredential=), as isSH_OPERATOR_INFERENCE_TOKENwhen configured bysetup-vm.sh. Setting one of those in an env file as well makes its consumer refuse to boot.MOCA_RELAY_EXEC_TOKENandSH_RELAY_TOKENare plainEnvironmentFilelines (mode 0640), not credentials. Docker Compose passes all of them as plain env. - Blank values. A blank line (
X=) means "use the default" for most numeric knobs. Exceptions: blankSH_TURNS_PER_WORKERrefuses to boot, and a blankSH_MODELis kept as an empty string rather than defaulting. - Strict vs lenient parsing. The supervisor's own
config.ts(includingSH_ROUTING_POLICY) and the control plane's byte-budget and URL settings refuse a bad value. The control plane's numeric TTLs (intEnv) silently fall back to the default, and accept forms such as1.9,1e4and0x1F90with no upper bound. Several worker settings (SH_STATS_INTERVAL_MS, theKAGENTI_SANDBOX_*lease and affinity timings,KAGENTI_SYNC_SATURATION_*) also fall back silently, so a typo produces no error. The Go microVM worker refuses a malformedWORKER_MAX_CONCURRENT.MOCA_ASYNC_QUEUED_PER_OWNERandMOCA_TURN_SUMMARY_BYTESare the exceptions: they use a strict parser (countEnv), because0is a meaningful setting for both andintEnvwould read it as "unset". CREDENTIALS_DIRECTORY. When systemd (or the K8s manifests) sets it, the control plane reads all four of its secrets from that directory first and falls back to the same-named env var; both present is fatal.- Values that must agree across components are called out in the rows (relay and supervisor ports and tokens, tier names, affinity TTL).
Supervisor (parent process)โ
packages/supervisor/src/config.ts.
| Variable | Default | Required / notes | Meaning |
|---|---|---|---|
SH_TURNS_PER_WORKER | none | Required, at least 1; blank refuses to boot | S, the in-flight turn cap per worker |
SH_TURNS_PER_SUBJECT | half of S, min 1 | Integer at least 1; a malformed value falls back to the default; unset with no S means no quota (and no fairness defer on the async drain). Bounds the subject's SYNC turns and its ASYNC leaves against one count (#391): over it, /turn answers 429 subject_quota_exceeded and a claimed queue entry is handed back unrun. Per worker and in-process, so it paces an owner's MIXED load only -- a worker runs one queued leaf at a time, so an async-only backlog never reaches the cap and is drained FIFO. MOCA_ASYNC_RUNNING_PER_OWNER is the cluster-wide companion | Per-subject in-flight turn cap per worker (#360) |
PORT | 8080 | Integer 0-65535 | Data-path listen port |
SH_ADMIN_PORT | 8081 | Must differ from PORT unless 0 | Admin listener (/metrics, /healthz, /readyz) |
SH_ADMIN_HOST | 127.0.0.1 | IP literal only. The admin listener is unauthenticated; widen it only behind your own access control | Admin bind address |
SH_WORKERS | CPU count available to the unit | Integer at least 1 | W, the worker count |
SH_ROUTING_POLICY | leastInFlight | leastInFlight or stickyBySession; others refuse to boot | How accepted sockets are routed |
SH_WORKER_RESTART_BACKOFF_MS | 250 | Integer at least 0 | Backoff before restarting a dead worker |
Worker: auth, tenancy and Redisโ
The worker is packages/server/src/worker.ts. It validates
SH_SANDBOX_DISCOVERY, SH_REMOTE_SANDBOX and the tier settings at boot and exits on failure.
| Variable | Default | Required / notes | Meaning |
|---|---|---|---|
SH_REQUIRE_AUTH | off (only true enables) | Required true when MOCA_TENANCY=multi. A bad token is refused even when off | Every turn needs a control-plane session token |
SH_SESSION_TOKEN_PUBLIC_KEYS | empty | Malformed value fails the boot. VM: setup-vm.sh writes it once | The control plane's public keyset, <kid>:<base64 SPKI> |
SH_CONTROL_PLANE_URL | unset | No boot check. VM preset http://127.0.0.1:8090. Also required for SH_ASYNC_DRAIN: the async claim calls POST /internal/turn-credentials on it | Where the worker reaches the control plane for credential exchange |
SH_EXCHANGE_TOKEN | unset | Secret. Env plus credential file, or an empty file, fails the boot. Also the async claim's bearer when SH_ASYNC_DRAIN is on | The workers' bearer for the control plane's exchange hop |
MOCA_TENANCY | single | single or multi; a near-miss name throws. multi refuses SH_LOCAL_TOOLS=1, SH_MODEL_HEADERS and a Vertex ADC file (below). The control plane reads it too (ADR-0047): async turns get grants, not a key; both processes must agree | multi scrubs ambient provider credentials. No shipped template sets it |
SH_LOCAL_TOOLS | off | Refused under multi | Single-tenant dev opt-in: run tools in the worker |
REDIS_URL | redis://127.0.0.1:6379 | URL may carry a password | Sessions, leases, affinity, sandbox records, turn log, bundles |
CREDENTIALS_DIRECTORY | unset | systemd sets it; the K8s manifests set it by hand to /run/credentials | Where credential files are read first |
MOCA_VERSION | dev | Reported version, baked in at image build | |
SH_STATS_INTERVAL_MS | 1000 | Invalid or non-positive falls back. Also carries ยง7's async counters; the two queue gauges are refreshed on their own 10 s timer rather than per interval | Pace of advisory stats from workers |
Worker: sandbox selection, affinity and tiersโ
| Variable | Default | Required / notes | Meaning |
|---|---|---|---|
SH_REMOTE_SANDBOX | off (only 1 enables) | A pool selector without 1 fails the selection, naming both variables | Read the sandbox presence records mirrored from the relay |
SH_SANDBOX_DISCOVERY | unset (records) | Removed modes: pods and both throw, naming ADR-0041. Unset or records is the only behaviour | Kept only so a stale value fails loudly instead of quietly changing |
SH_RELAY_ADDR | sandbox-relay.default.svc.cluster.local:8443 | Must reach the relay's MOCA_RELAY_EXEC_ADDR listener (the same port, not necessarily the same literal address: Kubernetes and Compose bind one address and dial a service name), not its attach port | Address of the relay's SandboxExec listener |
MOCA_RELAY_EXEC_TOKEN | none | Secret. Required when the exec client is built. Must equal the relay's | The workers' credential for the relay's SandboxExec |
KAGENTI_SANDBOX_POOL_SELECTOR | unset | Templates set app=sandbox. Unset means no pool: turns run with local tools (or fail in server mode); a set selector without SH_REMOTE_SANDBOX=1 fails the selection | Gate for leasing from the sandbox pool (records are filtered by tier and workload, not by this literal) |
KAGENTI_SANDBOX_CWD | /workspace | Must equal the sandbox worker's SH_WORKSPACE_ROOT, or sessions do not get their own <root>/<sessionId> directory | Working directory in the sandbox |
KAGENTI_SANDBOX_CAP | 20 | Invalid or below 1 falls back. Templates set 4 | Soft cap on leases per sandbox |
KAGENTI_SANDBOX_LEASE_TTL_MS | 60000 | Floor 1000. Set by no template | Lease TTL |
KAGENTI_SANDBOX_HEARTBEAT_MS | 20000 | Clamped to at most TTL/3. Set by no template | Lease renewal interval |
SH_SANDBOX_TIERS | unset (untiered) | Comma-separated; duplicate or invalid names throw. Must match the control plane exactly | Declared sandbox tiers |
SH_SANDBOX_DEFAULT_TIER | the only tier, if one | Required when more than one tier is declared; must be a declared tier | Tier for sessions that do not choose |
SH_SANDBOX_AFFINITY_TTL_SECONDS | 86400 | Keep at least the P4 worker's SH_WORKSPACE_IDLE; must equal the relay's copy | How long a session remembers its sandbox |
SH_SANDBOX_AFFINITY_GRACE_SECONDS | 60 | 0 is legal | How long a turn waits (503) for its sandbox before moving within the tier |
Worker: turns, model and budgetโ
| Variable | Default | Required / notes | Meaning |
|---|---|---|---|
SH_TURN_DETACH | off (only 1 enables) | Templates enable it | Detachable, re-attachable turns |
SH_TURN_DETACHED_MAX_S | 1800 | Blank or invalid falls back | Unwatched turns end after this |
SH_TURN_LOG_TTL_S | 86400 | Blank or invalid falls back | A finished turn stays replayable this long |
SH_ASYNC_DRAIN | off (1, true or yes enables) | Needs SH_CONTROL_PLANE_URL and SH_EXCHANGE_TOKEN; ignored under MOCA_TENANCY=multi. A missing prerequisite logs one line and leaves the drain off -- it never fails the boot | Every worker also drains the async leaf queue (#389) |
MOCA_ASYNC_RUNNING_PER_OWNER | unset (no cluster-wide cap) | Integer at least 1; anything else (including 0) reads as unset, and derives nothing from S. Set the same value on every worker -- each enforces it independently against a Redis count, so differing values make the effective bound whichever worker claimed first. Only meaningful with SH_ASYNC_DRAIN. Over it, a claimed queue entry is handed back unrun (async_deferred_subject), as over SH_TURNS_PER_SUBJECT | Async leaves one owner may RUN deployment-wide (#391) |
SH_TURN_STREAM_TOOL_RESULT_PREVIEW_BYTES | 2048 | Byte cap on tool_result previews in the stream | |
SH_TURN_PATCH_MAX_BYTES | 4194304 (4 MiB) | Positive integer; at most the 8 MiB output cap less 4 KiB | Over it, a templated turn's workspace.patch is left out (patchRefused), never cut |
SH_TURN_STREAM_KEEPALIVE_MS | 20000 | 0 disables | Interval of the stream's : keepalive comment |
SH_TURN_STREAM_FIRST_FRAME_FLUSH_MS | 15000 | 0 disables | Flush SSE headers if no frame by then |
SH_MODEL_PROVIDER | anthropic (openai on the custom openai-completions path) | Model provider | |
SH_MODEL | claude-opus-4-8 | A blank value is kept as an empty string. /turn sessions always use it; only a leaf's envelope or leaf config can override it (a config bundle has no model field) | Model id |
SH_MODEL_CUSTOM | off (only 1 enables) | Requires a base URL (below) | Synthesize a model not in Pi's registry |
SH_MODEL_API | anthropic | anthropic, anthropic-messages or openai-completions. openai-responses throws "not yet implemented"; any other value throws "Unknown SH_MODEL_API" | API family of the custom model |
SH_MODEL_BASE_URL | none | A custom model throws without it, unless ANTHROPIC_BASE_URL (anthropic) or OPENAI_BASE_URL (openai) is set | Endpoint |
SH_MODEL_AUTH | bearer | openai-completions only (ignored with anthropic). custom-header and none strip the Authorization header | Auth style |
SH_MODEL_HEADERS | none | openai-completions only (ignored with anthropic). JSON object; ${VAR} in values is interpolated from env. May carry secrets, so MOCA_TENANCY=multi refuses it (below) | Extra request headers |
SH_MODEL_CONTEXT_WINDOW | 131072 | Custom model context window | |
SH_MODEL_MAX_TOKENS | 8192 | Custom model max tokens | |
SH_BUDGET_TOKENS, SH_BUDGET_MARGIN | none | Applied only when a positive number. A deployment CEILING: an async turn's own caps.tokens can narrow it but never raise it, so the tighter of the two applies (#391). Over the cap, further tool calls are refused; an async turn then ends failed: budget | Token budget and margin |
SH_PROMPT_CACHE | unset (caching on) | Opt-in, for example for benchmarking and performance analysis. off or on; any other value (OFF too) refuses to boot. Deployment-wide (below) | off strips Anthropic prompt-caching cache_control markers from the agent's model requests |
SH_GATEWAY_CACHE | unset (caching on) | Opt-in, as above; independent of SH_PROMPT_CACHE, same values. Only for a caching gateway that reads the field; a provider's own API may reject it | off adds cache: {"no-cache": true} to the agent's model requests, bypassing the response cache |
ANTHROPIC_API_KEY | none | Secret. Under multi tenancy it is forced to a sentinel and every ambient provider credential is scrubbed (see below) | Provider key |
ANTHROPIC_AUTH_TOKEN | none | Secret. Not used for an authenticated (control-plane) turn | Gateway bearer |
ANTHROPIC_BASE_URL | none | Gateway or endpoint | |
OPENAI_API_KEY, OPENAI_BASE_URL | none | Secret (key). OPENAI_API_KEY is seeded with unused for custom-header and none | OpenAI-compatible provider |
HARNESS_CWD | process cwd | Turn working directory | |
LEAF_RESULT_TTL_SECONDS | 604800 (7 days) | Positive integer or boot fails; blank (or whitespace) means the default, and surrounding whitespace is trimmed. Same strict parse the control plane uses, because both processes write the same result keys | TTL of leaf results (sync /runs and async drain) |
SH_RUN_HEARTBEAT_MS | 10000 | Blank or invalid falls back | How often a sync /runs run refreshes its in-flight heartbeat (#558) |
SH_RUN_STALE_MS | 60000 | Blank or invalid falls back; clamped to at least 2ร SH_RUN_HEARTBEAT_MS (a stale window shorter than the heartbeat would read every live run as dead) | A silent run holder reads as dead after this; the reaper then finalizes its run failed/owner_lost |
SH_RUN_REAP_INTERVAL_MS | 30000 | Non-positive falls back to the default | Sweep interval of the orphaned-run reaper every worker arms (#558) |
KAGENTI_SYNC_SATURATION_WAIT_MS, _BACKOFF_MS, _MAX_BACKOFF_MS | 30000, 250, 5000 | Parsed leniently | Sync /runs retry while the pool is saturated |
KAGENTI_SYNC_SATURATION_RETRY_AFTER_S | 5 | Retry-After seconds, also used for /turn |
Pi finds provider credentials by variable shape (*_API_KEY, *_AUTH_TOKEN, *_OAUTH_TOKEN,
HF_TOKEN, COPILOT_GITHUB_TOKEN, and the Bedrock AWS and Vertex ADC sources;
packages/server/src/server-process.ts). Under MOCA_TENANCY=multi, scrubAmbientCredentials
deletes all of them from the worker's environment, not only ANTHROPIC_API_KEY. Two ambient
sources survive an environment scrub, so multi refuses to boot with either: SH_MODEL_HEADERS
(an inline secret, or a ${VAR} naming a variable outside those shapes, would be sent on every
tenant's model requests), and a Vertex application-default credentials file at
$HOME/.config/gcloud/application_default_credentials.json, which pi falls back to once
GOOGLE_APPLICATION_CREDENTIALS is scrubbed.
For authenticated turns, inference credentials come from the control plane per user rather than from these variables.
SH_PROMPT_CACHE and SH_GATEWAY_CACHE (harness/src/prompt-cache-extension.ts) are opt-in
switches for runs that need model requests free of caching effects, for example benchmarking and
performance analysis: re-running the same prompts to compare two configurations, where cached
prefixes move tokens into the cache-read class and change timings, and a gateway's response cache
can return a stored reply without calling the model. Unset, requests are byte-for-byte what they
were. They are deployment-wide operator switches read from the worker's environment, not per
session or per tenant: under MOCA_TENANCY=multi they apply to every tenant's turns alike, and no
request can set or clear them. They cover the agent's model requests in a /turn turn (sync,
streamed or detached), a prompt leaf, and a solve or verdict leaf, in server mode too: they are
harness-internal extension factories, which the server-mode noExtensions lockdown does not
affect, not extension files a user could load or drop. They do not reach a compaction's summary
request, which pi sends outside the extension payload hook. A bad value fails the worker's boot,
and a turn built outside the worker (the CLI) fails instead of running cached. Turning prompt
caching off raises the billed input tokens of a long session.
Worker: Context Service workloads (optional)โ
Enabled only when MOCA_CONTEXT_WORKLOADS_ENABLED=1 and CONTEXT_SERVICE_URL is set; otherwise
/workloads returns 501. See docs/harness/how-to/workloads.md.
| Variable | Default | Notes |
|---|---|---|
MOCA_CONTEXT_WORKLOADS_ENABLED | off | Feature switch |
CONTEXT_SERVICE_URL | none | |
CONTEXT_SERVICE_PUBLIC_URL | none | Required for workloads; HTTPS except on loopback |
CONTEXT_SERVICE_TOKEN | none | Secret. Required for workloads |
CONTEXT_SERVICE_NAMESPACE (falls back to POD_NAMESPACE) | default | |
CONTEXT_SERVICE_TIMEOUT_MS | 5000 | |
MOCA_CONTEXT_MAX_STORAGE_GIB | 10 | |
MOCA_CONTEXT_MAX_WORKLOADS_PER_OWNER | 5 | |
MOCA_WORKLOAD_DELETED_TTL_SECONDS | 86400 | TTL of the deleted-workload record |
MOCA_CONTEXT_ROLLBACK_RETRY_ATTEMPTS | 3 | Create-rollback cleanup attempts (including the first) while Context Service is unreachable; 1 means no retry |
MOCA_CONTEXT_ROLLBACK_RETRY_BACKOFF_MS | 500 | Backoff between those attempts |
MOCA_CONTEXT_STORAGE_CLASSES | empty (any class rejected) |
These settings are checked per request, not at boot: a missing CONTEXT_SERVICE_TOKEN or URL returns
500 workloads_misconfigured.
Workloads with sandboxes of their own (phase 2, docs/harness/how-to/workloads.md,
"Own sandboxes"), off unless MOCA_PROVISIONER_URL is set:
| Variable | Default | Notes |
|---|---|---|
MOCA_PROVISIONER_URL | unset (off) | moca-provisioner's internal API. Set, POST /workloads accepts sandboxes |
MOCA_PROVISIONER_TOKEN | none | Secret. Required with the URL (500 workloads_misconfigured otherwise) |
MOCA_PROVISIONER_TIMEOUT_MS | 15000 | Per-request timeout |
MOCA_PROVISIONER_DELETE_WAIT_MS | 60000 | How long DELETE waits for the workload's pods to go before answering 202 |
MOCA_WORKLOAD_MAX_SANDBOXES | 2 | Largest sandboxes.count; the provisioner checks it again |
MOCA_WORKLOAD_MAX_STORAGE | 10Gi | Largest workspace.size with workspace.mount (<n>Mi or <n>Gi) |
MOCA_WORKLOAD_STORAGE_CLASSES | empty | <class>:rwo or <class>:rwx, comma-separated; empty: the default class |
moca-provisioner (packages/provisioner)โ
The only moca component with Kubernetes permissions in the sandbox namespace
(ADR-0043). Secrets are files under
CREDENTIALS_DIRECTORY, or env vars of the same name.
| Variable | Default | Notes |
|---|---|---|
MOCA_ATTACH_PRIVATE_KEY | none | Secret, required. Ed25519 key that signs attach tokens; its public half is the relay's MOCA_ATTACH_PUBLIC_KEYS |
MOCA_PROVISIONER_TOKEN | none | Secret, required. The workers' service token |
SH_SESSION_TOKEN_PUBLIC_KEYS | none | Required. Verifies the API token a worker forwards |
MOCA_SANDBOX_NAMESPACE | moca-sandbox | The one namespace it acts in |
MOCA_PROVISIONER_PORT | 8080 | |
MOCA_WORKLOAD_MAX_SANDBOXES | 2 | count per workload |
MOCA_OWNER_MAX_SANDBOXES | 4 | An owner's replicas across all workloads |
MOCA_ATTACH_TOKEN_TTL_S | 86400 | Attach-token lifetime; re-minted when less than half remains |
MOCA_PROVISIONER_RECONCILE_S | 300 | How often it checks tokens for re-minting and sweeps orphaned workloads |
MOCA_PROVISIONER_ORPHAN_GRACE_S | 600 | A workload's objects are swept only once all are older than this (record missing, deleted, deleting or of another generation) |
REDIS_URL | unset (no sweep) | Secret. The deployment's Redis; the orphan sweep only reads workload records with it. On Kubernetes it names the provisioner's own Redis user (moca-redis-provisioner), which may run GET on sh:wl:* and nothing else |
MOCA_PROVISIONER_REDIS_TIMEOUT_MS | 2000 | The bound on each record read; a read past it skips that workload for the pass |
MOCA_WORKLOAD_MAX_STORAGE | 10Gi | A mounted workload's largest PVC |
MOCA_WORKLOAD_STORAGE_CLASSES | empty | <class>:rwo or <class>:rwx; empty: the default class, ReadWriteOnce |
MOCA_PROVISIONER_SEED_PORT | 8081 | The seed port: GET /seed/v1/bundle with an attach token, nothing else |
MOCA_PROVISIONER_SEED_URL | http://moca-provisioner.moca.svc:8081/seed/v1/bundle | What workload pods' init containers fetch their bundle from |
MOCA_PROVISIONER_SEED_BUDGET_BYTES | 1073741824 (1 GiB) | Bundles held for seeding and hand-offs being read, all workloads together, at most half of it per owner; past it, 503 seed_budget_full. At least twice MOCA_CONTEXT_BUNDLE_MAX_BYTES; four times or more for a resend, which counts alongside the copy it replaces, to go through |
MOCA_PROVISIONER_SEED_HOLD_S | 600 | How long a bundle is held, seeded or not; then GET reports seed: bundle_missing until the next activate resends it |
MOCA_CONTEXT_BUNDLE_MAX_BYTES | 268435456 | Largest bundle a hand-off may carry. Must equal the workers': the component sets both; patch them together. Over it, activate answers 413 bundle_too_large |
MOCA_CONTEXT_BUNDLE_MAX_ENTRIES | 10000 | Most entries the seed extracts. Set to the workers' value, as the component does |
The pod template is the PodTemplate moca-workload-sandbox in the sandbox namespace
(deploy/k8s/base/workload-sandboxes/template.yaml: the shared pool's image, resources, relay address
and security settings, with no Secret); the provisioner adds the attach token as a file. It runs as
exactly one replica (replicas: 1, Recreate): the per-owner cap is serialized in the process, so a
second replica could let two concurrent requests both pass it.
Sandbox relayโ
packages/sandbox-relay/src/main.ts.
| Variable | Default | Required / notes | Meaning |
|---|---|---|---|
SH_RELAY_PORT | 8443 | Templates use 9443. Sandboxes dial it as RELAY_ADDR | Attach bind port (all interfaces) |
MOCA_RELAY_EXEC_ADDR | unset (exec shares the attach listener) | Templates set a separate listener. The supervisor's SH_RELAY_ADDR must dial this | Bind address for SandboxExec |
MOCA_RELAY_EXEC_TOKEN | none | Secret, required. The relay refuses to boot without it, or if it equals SH_RELAY_TOKEN or a per-sandbox env token | Exec caller credential; must equal the supervisor's |
SH_RELAY_TOKEN | none | Secret. Attach is fail-closed: with no token every attach is rejected. An empty value counts as missing | Shared sandbox attach token; must match each sandbox's SANDBOX_TOKEN |
SH_RELAY_TOKEN_<sandboxId> | falls back to SH_RELAY_TOKEN | Secret. Looked up verbatim by sandbox id, so an id with a dash cannot have an env token where the environment cannot carry a dashed name (systemd drops them, so not on the VM or a microVM host). It is never looked up in SH_RELAY_TOKEN_DIR and uses SH_RELAY_TOKEN there. setup-microvm.sh rejects dashed ids and writes these | Per-sandbox attach token |
SH_RELAY_TOKEN_DIR | unset | One file per sandbox id (ids must match ^[A-Za-z_][A-Za-z0-9_]*$; DIR is reserved), read on each attach. An unreadable or empty file refuses the attach; a file equal to the exec token is refused at attach time, not at boot. K8s mounts /run/relay-tokens | Token directory |
MOCA_ATTACH_PUBLIC_KEYS | unset (no workload labels: every Hello label is mirrored as sent, and an Exec's workload is ignored) | <kid>:<base64 Ed25519 SPKI>[,...], the format of SH_SESSION_TOKEN_PUBLIC_KEYS. A malformed entry refuses the boot. Set, a sandbox may attach with a moca-attach+jwt token instead of its relay token. The token needs iss=moca-provisioner, aud=moca-relay-attach, a known kid and an unexpired exp (30 s leeway); the id must be <wl>-<ordinal> (^<wl>-(0|[1-9][0-9]*)$) with the ordinal below the token's n. The relay closes the attach stream when the token's exp passes, and stamps moca.dev/workload, moca.dev/owner and moca.dev/tier from it; every other Hello loses its moca.dev/workload and moca.dev/owner labels and cannot take a w-<32 hex>-<n> id, and an Exec whose workload does not match its sandbox's is refused PERMISSION_DENIED (workload sandboxes spec ยง3) | Attach-token public keys (public halves only: the relay cannot mint) |
MOCA_RELAY_KEEPALIVE_TIME_MS | 20000 | Milliseconds: an integer from 1000 up to below 2147483647, else the relay refuses to boot (so 20, meant as seconds, is refused). Unset or empty is the default; keepalive cannot be turned off. Keep it below the shortest idle timeout between the relay and its peers (one load balancer was measured at 50 s), so a silent Exec's connection never looks idle. The passthrough Route forwards the TLS bytes untouched, and the ghostunnel sidecars are L4 TLS proxies that terminate TLS and forward the bytes without parsing HTTP/2; neither answers a PING, so the worker itself acks the relay's PINGs | How often the relay PINGs each connection, on both listeners |
MOCA_RELAY_KEEPALIVE_TIMEOUT_MS | 10000 | Same rules. A peer that has not acked a PING within this is dropped, so a sandbox whose network died without a TCP close is torn down (presence removed, its reconnect admitted) within time + timeout, about 30 s by default, not at the router's 5 m idle timeout. The workers' own 30 s client pings are never refused: grpc-js's server has no ping-rate policy | How long the relay waits for a PING ack |
SH_SANDBOX_AFFINITY_TTL_SECONDS | 86400 | Must match the supervisor's | TTL of the detach mark |
REDIS_URL | redis://127.0.0.1:6379 | Same Redis as the supervisor | Sandbox pool mirror |
Control planeโ
packages/control-plane/src/main.ts.
| Variable | Default | Required / notes | Meaning |
|---|---|---|---|
SH_SESSION_TOKEN_PRIVATE_KEY | none | Secret, required | Token signing key |
SH_CREDENTIAL_KEK | none | Secret, required; must decode as a valid key ring | Envelope-encryption key ring for stored credentials |
SH_EXCHANGE_TOKEN | none | Secret, required. Same value as the workers' | Bearer workers present for the exchange hop |
MOCA_GRANT_SIGNING_KEY | unset | Secret, optional. A SEPARATE Ed25519 key from SH_SESSION_TOKEN_PRIVATE_KEY, so a session token can never pass as a grant (MI1 ยง6.1). Unset unmounts POST /internal/turn-grants and POST /internal/grants/refresh, which then 404. REQUIRED under MOCA_TENANCY=multi, where the boot refuses without it and the dequeue exchange returns grants rather than a key; unset is the correct setting under single. The two rings must be DISJOINT and that is enforced: a key this ring shares with the session ring refuses to boot, because nothing detects it at runtime -- every token still verifies | Grant ring signing key |
MOCA_GRANT_PUBLIC_KEYS | empty | <kid>:<base64 SPKI>, comma-separated; the signer's own public half is always added. Only needed during a grant-key rotation. Verified on every request the inference listener is handed, so a rotation must list the retiring key here until the last grant signed by it has expired. Listing a key from SH_SESSION_TOKEN_PUBLIC_KEYS (or the session signer's own) refuses to boot | Extra grant verification keys |
MOCA_GRANT_TTL_S | 300 | Blank or invalid falls back. With no revocation list (MI1 ยง6.2 builds none on purpose), this IS the revocation latency and a stolen grant's replay window; the holder refreshes at half-life. It governs the INTERACTIVE /internal/turn-grants pair only: at dequeue an async turn's grant is minted for the whole turn (exp == turn_exp), because the worker has no refresh loop | How long one grant lives |
MOCA_TURN_MAX_S | 1800 | Blank or invalid falls back. An absolute cap: a refresh carries it forward unchanged and is refused once it passes, so no number of refreshes extends a turn. A turn's caps may ask for less and never more -- more is clamped at mint. A fresh ISSUE does start a new window, so on the interactive path this caps one turn's refresh chain rather than a session. For an ASYNC turn it is anchored at the dequeue and clamped to caps.wallClock when the submission named one -- and since #391 the worker ENFORCES that instant: it stops the leaf there and the turn ends failed: budget, instead of running on until its grants start failing | Deployment-wide ceiling on one turn |
MOCA_INFERENCE_ADDR | unset | host:port for the inference listener -- a SECOND HTTP server in the control-plane process, not a route. Required under MOCA_TENANCY=multi, where the boot refuses without it. Unset means one port and no redemption, which is correct for single. Bind it to loopback or to the sandbox network only: a caller holding a valid grant gets the session's credential spent on its behalf, so this port is a credential boundary -- the control plane warns at boot when the bind is not loopback | The inference listener's bind address |
MOCA_INFERENCE_URL | derived from MOCA_INFERENCE_ADDR | What a worker is told to point pi at, as reachable from the WORKER rather than from the control plane. Required when the listener binds a wildcard, since 0.0.0.0 is not an address a worker can dial. Must be an origin with no path -- the credential's own endpoint path is appended, and a path here would be counted twice | What the worker dials |
SH_GITHUB_CLIENT_ID | none | Required when SH_IDENTITY_PROVIDER=github (the default). A GitHub OAuth app with device flow enabled; no client secret | Login |
SH_IDENTITY_PROVIDER | github | github or oidc; anything else refuses to boot, and a near-miss spelling of the name throws (SH_IDENTITY_PROVDER, MOCA_IDENTITY_PROVIDER) | Which identity provider logins use |
SH_OIDC_ISSUER | none | Required when oidc. The provider's issuer URL (e.g. https://<issuer>); discovery is read from /.well-known/openid-configuration | Login |
SH_OIDC_CLIENT_ID | none | Required when oidc. The client id registered with the provider | Login |
SH_OIDC_REDIRECT_URI | none | Required when oidc. The control plane's public GET /v1/auth/oidc/callback URL, exactly as registered with the provider (e.g. its OpenShift Route) | Login |
SH_OIDC_CLIENT_SECRET | none | Secret, required when oidc. Resolved through withCredentials (systemd credential or K8s secret), never committed | Login |
SH_OIDC_SCOPE | openid email profile | Only when oidc | Login |
SH_OIDC_MAX_PENDING_PER_SOURCE | 20 | Only when oidc. Live login starts one client address may hold, beside the 10,000 the control plane holds in total; past it that address gets the total cap's 429 quota_exceeded, while other addresses still start. An abandoned start holds its slot for the state TTL (15 minutes). 0 turns the bound off, for a deployment whose clients all arrive from one address (an SSH tunnel); a malformed value refuses to boot. Which address a request comes from follows SH_TRUSTED_PROXY_HOPS | Login |
SH_TRUSTED_PROXY_HOPS | 0 | How many reverse proxies in front of the control plane append the address they saw to X-Forwarded-For; the entry that many from the right is the client's (so too high a count lets a client pick its address), and a header with fewer entries than that is ignored for the socket peer. 0 ignores the header. deploy/k8s/setup.sh writes 1 (deploy/sbx/setup.sh too, with OIDC), and its Routes pin set-forwarded-headers: append, which the trust relies on (oidc guide). Malformed refuses to boot. Read only for per-source bounds, never for authorization | Login |
SH_PUBLIC_HARNESS_URL | unset | Code does not require it (discovery returns harnessUrl: null), but the VM installer does. Absolute http(s) URL | Harness URL advertised to clients (GET /v1/discovery) |
SH_CONTROL_PLANE_PORT | 8080 | VM template uses 8090 (8080 is the supervisor's). Invalid silently falls back | Listen port |
SH_CONTROL_PLANE_HOST | all interfaces | VM template sets 127.0.0.1: plain HTTP, reach it through a tunnel | Bind address |
REDIS_URL | redis://127.0.0.1:6379 | Retries forever | Ownership index, refresh tokens, bundles |
SH_CREDENTIAL_STORE | kubernetes | kubernetes, file or vault. VM and Compose use file | Credential store backend |
SH_CREDENTIAL_DIR | none | Required for file | File store path |
SH_CREDENTIAL_NAMESPACE | sh-credentials | Kubernetes store; the K8s manifests use moca-credentials | Secret namespace |
VAULT_ADDR, VAULT_TOKEN or VAULT_TOKEN_FILE (exactly one), VAULT_NAMESPACE, SH_VAULT_KV_MOUNT (secret), SH_VAULT_PATH (moca/credentials) | none | Vault store only; no template wires it. Token is a secret | Vault credential store |
SH_ADMIN_SUBJECTS | none | Comma-separated github:<id> or oidc:<sub> | Admin role |
SH_ALLOWED_SUBJECTS | none | Required on sandbox and combined (boot fails without it); not read on harness. Comma-separated subjects, each matching the subject grammar (github:<id>, oidc:<sub>, test:<n>) or boot fails. The enrollment bootstrap: never edited by /v1/subjects. See Users, enrollment and roles | Enrolled subjects |
SH_INSTALLER_TOKEN | unset (refuses every use) | Secret, optional; sandbox and combined profiles; at least 32 characters or boot fails. A static bearer accepted on the /v1/subjects* routes only, acting as the synthetic subject installer with a settings admin's power over enrollment and roles. deploy/sbx/setup.sh generates it into moca-mu1; on combined it becomes live at the upgrade that reads it there (Upgrade notes) | Members-API automation |
SH_TEST_USERS | 0 (off) | Dev/test only. 1-1000; needs SH_TEST_USER_SECRET; refused on the sandbox profile; on --target ocp needs SH_TEST_USERS_ACK | Synthetic test:N logins (ADR-0045) |
SH_TEST_USER_SECRET | none | Secret, required with SH_TEST_USERS; min 16 chars. A credential FILE under CREDENTIALS_DIRECTORY (k8s: its own moca-test-users Secret, deleted when off), never an env line; setup.sh generates it | Shared secret a test-user login must present |
SH_DEFAULT_INFERENCE_ENDPOINT | none | Validated if set. For Anthropic use https://api.anthropic.com (no /v1) | Gateway origin for credentials with no endpoint |
SH_ALLOW_OPERATOR_FALLBACK | off (only true enables) | true requires the token and endpoint, mutually consistent, or boot fails | Users without their own credential spend the operator's |
SH_OPERATOR_INFERENCE_TOKEN | none | Secret. On a VM, a credential file via a drop-in setup-vm.sh creates; never an env line | The operator's inference key |
SH_OPERATOR_INFERENCE_HEADER | authorization | authorization or x-api-key; an Anthropic API key needs x-api-key | Header the operator key travels in |
SH_API_TOKEN_TTL_SECONDS / SH_SESSION_TOKEN_TTL_SECONDS | 900 / 300 | Invalid silently falls back | Token lifetimes |
SH_REFRESH_IDLE_TTL_SECONDS / SH_REFRESH_MAX_TTL_SECONDS | 2592000 / 7776000 | Idle must not exceed max | Refresh token lifetimes |
SH_REFRESH_REUSE_GRACE_SECONDS | 30 | Invalid or 0 silently becomes 30, so the grace cannot be disabled; above 300 throws | Grace for a retried refresh |
SH_SANDBOX_TIERS / SH_SANDBOX_DEFAULT_TIER | as for the worker | Must match the supervisor's exactly | Tiers a session may choose |
SH_ROUTE_PROFILE | harness | Exactly harness, sandbox or combined, else boot fails. combined serves sessions and sandboxes in one process: it requires both profiles' settings, naming a missing one; login is open, and the sandbox routes and template writes need an enrolled subject | The route set this control plane serves |
SH_SANDBOX_TOKEN_TTL_SECONDS | 900 | sandbox and combined. A positive integer, at most 3600, or boot fails. Bounds the longest command and how late a delete or unenrollment takes effect (plus the relay's 30 s leeway) | Sandbox token lifetime |
SH_SANDBOX_MAX_PER_SUBJECT | 3 | sandbox and combined. A positive integer or boot fails | Live sandboxes per subject |
SH_SANDBOX_LIFETIME_SECONDS | 604800 (7 days) | sandbox and combined. A positive integer, at least 3600, and at most SH_SANDBOX_MAX_LIFETIME_SECONDS, or boot fails | Default sandbox lifetime |
SH_SANDBOX_MAX_LIFETIME_SECONDS | SH_SANDBOX_LIFETIME_SECONDS | sandbox and combined. At least 3600. Setting it turns idle lifetimes on: an owner's activity slides the deadline. Unset, the deadline is fixed at create | Longest lifetime an owner may pick |
SH_SANDBOX_MODES_ALLOWED | per-exec | sandbox and combined. A comma list of per-exec, lease, lease+processes; unset or empty means per-exec, while a list of no names (such as ,) or an unknown name fails boot | Sandbox modes an owner may pick |
SH_SANDBOX_IDLE_CEILING_S | 1800 | sandbox and combined. A positive integer, at least 30, or boot fails | Longest lease idle timeout |
SH_SANDBOX_TEMPLATES | unset (no templates) | Either profile. JSON [{id, worker, description, tools, seed?}]; malformed throws. With SH_PROVENANCE_DIR set, imported into the template store once (owner null) and ignored after that, and a session's template resolves through the store (id, id:tag, id@<build id>) | Sandbox and session templates; a seed per workspace |
SH_PROVENANCE_DIR | unset | Absolute path on a persistent volume; either profile; one control-plane process per directory. Opens the provenance, template, policy and members stores together. The members store (members.json) enables /v1/subjects, and each request's roles and enrollment then come from the settings and that store, harness profile included. Unset: templates come from SH_SANDBOX_TEMPLATES at every start, nothing is recorded, and a token's roles stand | Template store and provenance records |
SH_GATE_RECORD_SCHEMA | moca-gate-record/1 | Sandbox profile. A schema string (path segments of letters, digits, ., _, -); malformed refuses to boot. A record of it needs gate.floor_checked_offline: true for X1.offline (fail closed); GET /v1/policy answers it as gateRecordSchema | The general-gate record schema |
SH_TEMPLATE_HOSTS / SH_HOST_TOKEN_<ID> | unset (no host routes) | Either profile. SH_TEMPLATE_HOSTS a JSON list of {id} (^[a-z0-9][a-z0-9-]{0,30}$); each host's SH_HOST_TOKEN_<ID> (the id upper-cased, - to _) 64 hex, secret, from the environment or a systemd credential, distinct from the exchange, janitor and every egress token; malformed throws. Unset: every host route answers 401 | The template host agents and their bearers |
SH_BUNDLE_SUBJECT_BYTES / SH_BUNDLE_TOTAL_BYTES | 16 MiB / 64 MiB | Positive integer strings or boot fails | Config-bundle byte budgets |
SH_SESSION_TOKEN_PUBLIC_KEYS | empty | Malformed throws | Extra public keys for rotation |
SH_INJECTOR_CONFIGURED | off | No template sets it | Skips the direct-mode mismatch check |
SH_SANDBOX_NAMESPACE | default | Used on Kubernetes paths | Sandbox namespace |
SH_MODEL_CATALOG_HOSTS | empty | Comma-separated bare hostnames, case-insensitive; a URL, port or path refuses to boot | Extra hosts the model catalog may contact |
MOCA_ASYNC_QUEUED_PER_OWNER | 50 | Non-negative integer or boot fails. 0 refuses every async submission (429). Distinct from the worker's SH_TURNS_PER_SUBJECT: that counts turns executing, this counts turns waiting | Non-terminal async turns one owner may hold (ADR-0047) |
MOCA_TENANCY | single | single or multi; a near-miss spelling of the name throws, here as in the worker. Must match the worker's | Tenancy mode |
LEAF_RESULT_TTL_SECONDS | 604800 (7 days) | The same variable the worker reads, through the same strict parse (resultTtlSeconds): positive integer or boot fails, in both processes, because both write the same result keys. The turn record's TTL is this plus a 1 h margin, so a finished turn's record outlives its result, and the per-session turn index gets the same clock. The ONE retention knob for async turns: a Friday turn is still readable on Monday, and raising it moves record, result and index together | Async turn record retention (ADR-0047) |
MOCA_TURN_SUMMARY_BYTES | 2048 | Non-negative integer or boot fails. Byte cap on the CONTENT of each model-written string an async status read carries: the summary, verdict.reason, and the gate's summary and proposed_action. A clipped string is this many bytes plus the 14-byte โฆ[truncated] marker. 0 omits all four keys -- no model prose in the body at all. Bytes, not tokens, like every other bound here, and it mirrors the worker's SH_TURN_STREAM_TOOL_RESULT_PREVIEW_BYTES -- a polled route must not return whatever a model happened to write | Async status-read summary cap (#390) |
Outbound calls. Besides the credential store and Redis, the control plane calls inference credential endpoints
when models are listed or chosen (GET /v1/models, GET /v1/sessions/{id}/models, POST /v1/sessions with a
model, PATCH /v1/sessions/{id}), with the endpoint's own scheme: <endpoint>/v1/models when the endpoint's host is
api.anthropic.com, <endpoint>/model/info for any other host. The endpoint's query and fragment are dropped.
The endpoint is the user's to choose, so these calls go only to an allow-listed host: api.anthropic.com, the host of
SH_DEFAULT_INFERENCE_ENDPOINT, and the hosts in SH_MODEL_CATALOG_HOSTS. Without the allow-list, any user with a
credential could make the control plane probe its own network (Redis, the identity provider, the Kubernetes API).
Private addresses are not refused as such, because an in-cluster gateway is usually on one. Add each gateway host your
users' credentials name, other than the default endpoint's, to SH_MODEL_CATALOG_HOSTS (for example
litellm.team-a.svc,gw.example.com). A host outside the allow-list is not contacted: listing returns
model_catalog_unavailable and a chosen model is accepted unverified, exactly as when the endpoint is down, and the
control plane logs the host with not in the catalog allow-list (SH_MODEL_CATALOG_HOSTS).
Egress policies must allow these calls. Every failure gives the caller the same message, the inference endpoint could not list its models; the log names the host and the reason (its status, no answer, not JSON, too large), never the
path, the query or the secret.
Sandbox workers (Go)โ
Container sandbox (remote-worker/cmd/worker)โ
| Variable | Default | Notes |
|---|---|---|
RELAY_ADDR | localhost:8443 | The relay's attach address |
SANDBOX_TOKEN | dev-token | Secret. Equals the relay's SH_RELAY_TOKEN (or its per-sandbox token). Do not leave the default |
SANDBOX_TOKEN_FILE | unset | A file holding the token; when set it replaces SANDBOX_TOKEN, and is re-read on every dial and reconnect, so a rotated mounted Secret (a workload's attach token) is picked up. When the file changes, the worker reconnects with it at its next idle moment (no command running). Unreadable or empty at boot is fatal |
RELAY_TLS, RELAY_CA_FILE | off | TLS to the relay; a garbage RELAY_TLS is fatal |
SANDBOX_ID | sbx-laptop-1 | Unique per sandbox |
SANDBOX_TIER | container | Advertised as the moca.dev/tier label. If set but blank, no label: a tiered harness excludes the worker |
SANDBOX_TEMPLATE | unset | Advertised as the moca.dev/template label; unset or blank, none: only sessions naming the template land here |
WORKER_MAX_CONCURRENT | 4 | Concurrency slots; garbage or non-positive falls back |
SANDBOX_IMAGE, SANDBOX_TRUST | empty, untrusted | Labels |
SH_WORKSPACE_ROOT | built-in default | Absolute path |
SH_WORKSPACE_IDLE | 30m | Go duration; idle time after which a session workspace is deleted (#338); malformed or non-positive is fatal. deploy/k8s/setup.sh writes 8h (sticky, via ConfigMap moca-sandbox-settings); disk is not admission-controlled, so the idle sweep bounds /workspace |
SH_WORKSPACE_EMPTY_IDLE | 15m | Go duration; idle time after which an empty session workspace that no process is in is deleted (#551). Must not exceed SH_WORKSPACE_IDLE; a larger or unparseable value is fatal |
SH_EXEC_TIMING=1 (off unless exactly 1) writes one exec-timing line per Exec to the worker's log:
req, workspace_key, start_ms, dur_ms (receipt to end), the command process's CPU (user_ms, sys_ms),
exit and err. It is cheap enough to leave on for a measured run, unlike SH_DIAG_PHASES (#576).
Commands run in a sandbox do not inherit the worker's own settings. The exact names SANDBOX_TOKEN,
RELAY_ADDR, RELAY_TLS, RELAY_CA_FILE, SANDBOX_ID, SANDBOX_IMAGE, SANDBOX_TRUST and
WORKER_MAX_CONCURRENT, and anything prefixed SANDBOX_TOKEN_, SH_ or MOCA_, are stripped. Other
names (for example SANDBOX_TIER) do reach commands.
MicroVM worker (remote-worker/cmd/microvm-worker)โ
It reads the same RELAY_* and SANDBOX_* variables (defaults SANDBOX_ID=sbx-microvm-1,
SANDBOX_TIER=microvm), plus:
| Variable | Default | Notes |
|---|---|---|
SH_SNAPSHOT_DIR | none | Required |
WORKER_MAX_CONCURRENT | 16 | Positive integer; a malformed or non-positive value is fatal, not a fallback. Not the container worker's 4 |
SH_WORKSPACE_ROOT | none | Required |
SH_MAX_COMMITTED_MB | none | Required, positive integer: the worker refuses to start without it. Size it against the slot count |
SH_VMM | firecracker | fake and unknown values are refused |
SH_ALLOW_INSTANCE_TYPE_MISMATCH | off | Opts a host out of the snapshot instance-type check, for deliberate cross-host use |
SH_VERIFY_MEMFILE | off | Exactly 1: also re-hash the snapshot's memory file at start (a version-2 manifest records its digest). A full read of the guest's RAM image, so off by default; the kernel, rootfs, agent and vmstate are checked at every start |
SH_VERIFY_CACHE | on | 0: no verify cache, every snapshot file hashed in full at every start (the old behaviour); 1 or unset: on; anything else is fatal. A file whose identity (device, inode, size, mtime; not ctime, which every VM restore's jail links move) is unchanged since a full hash on this host matched the manifest is not hashed again; the manifest comparison is made either way. A missing, corrupt or not-0600 cache only means a full check. microvm-worker -verify-snapshot DIR (run by build-snapshot.sh after it publishes) seeds it |
SH_VERIFY_CACHE_PATH | per snapshot | Absolute path of the verify cache file. Default: <SH_VERIFY_CACHE_DIR>/<image>-<hash of the snapshot directory>.json, which the build-time seed computes the same way; set it only if the worker and the seed are given the same value |
SH_VERIFY_CACHE_DIR | /var/lib/moca-microvm-worker/verify-cache | The directory of the default per-snapshot cache file (absolute; the file name is computed as for the default). The sandbox service sets it under its own /srv/sbx (install-host.sh for each worker, template-build.sh for the seed), so its state stays inside that tree; SH_VERIFY_CACHE_PATH wins when both are set |
SH_TEMPLATE_RECORD | unset | Path to the template record this worker serves (template-build.sh's $SBX_SRV/templates/<snapshot>.json), set by install-host.sh when that file exists (with SANDBOX_TEMPLATE, the record's id), checked at start against the snapshot's manifest and the worker's identity: a mismatch, or a manifest older than hash version 2 or without source_image_digest, is fatal. Unset: no check |
SH_STANDBY_DEPTH | built-in | Warm standby VMs |
SH_STANDBY_HEADROOM | 4 | full (pre-#644 full-RAM charge) or a number โฅ 1: multiplier on a paused standby's measured dirty-page footprint (its per-VM cgroup memory.current) for the admission budget. Running VMs are always charged full price; a standby over budget is evicted, not refused |
SH_GUEST_RAM_MB | built-in | Per-guest RAM |
SH_MAX_RUNS | 64 | Positive integer |
SH_MEMORY_RESERVE_MB | none | Positive integer if set |
SH_HOST_MEM_FLOOR_MB | off | Positive integer if set: refuse admission when host MemAvailable drops below it (counted as host-memory, distinct from memory-budget) โ the host backstop beside dirty-page accounting (#644) |
SH_WORKSPACE_IDLE | built-in | Go duration; setup-microvm.sh sets it from MICROVM_WORKSPACE_IDLE (default 8h) |
SH_PARENT_CGROUP | built-in | Slice-relative; under systemd a nonexistent path is fatal |
SH_JAILER_BIN, SH_FIRECRACKER_BIN, SH_CHROOT_BASE | PATH, /srv/jail | Binary and jail locations |
SH_WORKSPACE_IMAGE_MB | 2048 | Positive integer |
SH_SNAPSHOT_IMAGE | default |
SH_EXEC_TIMING=1 (off unless exactly 1) writes the container worker's exec-timing line per Exec, with the
same fields, plus the phases ExecPhased computes (acquire_us, resume_us, mount_us, run_us, destroy_us,
cold) and the VM's CPU from its pooled cgroup's cpu.stat, read after the acquire and before the destroy.
user_ms=-1 sys_ms=-1 means not measured, never no CPU. Scheduling, admission and teardown are unchanged (#576).
SH_VIRTIOFSD_UID and SH_VIRTIOFSD_GID (default 65534) are read only in the Cloud Hypervisor arm, so
they do nothing with the default SH_VMM=firecracker.
Diagnostic switches (SH_DIAG_PPROF, SH_DIAG_STATS_ADDR, SH_DIAG_PHASES) and the Cloud
Hypervisor variables (SH_CHV_*, SH_CH_REMOTE_BIN, SH_VIRTIOFSD_BIN) exist but are not part of
the supported setup.
mocactlโ
| Variable | Default | Notes |
|---|---|---|
SH_CONTROL_PLANE_URL | saved config | Precedence: flag, env, config, the login's own URL |
SH_HARNESS_URL | saved config, else discovery | Overrides the harness URL that discovery returns |
XDG_CONFIG_HOME | ~/.config | mocactl/config.json and the login file (holds tokens) |
XDG_STATE_HOME | ~/.local/state | Transcripts and exports |
VISUAL / EDITOR | vi | External editor |
NO_COLOR | off | Disables colour when non-empty |
MOCACTL_VERSION, MOCACTL_INSTALL_DIR and MOCACTL_BASE_URL (the releases URL, https only) are read
by the installer (scripts/install-mocactl.sh), not by mocactl itself.
Installer-time variablesโ
Read by the install scripts (setup-vm.sh, setup-microvm.sh, deploy/compose/install.sh,
deploy/k8s/setup.sh) rather than by the runtime. SH_GITHUB_CLIENT_ID and SH_PUBLIC_HARNESS_URL
are also read by the control plane, and SANDBOX_IMAGE by both Go workers (rows above). Each script's
header is authoritative.
- Paths and image:
SH_UNIT_DIR,SH_ENV_DIR,SH_INSTALL_DIR,SH_CRED_DIR,SH_REPO_ROOT,SH_SANDBOX_COUNT,SH_SANDBOX_RELAY_ADDR,SH_BIN_DIR. - VM sandbox network:
MOCA_SANDBOX_SUBNET,MOCA_SANDBOX_GATEWAY,MOCA_SANDBOX_BRIDGE. - MicroVM installer:
MICROVM_SANDBOX_ID,MICROVM_WORKSPACE_IDLE,MICROVM_SNAPSHOT_DIR,MICROVM_BIN,MICROVM_ATTACH_TIMEOUT,MICROVM_ATTACH_SETTLE,MICROVM_MAX_COMMITTED_MB. SH_SKIP_PULL(non-empty) โ run the images this machine already has instead of pulling them. Read bydeploy/compose/install.sh,setup-vm.shanddeploy/microvm/build-rootfs.sh. The pull is otherwise fail-closed in all three, because neitherdocker compose up -dnorpodman runre-resolves a reference the host already holds a copy of โ so a:latestpulled once is what every later run starts (#349, #414).- Compose
install.shinputs:SH_COMPOSE_DIR,SH_COMPOSE_BASE_URL,SH_HARNESS_IMAGE. - Compose file interpolation (
docker-compose.yml):SH_SANDBOX_IMAGE,SH_PORT,SH_CP_PORT,MOCA_RELAY_EXEC_PORT,MOCA_RELAY_BRAIN_IP,MOCA_BRAIN_SUBNET,COMPOSE_PROFILES. - Kubernetes
setup.sh:SH_P4_SANDBOX_IDS,SH_SANDBOX_EGRESS_EXCEPT,SH_ROUTE_DOMAIN,SH_SINGLE_NAMESPACE,SH_WAIT_SECONDS,SH_PUBLIC_HARNESS_URL(port-forward-reached targets only: overrides the defaulthttp://127.0.0.1:8080),SH_WORKSPACE_IDLE(the container sandboxes' idle reclaim, default8h; a change rolls the sandbox pods). - Sandbox service KVM host (
deploy/sbx/install-host.sh,deploy/sbx/host-agent.sh):SBX_WORKER_BIN(default/usr/local/libexec/sbx/microvm-worker: the worker binary the sandbox service's units run, never/usr/local/bin/microvm-worker),SBX_SAMPLER_INTERVAL_S(the host sampler's interval in seconds, 5-3600, default 15;0installs none and removes an installed one); the host agent'sSBX_API_URL,SBX_HOST_ID,SBX_HOST_TOKEN_FILE,SBX_KERNEL,SBX_API_CA_FILE,SBX_DISK_FLOOR_GB(default 60),SBX_BUILD_CONCURRENCY(default 1, at most 4),SBX_ACTIVE_LIMIT(the workers the control plane places on the host at once; default 0, none),SBX_IDLE_LIMIT_S(the default activation lease, in seconds, clamped to 60-86400; default 0, then 3600),SBX_MEM_FLOOR_MIB(the memory the control plane never places workers into, MiB; default 10% of MemTotal, at least 4096),SBX_MEM_PRESSURE_LIMIT(no new worker start while memory PSIfull avg10is above it; default 10),SBX_START_CONCURRENCY(the workers starting at once, started and not attached yet; default 4, at least 1),SBX_START_WINDOW_S(how long a start counts as starting at most, in seconds: with a control plane that sends nostarting, the agent's own starts; with one, a listed worker not attached after it is stuck and holds no slot; default 300),SBX_IDLE_GRACE_S(how long a released build's running worker is kept, in seconds; default 0, off; at most 86400),SBX_REGISTRY(the runbook, the template host agent).deploy/sbx/setup.sh'sSBX_TEMPLATE_HOSTSlists the hosts and writes each one's bundle.
Known inconsistenciesโ
SH_PUBLIC_HARNESS_URLis documented as required in the VM env template, but only the installer enforces it.SH_PERSISTENT_EXECandANTHROPIC_MODELappear in the supervisor/metricsallowlist but are read by no P6 code.SH_WORKER_IDnow has a reader: the async drain's consumer name (moca-${HOSTNAME}-w${SH_WORKER_ID}, #389), which falls back tow0when it is unset.SH_ROUTING_POLICY=stickyBySessionis valid but appears in no template.