Skip to main content
Version: v0.11.0

Configuration reference

Preview. Describes the P6 runtime as of main on 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 in deploy/vm/env/*.env.example.

Conventionsโ€‹

  • Secret means the value is a credential. On a VM, SH_EXCHANGE_TOKEN, SH_SESSION_TOKEN_PRIVATE_KEY and SH_CREDENTIAL_KEK are systemd credentials (LoadCredential=), as is SH_OPERATOR_INFERENCE_TOKEN when configured by setup-vm.sh. Setting one of those in an env file as well makes its consumer refuse to boot. MOCA_RELAY_EXEC_TOKEN and SH_RELAY_TOKEN are plain EnvironmentFile lines (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: blank SH_TURNS_PER_WORKER refuses to boot, and a blank SH_MODEL is kept as an empty string rather than defaulting.
  • Strict vs lenient parsing. The supervisor's own config.ts (including SH_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 as 1.9, 1e4 and 0x1F90 with no upper bound. Several worker settings (SH_STATS_INTERVAL_MS, the KAGENTI_SANDBOX_* lease and affinity timings, KAGENTI_SYNC_SATURATION_*) also fall back silently, so a typo produces no error. The Go microVM worker refuses a malformed WORKER_MAX_CONCURRENT. MOCA_ASYNC_QUEUED_PER_OWNER and MOCA_TURN_SUMMARY_BYTES are the exceptions: they use a strict parser (countEnv), because 0 is a meaningful setting for both and intEnv would 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.

VariableDefaultRequired / notesMeaning
SH_TURNS_PER_WORKERnoneRequired, at least 1; blank refuses to bootS, the in-flight turn cap per worker
SH_TURNS_PER_SUBJECThalf of S, min 1Integer 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 companionPer-subject in-flight turn cap per worker (#360)
PORT8080Integer 0-65535Data-path listen port
SH_ADMIN_PORT8081Must differ from PORT unless 0Admin listener (/metrics, /healthz, /readyz)
SH_ADMIN_HOST127.0.0.1IP literal only. The admin listener is unauthenticated; widen it only behind your own access controlAdmin bind address
SH_WORKERSCPU count available to the unitInteger at least 1W, the worker count
SH_ROUTING_POLICYleastInFlightleastInFlight or stickyBySession; others refuse to bootHow accepted sockets are routed
SH_WORKER_RESTART_BACKOFF_MS250Integer at least 0Backoff 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.

VariableDefaultRequired / notesMeaning
SH_REQUIRE_AUTHoff (only true enables)Required true when MOCA_TENANCY=multi. A bad token is refused even when offEvery turn needs a control-plane session token
SH_SESSION_TOKEN_PUBLIC_KEYSemptyMalformed value fails the boot. VM: setup-vm.sh writes it onceThe control plane's public keyset, <kid>:<base64 SPKI>
SH_CONTROL_PLANE_URLunsetNo 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 itWhere the worker reaches the control plane for credential exchange
SH_EXCHANGE_TOKENunsetSecret. Env plus credential file, or an empty file, fails the boot. Also the async claim's bearer when SH_ASYNC_DRAIN is onThe workers' bearer for the control plane's exchange hop
MOCA_TENANCYsinglesingle 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 agreemulti scrubs ambient provider credentials. No shipped template sets it
SH_LOCAL_TOOLSoffRefused under multiSingle-tenant dev opt-in: run tools in the worker
REDIS_URLredis://127.0.0.1:6379URL may carry a passwordSessions, leases, affinity, sandbox records, turn log, bundles
CREDENTIALS_DIRECTORYunsetsystemd sets it; the K8s manifests set it by hand to /run/credentialsWhere credential files are read first
MOCA_VERSIONdevReported version, baked in at image build
SH_STATS_INTERVAL_MS1000Invalid 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 intervalPace of advisory stats from workers

Worker: sandbox selection, affinity and tiersโ€‹

VariableDefaultRequired / notesMeaning
SH_REMOTE_SANDBOXoff (only 1 enables)A pool selector without 1 fails the selection, naming both variablesRead the sandbox presence records mirrored from the relay
SH_SANDBOX_DISCOVERYunset (records)Removed modes: pods and both throw, naming ADR-0041. Unset or records is the only behaviourKept only so a stale value fails loudly instead of quietly changing
SH_RELAY_ADDRsandbox-relay.default.svc.cluster.local:8443Must 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 portAddress of the relay's SandboxExec listener
MOCA_RELAY_EXEC_TOKENnoneSecret. Required when the exec client is built. Must equal the relay'sThe workers' credential for the relay's SandboxExec
KAGENTI_SANDBOX_POOL_SELECTORunsetTemplates 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 selectionGate for leasing from the sandbox pool (records are filtered by tier and workload, not by this literal)
KAGENTI_SANDBOX_CWD/workspaceMust equal the sandbox worker's SH_WORKSPACE_ROOT, or sessions do not get their own <root>/<sessionId> directoryWorking directory in the sandbox
KAGENTI_SANDBOX_CAP20Invalid or below 1 falls back. Templates set 4Soft cap on leases per sandbox
KAGENTI_SANDBOX_LEASE_TTL_MS60000Floor 1000. Set by no templateLease TTL
KAGENTI_SANDBOX_HEARTBEAT_MS20000Clamped to at most TTL/3. Set by no templateLease renewal interval
SH_SANDBOX_TIERSunset (untiered)Comma-separated; duplicate or invalid names throw. Must match the control plane exactlyDeclared sandbox tiers
SH_SANDBOX_DEFAULT_TIERthe only tier, if oneRequired when more than one tier is declared; must be a declared tierTier for sessions that do not choose
SH_SANDBOX_AFFINITY_TTL_SECONDS86400Keep at least the P4 worker's SH_WORKSPACE_IDLE; must equal the relay's copyHow long a session remembers its sandbox
SH_SANDBOX_AFFINITY_GRACE_SECONDS600 is legalHow long a turn waits (503) for its sandbox before moving within the tier

Worker: turns, model and budgetโ€‹

VariableDefaultRequired / notesMeaning
SH_TURN_DETACHoff (only 1 enables)Templates enable itDetachable, re-attachable turns
SH_TURN_DETACHED_MAX_S1800Blank or invalid falls backUnwatched turns end after this
SH_TURN_LOG_TTL_S86400Blank or invalid falls backA finished turn stays replayable this long
SH_ASYNC_DRAINoff (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 bootEvery worker also drains the async leaf queue (#389)
MOCA_ASYNC_RUNNING_PER_OWNERunset (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_SUBJECTAsync leaves one owner may RUN deployment-wide (#391)
SH_TURN_STREAM_TOOL_RESULT_PREVIEW_BYTES2048Byte cap on tool_result previews in the stream
SH_TURN_PATCH_MAX_BYTES4194304 (4 MiB)Positive integer; at most the 8 MiB output cap less 4 KiBOver it, a templated turn's workspace.patch is left out (patchRefused), never cut
SH_TURN_STREAM_KEEPALIVE_MS200000 disablesInterval of the stream's : keepalive comment
SH_TURN_STREAM_FIRST_FRAME_FLUSH_MS150000 disablesFlush SSE headers if no frame by then
SH_MODEL_PROVIDERanthropic (openai on the custom openai-completions path)Model provider
SH_MODELclaude-opus-4-8A 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_CUSTOMoff (only 1 enables)Requires a base URL (below)Synthesize a model not in Pi's registry
SH_MODEL_APIanthropicanthropic, 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_URLnoneA custom model throws without it, unless ANTHROPIC_BASE_URL (anthropic) or OPENAI_BASE_URL (openai) is setEndpoint
SH_MODEL_AUTHbeareropenai-completions only (ignored with anthropic). custom-header and none strip the Authorization headerAuth style
SH_MODEL_HEADERSnoneopenai-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_WINDOW131072Custom model context window
SH_MODEL_MAX_TOKENS8192Custom model max tokens
SH_BUDGET_TOKENS, SH_BUDGET_MARGINnoneApplied 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: budgetToken budget and margin
SH_PROMPT_CACHEunset (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_CACHEunset (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 itoff adds cache: {"no-cache": true} to the agent's model requests, bypassing the response cache
ANTHROPIC_API_KEYnoneSecret. Under multi tenancy it is forced to a sentinel and every ambient provider credential is scrubbed (see below)Provider key
ANTHROPIC_AUTH_TOKENnoneSecret. Not used for an authenticated (control-plane) turnGateway bearer
ANTHROPIC_BASE_URLnoneGateway or endpoint
OPENAI_API_KEY, OPENAI_BASE_URLnoneSecret (key). OPENAI_API_KEY is seeded with unused for custom-header and noneOpenAI-compatible provider
HARNESS_CWDprocess cwdTurn working directory
LEAF_RESULT_TTL_SECONDS604800 (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 keysTTL of leaf results (sync /runs and async drain)
SH_RUN_HEARTBEAT_MS10000Blank or invalid falls backHow often a sync /runs run refreshes its in-flight heartbeat (#558)
SH_RUN_STALE_MS60000Blank 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_MS30000Non-positive falls back to the defaultSweep interval of the orphaned-run reaper every worker arms (#558)
KAGENTI_SYNC_SATURATION_WAIT_MS, _BACKOFF_MS, _MAX_BACKOFF_MS30000, 250, 5000Parsed lenientlySync /runs retry while the pool is saturated
KAGENTI_SYNC_SATURATION_RETRY_AFTER_S5Retry-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.

VariableDefaultNotes
MOCA_CONTEXT_WORKLOADS_ENABLEDoffFeature switch
CONTEXT_SERVICE_URLnone
CONTEXT_SERVICE_PUBLIC_URLnoneRequired for workloads; HTTPS except on loopback
CONTEXT_SERVICE_TOKENnoneSecret. Required for workloads
CONTEXT_SERVICE_NAMESPACE (falls back to POD_NAMESPACE)default
CONTEXT_SERVICE_TIMEOUT_MS5000
MOCA_CONTEXT_MAX_STORAGE_GIB10
MOCA_CONTEXT_MAX_WORKLOADS_PER_OWNER5
MOCA_WORKLOAD_DELETED_TTL_SECONDS86400TTL of the deleted-workload record
MOCA_CONTEXT_ROLLBACK_RETRY_ATTEMPTS3Create-rollback cleanup attempts (including the first) while Context Service is unreachable; 1 means no retry
MOCA_CONTEXT_ROLLBACK_RETRY_BACKOFF_MS500Backoff between those attempts
MOCA_CONTEXT_STORAGE_CLASSESempty (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:

VariableDefaultNotes
MOCA_PROVISIONER_URLunset (off)moca-provisioner's internal API. Set, POST /workloads accepts sandboxes
MOCA_PROVISIONER_TOKENnoneSecret. Required with the URL (500 workloads_misconfigured otherwise)
MOCA_PROVISIONER_TIMEOUT_MS15000Per-request timeout
MOCA_PROVISIONER_DELETE_WAIT_MS60000How long DELETE waits for the workload's pods to go before answering 202
MOCA_WORKLOAD_MAX_SANDBOXES2Largest sandboxes.count; the provisioner checks it again
MOCA_WORKLOAD_MAX_STORAGE10GiLargest workspace.size with workspace.mount (<n>Mi or <n>Gi)
MOCA_WORKLOAD_STORAGE_CLASSESempty<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.

VariableDefaultNotes
MOCA_ATTACH_PRIVATE_KEYnoneSecret, required. Ed25519 key that signs attach tokens; its public half is the relay's MOCA_ATTACH_PUBLIC_KEYS
MOCA_PROVISIONER_TOKENnoneSecret, required. The workers' service token
SH_SESSION_TOKEN_PUBLIC_KEYSnoneRequired. Verifies the API token a worker forwards
MOCA_SANDBOX_NAMESPACEmoca-sandboxThe one namespace it acts in
MOCA_PROVISIONER_PORT8080
MOCA_WORKLOAD_MAX_SANDBOXES2count per workload
MOCA_OWNER_MAX_SANDBOXES4An owner's replicas across all workloads
MOCA_ATTACH_TOKEN_TTL_S86400Attach-token lifetime; re-minted when less than half remains
MOCA_PROVISIONER_RECONCILE_S300How often it checks tokens for re-minting and sweeps orphaned workloads
MOCA_PROVISIONER_ORPHAN_GRACE_S600A workload's objects are swept only once all are older than this (record missing, deleted, deleting or of another generation)
REDIS_URLunset (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_MS2000The bound on each record read; a read past it skips that workload for the pass
MOCA_WORKLOAD_MAX_STORAGE10GiA mounted workload's largest PVC
MOCA_WORKLOAD_STORAGE_CLASSESempty<class>:rwo or <class>:rwx; empty: the default class, ReadWriteOnce
MOCA_PROVISIONER_SEED_PORT8081The seed port: GET /seed/v1/bundle with an attach token, nothing else
MOCA_PROVISIONER_SEED_URLhttp://moca-provisioner.moca.svc:8081/seed/v1/bundleWhat workload pods' init containers fetch their bundle from
MOCA_PROVISIONER_SEED_BUDGET_BYTES1073741824 (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_S600How long a bundle is held, seeded or not; then GET reports seed: bundle_missing until the next activate resends it
MOCA_CONTEXT_BUNDLE_MAX_BYTES268435456Largest 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_ENTRIES10000Most 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.

VariableDefaultRequired / notesMeaning
SH_RELAY_PORT8443Templates use 9443. Sandboxes dial it as RELAY_ADDRAttach bind port (all interfaces)
MOCA_RELAY_EXEC_ADDRunset (exec shares the attach listener)Templates set a separate listener. The supervisor's SH_RELAY_ADDR must dial thisBind address for SandboxExec
MOCA_RELAY_EXEC_TOKENnoneSecret, required. The relay refuses to boot without it, or if it equals SH_RELAY_TOKEN or a per-sandbox env tokenExec caller credential; must equal the supervisor's
SH_RELAY_TOKENnoneSecret. Attach is fail-closed: with no token every attach is rejected. An empty value counts as missingShared sandbox attach token; must match each sandbox's SANDBOX_TOKEN
SH_RELAY_TOKEN_<sandboxId>falls back to SH_RELAY_TOKENSecret. 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 thesePer-sandbox attach token
SH_RELAY_TOKEN_DIRunsetOne 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-tokensToken directory
MOCA_ATTACH_PUBLIC_KEYSunset (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_MS20000Milliseconds: 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 PINGsHow often the relay PINGs each connection, on both listeners
MOCA_RELAY_KEEPALIVE_TIMEOUT_MS10000Same 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 policyHow long the relay waits for a PING ack
SH_SANDBOX_AFFINITY_TTL_SECONDS86400Must match the supervisor'sTTL of the detach mark
REDIS_URLredis://127.0.0.1:6379Same Redis as the supervisorSandbox pool mirror

Control planeโ€‹

packages/control-plane/src/main.ts.

VariableDefaultRequired / notesMeaning
SH_SESSION_TOKEN_PRIVATE_KEYnoneSecret, requiredToken signing key
SH_CREDENTIAL_KEKnoneSecret, required; must decode as a valid key ringEnvelope-encryption key ring for stored credentials
SH_EXCHANGE_TOKENnoneSecret, required. Same value as the workers'Bearer workers present for the exchange hop
MOCA_GRANT_SIGNING_KEYunsetSecret, 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 verifiesGrant ring signing key
MOCA_GRANT_PUBLIC_KEYSempty<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 bootExtra grant verification keys
MOCA_GRANT_TTL_S300Blank 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 loopHow long one grant lives
MOCA_TURN_MAX_S1800Blank 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 failingDeployment-wide ceiling on one turn
MOCA_INFERENCE_ADDRunsethost: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 loopbackThe inference listener's bind address
MOCA_INFERENCE_URLderived from MOCA_INFERENCE_ADDRWhat 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 twiceWhat the worker dials
SH_GITHUB_CLIENT_IDnoneRequired when SH_IDENTITY_PROVIDER=github (the default). A GitHub OAuth app with device flow enabled; no client secretLogin
SH_IDENTITY_PROVIDERgithubgithub 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_ISSUERnoneRequired when oidc. The provider's issuer URL (e.g. https://<issuer>); discovery is read from /.well-known/openid-configurationLogin
SH_OIDC_CLIENT_IDnoneRequired when oidc. The client id registered with the providerLogin
SH_OIDC_REDIRECT_URInoneRequired 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_SECRETnoneSecret, required when oidc. Resolved through withCredentials (systemd credential or K8s secret), never committedLogin
SH_OIDC_SCOPEopenid email profileOnly when oidcLogin
SH_OIDC_MAX_PENDING_PER_SOURCE20Only 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_HOPSLogin
SH_TRUSTED_PROXY_HOPS0How 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 authorizationLogin
SH_PUBLIC_HARNESS_URLunsetCode does not require it (discovery returns harnessUrl: null), but the VM installer does. Absolute http(s) URLHarness URL advertised to clients (GET /v1/discovery)
SH_CONTROL_PLANE_PORT8080VM template uses 8090 (8080 is the supervisor's). Invalid silently falls backListen port
SH_CONTROL_PLANE_HOSTall interfacesVM template sets 127.0.0.1: plain HTTP, reach it through a tunnelBind address
REDIS_URLredis://127.0.0.1:6379Retries foreverOwnership index, refresh tokens, bundles
SH_CREDENTIAL_STOREkuberneteskubernetes, file or vault. VM and Compose use fileCredential store backend
SH_CREDENTIAL_DIRnoneRequired for fileFile store path
SH_CREDENTIAL_NAMESPACEsh-credentialsKubernetes store; the K8s manifests use moca-credentialsSecret namespace
VAULT_ADDR, VAULT_TOKEN or VAULT_TOKEN_FILE (exactly one), VAULT_NAMESPACE, SH_VAULT_KV_MOUNT (secret), SH_VAULT_PATH (moca/credentials)noneVault store only; no template wires it. Token is a secretVault credential store
SH_ADMIN_SUBJECTSnoneComma-separated github:<id> or oidc:<sub>Admin role
SH_ALLOWED_SUBJECTSnoneRequired 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 rolesEnrolled subjects
SH_INSTALLER_TOKENunset (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_USERS0 (off)Dev/test only. 1-1000; needs SH_TEST_USER_SECRET; refused on the sandbox profile; on --target ocp needs SH_TEST_USERS_ACKSynthetic test:N logins (ADR-0045)
SH_TEST_USER_SECRETnoneSecret, 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 itShared secret a test-user login must present
SH_DEFAULT_INFERENCE_ENDPOINTnoneValidated if set. For Anthropic use https://api.anthropic.com (no /v1)Gateway origin for credentials with no endpoint
SH_ALLOW_OPERATOR_FALLBACKoff (only true enables)true requires the token and endpoint, mutually consistent, or boot failsUsers without their own credential spend the operator's
SH_OPERATOR_INFERENCE_TOKENnoneSecret. On a VM, a credential file via a drop-in setup-vm.sh creates; never an env lineThe operator's inference key
SH_OPERATOR_INFERENCE_HEADERauthorizationauthorization or x-api-key; an Anthropic API key needs x-api-keyHeader the operator key travels in
SH_API_TOKEN_TTL_SECONDS / SH_SESSION_TOKEN_TTL_SECONDS900 / 300Invalid silently falls backToken lifetimes
SH_REFRESH_IDLE_TTL_SECONDS / SH_REFRESH_MAX_TTL_SECONDS2592000 / 7776000Idle must not exceed maxRefresh token lifetimes
SH_REFRESH_REUSE_GRACE_SECONDS30Invalid or 0 silently becomes 30, so the grace cannot be disabled; above 300 throwsGrace for a retried refresh
SH_SANDBOX_TIERS / SH_SANDBOX_DEFAULT_TIERas for the workerMust match the supervisor's exactlyTiers a session may choose
SH_ROUTE_PROFILEharnessExactly 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 subjectThe route set this control plane serves
SH_SANDBOX_TOKEN_TTL_SECONDS900sandbox 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_SUBJECT3sandbox and combined. A positive integer or boot failsLive sandboxes per subject
SH_SANDBOX_LIFETIME_SECONDS604800 (7 days)sandbox and combined. A positive integer, at least 3600, and at most SH_SANDBOX_MAX_LIFETIME_SECONDS, or boot failsDefault sandbox lifetime
SH_SANDBOX_MAX_LIFETIME_SECONDSSH_SANDBOX_LIFETIME_SECONDSsandbox and combined. At least 3600. Setting it turns idle lifetimes on: an owner's activity slides the deadline. Unset, the deadline is fixed at createLongest lifetime an owner may pick
SH_SANDBOX_MODES_ALLOWEDper-execsandbox 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 bootSandbox modes an owner may pick
SH_SANDBOX_IDLE_CEILING_S1800sandbox and combined. A positive integer, at least 30, or boot failsLongest lease idle timeout
SH_SANDBOX_TEMPLATESunset (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_DIRunsetAbsolute 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 standTemplate store and provenance records
SH_GATE_RECORD_SCHEMAmoca-gate-record/1Sandbox 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 gateRecordSchemaThe 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 401The template host agents and their bearers
SH_BUNDLE_SUBJECT_BYTES / SH_BUNDLE_TOTAL_BYTES16 MiB / 64 MiBPositive integer strings or boot failsConfig-bundle byte budgets
SH_SESSION_TOKEN_PUBLIC_KEYSemptyMalformed throwsExtra public keys for rotation
SH_INJECTOR_CONFIGUREDoffNo template sets itSkips the direct-mode mismatch check
SH_SANDBOX_NAMESPACEdefaultUsed on Kubernetes pathsSandbox namespace
SH_MODEL_CATALOG_HOSTSemptyComma-separated bare hostnames, case-insensitive; a URL, port or path refuses to bootExtra hosts the model catalog may contact
MOCA_ASYNC_QUEUED_PER_OWNER50Non-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 waitingNon-terminal async turns one owner may hold (ADR-0047)
MOCA_TENANCYsinglesingle or multi; a near-miss spelling of the name throws, here as in the worker. Must match the worker'sTenancy mode
LEAF_RESULT_TTL_SECONDS604800 (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 togetherAsync turn record retention (ADR-0047)
MOCA_TURN_SUMMARY_BYTES2048Non-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 writeAsync 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)โ€‹

VariableDefaultNotes
RELAY_ADDRlocalhost:8443The relay's attach address
SANDBOX_TOKENdev-tokenSecret. Equals the relay's SH_RELAY_TOKEN (or its per-sandbox token). Do not leave the default
SANDBOX_TOKEN_FILEunsetA 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_FILEoffTLS to the relay; a garbage RELAY_TLS is fatal
SANDBOX_IDsbx-laptop-1Unique per sandbox
SANDBOX_TIERcontainerAdvertised as the moca.dev/tier label. If set but blank, no label: a tiered harness excludes the worker
SANDBOX_TEMPLATEunsetAdvertised as the moca.dev/template label; unset or blank, none: only sessions naming the template land here
WORKER_MAX_CONCURRENT4Concurrency slots; garbage or non-positive falls back
SANDBOX_IMAGE, SANDBOX_TRUSTempty, untrustedLabels
SH_WORKSPACE_ROOTbuilt-in defaultAbsolute path
SH_WORKSPACE_IDLE30mGo 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_IDLE15mGo 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:

VariableDefaultNotes
SH_SNAPSHOT_DIRnoneRequired
WORKER_MAX_CONCURRENT16Positive integer; a malformed or non-positive value is fatal, not a fallback. Not the container worker's 4
SH_WORKSPACE_ROOTnoneRequired
SH_MAX_COMMITTED_MBnoneRequired, positive integer: the worker refuses to start without it. Size it against the slot count
SH_VMMfirecrackerfake and unknown values are refused
SH_ALLOW_INSTANCE_TYPE_MISMATCHoffOpts a host out of the snapshot instance-type check, for deliberate cross-host use
SH_VERIFY_MEMFILEoffExactly 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_CACHEon0: 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_PATHper snapshotAbsolute 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-cacheThe 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_RECORDunsetPath 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_DEPTHbuilt-inWarm standby VMs
SH_STANDBY_HEADROOM4full (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_MBbuilt-inPer-guest RAM
SH_MAX_RUNS64Positive integer
SH_MEMORY_RESERVE_MBnonePositive integer if set
SH_HOST_MEM_FLOOR_MBoffPositive 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_IDLEbuilt-inGo duration; setup-microvm.sh sets it from MICROVM_WORKSPACE_IDLE (default 8h)
SH_PARENT_CGROUPbuilt-inSlice-relative; under systemd a nonexistent path is fatal
SH_JAILER_BIN, SH_FIRECRACKER_BIN, SH_CHROOT_BASEPATH, /srv/jailBinary and jail locations
SH_WORKSPACE_IMAGE_MB2048Positive integer
SH_SNAPSHOT_IMAGEdefault

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โ€‹

VariableDefaultNotes
SH_CONTROL_PLANE_URLsaved configPrecedence: flag, env, config, the login's own URL
SH_HARNESS_URLsaved config, else discoveryOverrides the harness URL that discovery returns
XDG_CONFIG_HOME~/.configmocactl/config.json and the login file (holds tokens)
XDG_STATE_HOME~/.local/stateTranscripts and exports
VISUAL / EDITORviExternal editor
NO_COLORoffDisables 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 by deploy/compose/install.sh, setup-vm.sh and deploy/microvm/build-rootfs.sh. The pull is otherwise fail-closed in all three, because neither docker compose up -d nor podman run re-resolves a reference the host already holds a copy of โ€” so a :latest pulled once is what every later run starts (#349, #414).
  • Compose install.sh inputs: 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 default http://127.0.0.1:8080), SH_WORKSPACE_IDLE (the container sandboxes' idle reclaim, default 8h; 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; 0 installs none and removes an installed one); the host agent's SBX_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 PSI full avg10 is 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 no starting, 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's SBX_TEMPLATE_HOSTS lists the hosts and writes each one's bundle.

Known inconsistenciesโ€‹

  • SH_PUBLIC_HARNESS_URL is documented as required in the VM env template, but only the installer enforces it.
  • SH_PERSISTENT_EXEC and ANTHROPIC_MODEL appear in the supervisor /metrics allowlist but are read by no P6 code. SH_WORKER_ID now has a reader: the async drain's consumer name (moca-${HOSTNAME}-w${SH_WORKER_ID}, #389), which falls back to w0 when it is unset.
  • SH_ROUTING_POLICY=stickyBySession is valid but appears in no template.