@@ -10,7 +10,7 @@ Each sandbox workload has two trust levels:
1010
1111| Process | Role |
1212| ---| ---|
13- | Supervisor | Starts as root inside the workload, prepares isolation, runs the proxy, fetches config , injects credentials, serves the relay socket, and launches child processes. |
13+ | Supervisor | Starts as root inside the workload, applies desired state, prepares isolation, runs the proxy, injects credentials, serves the relay socket, and launches child processes. |
1414| Agent child | Runs as an unprivileged user with filesystem, process, and network restrictions applied. |
1515
1616The supervisor keeps enough privilege to manage the sandbox, but the agent child
@@ -25,15 +25,55 @@ only when the set is already empty; any other outcome fails the spawn.
2525
26261 . The compute runtime starts the workload with sandbox identity, callback
2727 endpoint, TLS or secret material, image metadata, and initial command.
28- 2 . The supervisor loads policy and runtime settings from local files or the
29- gateway, depending on mode.
30- 3 . It prepares filesystem access, process restrictions, network namespace
28+ 2 . In gateway-backed mode, the supervisor opens ` ConnectSupervisor ` before it
29+ initializes gateway-owned runtime state. The gateway sends a complete
30+ configuration, provider environment, and inference bootstrap.
31+ 3 . The supervisor applies the bootstrap, or loads explicit local files in
32+ standalone mode. A required configuration or policy failure aborts startup.
33+ 4 . It prepares filesystem access, process restrictions, network namespace
3134 routing, trust stores, provider credential resolution, and inference routes.
32- 4 . It launches the persisted canonical main-process argv and retains its PTY
35+ 5 . It launches the persisted canonical main-process argv and retains its PTY
3336 or pipes in the main-session multiplexer.
34- 5 . It starts the policy proxy and local SSH server.
35- 6 . It opens a supervisor session back to the gateway for connect, exec, file
36- sync, config polling, and log push.
37+ 6 . It starts the policy proxy and local SSH server, then signals runtime-ready.
38+ 7 . The gateway enables connect, exec, file sync, and other relay operations only
39+ after both bootstrap initialization and runtime-ready are complete.
40+
41+ ## Desired-State Delivery
42+
43+ ` ConnectSupervisor ` carries gateway-owned desired state. A fresh session always
44+ starts with a complete ` ConfigBootstrap ` . Bootstrap success marks the session
45+ initialized; ` SupervisorRuntimeReady ` separately proves that runtime-dependent
46+ services are available. Bootstrap failure or a 120-second timeout moves the
47+ sandbox to ` Error ` . Disconnect before initialization returns it to
48+ ` Provisioning ` .
49+
50+ After bootstrap, the gateway sends level-triggered ` ConfigUpdate ` messages for
51+ one component at a time. Request IDs correlate results, component-local sequence
52+ numbers reject stale delivery, and snapshot revisions remain equality-only
53+ content fingerprints. The gateway keeps at most one update in flight for each
54+ component and coalesces newer state. Failed live updates keep the sandbox
55+ ` Ready ` and add a component-specific degraded condition. Policy and inference
56+ retain their last-known-good runtime state. Invalid provider bindings fail
57+ closed by revoking static credential material while retaining fetched dynamic
58+ token grants.
59+
60+ Committed sandbox changes notify the session owner immediately. Provider and
61+ inference changes use a workspace-wide invalidation signal. A 30-second
62+ jittered reconciliation pass rebuilds snapshots for active locally owned
63+ sessions, repairing missed notifications and cross-replica writes. Reconnects
64+ discard queued state and begin again with one complete bootstrap.
65+
66+ Explicit local policy and inference files remain authoritative. Their component
67+ results report ` RETAINED_LOCAL_OVERRIDE ` , while non-conflicting gateway settings
68+ and provider state continue to update. A supervisor without a gateway does not
69+ open or wait for a session.
70+
71+ ` GetSandboxConfig ` remains a public read API. Policy status, policy analysis,
72+ log upload, credential refresh, and relay RPCs remain independent of desired
73+ state delivery. The old supervisor-only provider-environment and inference-bundle
74+ fetch RPCs no longer exist. Snapshot builders and component apply routines are
75+ shared implementation boundaries for a future direct transport; the runtime
76+ does not add a transport abstraction before that transport exists.
3777
3878## Isolation Layers
3979
@@ -195,10 +235,9 @@ the registry. Public custom-CA PEM travels with the stable registration.
195235
196236The slots live in a supervisor-owned ` ExtensionCredentialStore ` shared by every
197237gateway connection the supervisor opens, so the registry's clients and the
198- polling loop that rotates them observe the same credentials. Configuration
199- polling runs far more frequently than credentials expire, so the loop rotates
200- only when a credential is missing or has passed four fifths of its lifetime,
201- and bounds its sleep by the soonest rotation deadline.
238+ independent credential-refresh task observe the same credentials. The task
239+ rotates only when a credential is missing or has passed four fifths of its
240+ lifetime.
202241
203242Middleware cannot observe injected credentials or mutate supervisor-owned
204243credential, routing, or framing headers. Body transformations are re-evaluated
@@ -442,9 +481,9 @@ policy structure.
442481This holds even when the initial policy is enriched with baseline paths during
443482startup: the enriched revision the supervisor synced back to the gateway is the
444483revision it acknowledges, so a successfully constructed initial policy never
445- remains ` Pending ` . If the first poll returns a different revision, the supervisor
446- processes it through the normal reload path instead of treating it as already
447- loaded.
484+ remains ` Pending ` . If a subsequent pushed snapshot carries a different revision,
485+ the supervisor processes it through the normal reload path instead of treating
486+ it as already loaded.
448487
449488A newer sandbox-scoped revision can carry the same non-empty effective policy
450489hash as the currently loaded revision, for example when provenance changes
@@ -459,19 +498,22 @@ Policy status delivery uses a FIFO background worker. Retryable delivery
459498failures retain the ordered update and retry with capped exponential backoff;
460499terminal errors are logged and discarded. The outbox is nonblocking and does
461500not discard updates because of a fixed queue capacity, so status endpoint
462- outages cannot block policy polling , enforcement, settings, or provider
463- refreshes and cannot permanently lose the initial acknowledgement.
501+ outages cannot block desired-state application , enforcement, settings, or
502+ provider refreshes and cannot permanently lose the initial acknowledgement.
464503
465504Only sandbox-scoped revisions (` PolicySource::Sandbox ` , version greater than
466505zero) are acknowledged. Global policies and local-file development policies do
467506not use the sandbox revision API and produce no acknowledgement. When explicit
468- local Rego and data files are configured, the supervisor continues polling the
469- gateway for settings and provider refreshes but never replaces the local OPA
470- engine with a gateway policy revision.
507+ local Rego and data files are configured, pushed gateway updates still apply
508+ settings and provider changes but never replace the local OPA engine with a
509+ gateway policy revision.
471510
472511## Failure Behavior
473512
474- - If gateway config polling fails, the sandbox keeps its last-known-good policy.
513+ - If desired-state delivery or application fails after startup, the sandbox
514+ remains ready and reports a degraded condition. Policy and inference retain
515+ their last-known-good state; invalid provider bindings follow the fail-closed
516+ revocation behavior above.
475517- If a live policy or middleware-registry update is invalid, the supervisor
476518 rejects the combined update and keeps the current runtime pair.
477519- If an operator-run middleware call fails, the selected config's ` on_error `
0 commit comments