Sandboxes

Long-lived interactive sessions — exec, suspend/resume, live egress grants and preview URLs.

postCreate Sandbox

Creates a sandbox from an environment in the same namespace and starts its pod. Resolves the workload command (request argv, then the environment's default_argv, then the image ENTRYPOINT/CMD; exec_only runs nothing), creates any ephemeral workspace mounts, and applies the base egress policy (deny-all when none is given; the egress bootstrap defaults to 24h when max_lifetime_sec is 0). Rejects an environment in another namespace (PermissionDenied), platform-owned env names (InvalidArgument), both workspace_id and workspaces set, more than 8 mounts, a non-absolute or unclean working_dir, and a durable workspace already attached to another live sandbox (FailedPrecondition). Unimplemented without cluster access. **Access:** namespace OPERATOR or above (write)

postDelete Sandbox

Deletes a sandbox: hard-kills its pod, revokes its agent key, drops its egress binding, console sessions and preview exposures, removes the record, then deletes any ephemeral workspaces it owned. No flush and no snapshot: snapshot first to keep content. **Access:** namespace OPERATOR or above (write)

postExec In Sandbox

Bidirectional stream running an argv (never shell-joined) in a RUNNING sandbox. The first client message must be the ExecSpec; later messages are stdin chunks or stdin_close. The server streams stdout/stderr frames then a final exit whose code/termination is status-derived; a timeout_sec deadline yields TERMINATION_TIMEOUT with code -1. Keeps the idle-suspend clock fresh for the session. Rejects an empty argv and wait=EXEC_WAIT_PROCESS combined with tty (InvalidArgument), and a sandbox that is not running (FailedPrecondition). **Access:** namespace OPERATOR or above (write)

postExpose Sandbox Port

Publishes a sandbox port on an isolated preview URL and records it on the sandbox; idempotent per port. port must be 1-65535, and 53, 80 and 443 are refused because the egress capture owns them (InvalidArgument). Only AUTH_SIGNED_URL returns an access token (embedded in the URL); FORWARD_AUTH and PUBLIC are resolved at access time. Unimplemented when no preview domain is configured. **Access:** namespace OPERATOR or above (write)

postGet Sandbox

Returns one sandbox. Egress fields are filled from the live egress binding, so they show what the proxy enforces now (expired grants are omitted). NotFound for an unknown id. **Access:** namespace VIEWER or above (read)

postGrant Egress

Adds one additive, independently revocable egress grant on top of the sandbox's base policy; the egress in force is the base unioned with every active grant. Takes effect on the proxy through the live policy feed without a restart. ttl_sec 0 means no expiry; otherwise at most 86400. The reason is recorded in the audit log. Rejects a missing policy (InvalidArgument) and a sandbox created without egress configured (FailedPrecondition); Unimplemented when egress signing is not configured. Returns the new grant id. **Access:** namespace OPERATOR or above (write)

postKeep Sandbox Alive

Restarts the idle-suspend clock without running anything in the sandbox, and returns when the sandbox would next be idle-suspended (0 when idle_suspend_sec is 0). Deliberately a read-level operation. FailedPrecondition when the sandbox is not RUNNING. **Access:** namespace VIEWER or above (read)

postList Sandboxes

Lists sandboxes in a namespace, newest first, optionally filtered by state. namespace is required unless the caller is a platform admin (empty then lists every namespace). page_size defaults to 100 and is clamped to 1000. **Access:** namespace VIEWER or above (read)

postResume Sandbox

Reschedules a suspended (or crashed) sandbox's pod from its persisted record: same command, resources, env, mounts and base egress, with a fresh agent key and control token. Clears any dead pod carrying the sandbox's name first. FailedPrecondition when a durable workspace it mounts was attached to another live sandbox in the meantime. **Access:** namespace OPERATOR or above (write)

postRevoke Egress

Removes exactly one grant by id, leaving the base policy and other grants intact; takes effect on the proxy via the live feed. grant_id is required (InvalidArgument); an unknown grant is NotFound. **Access:** namespace OPERATOR or above (write)

postSuspend Sandbox

Suspends a sandbox: records a SUSPENDED marker in the run log, deletes the pod gracefully (30s grace when a writable workspace needs flushing, 10s otherwise), marks the record SUSPENDED, revokes the agent key and marks console sessions lost. Workspaces and the egress binding are kept for resume. **Access:** namespace OPERATOR or above (write)

postSync Sandbox Workspace

Forces the sandbox's agent to flush local changes back to the workspace store now rather than on the periodic sync, and reports files/bytes flushed plus conflict paths accumulated since the last call. Empty workspace_id flushes every read-write mount. FailedPrecondition when the sandbox has no writable workspace or is not RUNNING. **Access:** namespace OPERATOR or above (write)

postTail Sandbox Logs

Streams the sandbox's retained run log (workload output plus typed lifecycle markers) across its whole life, including suspends. Starts after from_offset (0 = oldest retained), optionally restricted to one run. limit caps history replayed per read (0 = 2000). With follow, stays open and polls for new output about every 2 seconds. sandbox_id is required (InvalidArgument). **Access:** namespace VIEWER or above (read)

postUnexpose Sandbox Port

Drops a port from the sandbox's preview exposures. Metadata only: already-issued tokens stop working when they expire. A port that is not exposed is a no-op. Unimplemented when no preview domain is configured. **Access:** namespace OPERATOR or above (write)

postWatch Sandbox

Server stream of sandbox state changes, derived from the record and the live pod phase and polled about every 2 seconds. Emits only on change and ends once the sandbox is TERMINATED. Unimplemented without cluster access. **Access:** namespace VIEWER or above (read)