@namzu/sandbox 13.0.0 → 15.0.0

package/src/index.ts

@@ -44,6 +44,30 @@ import type {
 import { buildAciStandbyPoolBackend } from './backends/aci-standby-pool/index.js'
 import { buildDockerBackend, resolveLayout } from './backends/docker/index.js'
 import { buildFirecrackerBackend } from './backends/firecracker/index.js'
+import type { KubernetesEgressConfig } from './backends/kubernetes/egress-policy.js'
+import {
+	type KubernetesAgentAddressMode,
+	type KubernetesBackendInternalConfig,
+	type KubernetesClusterAccess,
+	type KubernetesReadTaskCapacityOptions,
+	type KubernetesReleaseTaskSandboxesOptions,
+	type KubernetesTaskCapacity,
+	buildKubernetesBackend,
+	readKubernetesTaskCapacity as readTaskCapacityOnCluster,
+	releaseKubernetesTaskSandboxes as releaseTaskSandboxesOnCluster,
+} from './backends/kubernetes/index.js'
+import type { KubernetesIngressConfig } from './backends/kubernetes/ingress-policy.js'
+import {
+	type KubernetesWorkspace,
+	type KubernetesWorkspaceOptions,
+	type KubernetesWorkspaceSummary,
+	type KubernetesWorkspaceSuspendOptions,
+	type KubernetesWorkspaceTransitionOptions,
+	createKubernetesWorkspace as buildKubernetesWorkspace,
+	deleteKubernetesWorkspace as deleteWorkspaceOnCluster,
+	listKubernetesWorkspaces as listWorkspacesOnCluster,
+	suspendKubernetesWorkspace as suspendWorkspaceOnCluster,
+} from './backends/kubernetes/workspace.js'
 
 // Re-export the layout types so consumers of `@namzu/sandbox` can
 // import them without also depending on `@namzu/sdk`. The canonical
@@ -78,11 +102,408 @@ export type {
 	OrchestratorTokenProvider,
 } from './backends/firecracker/index.js'
 export {
+	AgentDialFailedError,
+	AgentPreauthFrameTooLargeError,
+	AgentReadFileStreamUnsupportedError,
+	AgentWriteFileTooLargeError,
+	DEFAULT_MAX_WRITE_FILE_BYTES,
 	FIRECRACKER_AGENT_PROTOCOL_VERSION,
+	GUEST_FRAME_LIMIT_BYTES,
 	type SandboxAgentHandle,
+	TCP_PREAUTH_FRAME_LIMIT_BYTES,
 	type VsockTransportOptions,
 	VsockAgentTransport,
 } from './backends/firecracker/transport.js'
+// The `write-file` part protocol: the healthz feature string a guest
+// advertises when it can take a body larger than one frame, and the shape
+// of one part. Exported so a host writing its own guest, or asserting what
+// this one advertises, names them rather than repeating the literal.
+export {
+	WRITE_FILE_PARTS_FEATURE,
+	type WriteFilePart,
+} from './backends/firecracker/protocol.js'
+// The per-stream liveness heartbeat: the feature string a guest advertises
+// when it understands one, the frame both sides send, and how many missed
+// intervals end a stream. Same reason as above — a host asserting what this
+// guest advertises should name the string rather than repeat the literal.
+export {
+	MIN_STREAM_HEARTBEAT_MS,
+	STREAM_HEARTBEAT_FEATURE,
+	STREAM_HEARTBEAT_MAX_ECHO_FACTOR,
+	STREAM_HEARTBEAT_MISS_LIMIT,
+	type StreamHeartbeat,
+} from './backends/firecracker/protocol.js'
+// The read side of the same arrangement: one healthz feature string for
+// both the ranged `read-file` and the `read-file-stream` op, and the
+// request/event shapes they speak. Exported for the same reason — a host
+// writing its own guest, or asserting what this one advertises, names them
+// rather than repeating the literal.
+export {
+	READ_FILE_STREAM_FEATURE,
+	type ReadFileStreamEvent,
+	type ReadFileStreamRequest,
+} from './backends/firecracker/protocol.js'
+
+// Kubernetes (agent-sandbox on any cluster) public surface. The access union
+// is named by `KubernetesBackendConfig.access`, so a host that builds its own
+// credential callback can name what it is passing; the address mode is named
+// by `KubernetesBackendConfig.agentAddress` and decides whether the agent is
+// dialed at its Service FQDN (in-cluster host) or at its pod IP (a host
+// outside the cluster, on a routable pod network).
+export type {
+	KubernetesAgentAddressMode,
+	KubernetesClusterAccess,
+} from './backends/kubernetes/index.js'
+// Egress translation types named by `KubernetesBackendConfig.egress` — see
+// `backends/kubernetes/egress-policy.ts` for what each engine can express,
+// and what the two Kubernetes-only kinds (`no-network`, `public-internet`)
+// mean that the shared `EgressPolicy` union has no word for.
+export type {
+	EgressProfileLabel,
+	KubernetesCiliumDnsNarrowing,
+	KubernetesCiliumEgressNarrowing,
+	KubernetesEgressConfig,
+	KubernetesEgressEngine,
+	KubernetesEgressPolicy,
+	KubernetesEgressVerification,
+	KubernetesOnlyEgressPolicy,
+	KubernetesPerSandboxEgressConfig,
+} from './backends/kubernetes/egress-policy.js'
+// Per-sandbox egress — `config.egress.perSandbox`, which makes
+// `Sandbox.setNetworkPolicy` PRESENT on a kubernetes TASK handle instead of
+// omitted. Everything a host needs to configure it and to catch its two
+// refusals by class: a capability declared in a way this backend cannot
+// honour (wiring time), and a write refused because the operator-applied
+// admission fence that bounds it is not there — or cannot be read, which is
+// a different file to fix (call time, nothing written in either case).
+// `KubernetesNetworkPolicyHostError` is the third: an `allowedHosts` entry
+// that is not a hostname, or one the configured narrowing cannot express.
+// `KubernetesOwnerUidMissingError` is the fourth, and the only one raised
+// from an ACQUIRE — the object this backend created reported no uid, so a
+// policy written for it would be an orphan.
+// `KubernetesWorkspacePerSandboxEgressConfigError` is the fifth: the same
+// option reaching `createKubernetesWorkspace`, whose handle never carries
+// `setNetworkPolicy` — refused there rather than accepted and ignored.
+// See `backends/kubernetes/per-sandbox-policy.ts` — and, for
+// `KubernetesNetworkPolicyHostError`, which the config-level translation
+// refuses the same entries with, `backends/kubernetes/egress-policy.ts`.
+export { KubernetesPerSandboxEgressConfigError } from './backends/kubernetes/egress-policy.js'
+export { KubernetesWorkspacePerSandboxEgressConfigError } from './backends/kubernetes/egress-policy.js'
+export { DEFAULT_PER_SANDBOX_EGRESS_LABEL_KEY } from './backends/kubernetes/egress-policy.js'
+export {
+	KubernetesAdmissionFenceMissingError,
+	KubernetesAdmissionFenceUnreadableError,
+	KubernetesNetworkPolicyHostError,
+	KubernetesOwnerUidMissingError,
+	PER_SANDBOX_POLICY_NAME_PREFIX,
+} from './backends/kubernetes/per-sandbox-policy.js'
+// The default label key `KubernetesEgressConfig.profile` is written under.
+// Exported because an operator has to name that key's DOMAIN in the
+// controller's `allowed-label-domains` allowlist before a profiled claim is
+// accepted, and reading it off the package beats copying a string out of a
+// document.
+export { DEFAULT_EGRESS_PROFILE_LABEL_KEY } from './backends/kubernetes/egress-policy.js'
+// The egress union check's refusal and the shapes it reports, so a host can
+// catch an over-wide policy by class and print which policy it was. Separate
+// from `KubernetesEgressPolicyMismatchError` (the ONE named object drifting)
+// and from `KubernetesIngressPolicyError` (the agent port being reachable):
+// three refusals on one create path, told apart by class.
+export type {
+	EgressPolicyRefusal,
+	EgressPolicyVerdict,
+	ExaminedEgressPolicy,
+} from './backends/kubernetes/egress-policy.js'
+export {
+	KubernetesEgressNarrowingUnsupportedError,
+	KubernetesEgressPolicyConfigError,
+	KubernetesEgressPolicyUnionError,
+} from './backends/kubernetes/egress-policy.js'
+// What an egress PROFILE adds to the refusals above. Two are thrown: a
+// profile this backend will not emit (while the host is still being wired),
+// and a bound pod that never carried the label this backend asked the
+// controller for — refused rather than admitted, because admitting it would
+// run the sandbox under whatever policy DOES select it. The third is never
+// thrown on its own: a claim the controller refused because a label key's
+// domain is not on its allowlist still comes out as
+// `KubernetesAcquireError { reason: 'claim-rejected' }`, and
+// `KubernetesPodLabelsRejectedError` is that error's `cause`, naming the map
+// that was sent and the config key that moves it.
+export {
+	KubernetesEgressProfileConfigError,
+	KubernetesPodLabelNotObservedError,
+	KubernetesPodLabelsRejectedError,
+} from './backends/kubernetes/egress-policy.js'
+// Ingress verification types named by `KubernetesBackendConfig.ingress`, plus
+// the refusal a create raises when no applied policy closes the agent port —
+// catchable by class, and distinct from every other refusal on that path. See
+// `backends/kubernetes/ingress-policy.ts`.
+export type {
+	ExaminedIngressPolicy,
+	IngressPolicyRefusal,
+	IngressPolicyVerdict,
+	KubernetesIngressConfig,
+	KubernetesIngressEngine,
+	/** @deprecated Renamed to `UnreadPolicySource`; both checks report it. */
+	UnreadIngressPolicySource,
+	UnreadPolicySource,
+} from './backends/kubernetes/ingress-policy.js'
+export { KubernetesIngressPolicyError } from './backends/kubernetes/ingress-policy.js'
+// The errors a caller of a kubernetes sandbox has to be able to catch BY
+// CLASS rather than by matching a message: an acquire refused because the
+// guest is not deprivileged, a call after the handle ended (this host
+// destroyed it, or the cluster deleted it), and a rejected agent token.
+export {
+	KubernetesPrivilegeProbeError,
+	type PrivilegeProbeFailure,
+	type ProcStatusPrivileges,
+} from './backends/kubernetes/privilege-probe.js'
+export {
+	KubernetesSandboxDestroyedError,
+	KubernetesSandboxGoneError,
+} from './backends/kubernetes/sandbox.js'
+export {
+	KubernetesAgentAddressUnresolvableError,
+	// A guest that has fenced itself refuses one CALL here, not the
+	// workspace: the Firecracker tier's mapping of the same refusal retires
+	// the sandbox, which on a workspace would take the pod away from every
+	// other holder. See `backends/kubernetes/transport.ts`.
+	KubernetesAgentRetiringError,
+	KubernetesAgentUnauthorizedError,
+} from './backends/kubernetes/transport.js'
+// A workspace command that can outlive the connection watching it: the
+// options that ask for one, and the three refusals a caller has to be able
+// to catch BY CLASS — a guest image too old to keep output, an execution
+// that can no longer be attached to (past retention, or in a replaced
+// pod), and an observation this host gave up on WITHOUT cancelling, which
+// names the id and the byte offset another process resumes from.
+export type {
+	KubernetesAttachExecutionOptions,
+	KubernetesAttachRefusal,
+	KubernetesDetachedExecOptions,
+} from './backends/kubernetes/transport.js'
+export {
+	KubernetesExecutionAttachUnsupportedError,
+	KubernetesExecutionDetachedError,
+	KubernetesExecutionNotAttachableError,
+} from './backends/kubernetes/transport.js'
+// Guest sessions: a workspace terminal or background program that outlives
+// the connection — and the host process — that started it. The options that
+// name one, the rows `listSessions()` returns, the `BackgroundJobOutput`
+// shape `readSession()` answers in, and the three refusals a caller catches
+// BY CLASS: a guest image with no session registry, a session the guest
+// answered about and refused (past retention, or in a replaced pod), and an
+// attachment that ended while its program went on running.
+export type {
+	KubernetesAttachTerminalOptions,
+	KubernetesOpenTerminalOptions,
+	KubernetesReadSessionOptions,
+	KubernetesSessionOutput,
+	KubernetesSessionRefusal,
+	KubernetesSessionSummary,
+	KubernetesSessionTerminal,
+	KubernetesStartDetachedOptions,
+	KubernetesWorkspaceTerminal,
+} from './backends/kubernetes/transport.js'
+export {
+	KubernetesSessionRefusedError,
+	KubernetesSessionsUnsupportedError,
+} from './backends/kubernetes/transport.js'
+export { AgentSessionDetachedError } from './backends/firecracker/transport.js'
+// The `sessions` healthz feature string, and the session vocabulary its
+// frames use. Same reason as the two feature strings above: a host asserting
+// what an image can do should name the string rather than repeat the literal.
+export {
+	SESSIONS_FEATURE,
+	type SessionDetachReason,
+	type SessionKind,
+	type SessionState,
+} from './backends/firecracker/protocol.js'
+// Quiesce: stop every process a workspace's guest is running, while the
+// agent goes on serving, so a capture taken next is one nobody is writing
+// under. The report a host reads, the two refusals it catches by class, and
+// — for the same reason as the feature strings above — the `quiesce` string
+// itself and the scope vocabulary its report is written in.
+export type {
+	KubernetesQuiesceOptions,
+	KubernetesWorkspaceQuiesceRequest,
+} from './backends/kubernetes/workspace.js'
+export type { KubernetesQuiesceReport } from './backends/kubernetes/transport.js'
+export {
+	KubernetesQuiesceUnconfirmedError,
+	KubernetesQuiesceUnsupportedError,
+} from './backends/kubernetes/transport.js'
+export {
+	QUIESCE_FEATURE,
+	type QuiesceScope,
+	type QuiescedProcess,
+} from './backends/firecracker/protocol.js'
+// Flush: put a workspace's writes on its device on purpose, rather than
+// leaving them to whatever the guest kernel had written back when the pod
+// stopped. `suspend()` runs it by default; the verb, its options, the report
+// and the three named outcomes are exported for the hosts that flush at a
+// moment of their own — before a snapshot, before a drain — and for the
+// `flush` string itself, for the same reason as the feature strings above.
+// Only ONE of the three is ever thrown at a caller by a suspend
+// (`KubernetesFlushUnconfirmedError`, a guest that answered and could not
+// confirm); the other two are what `onFlushUnsupported` and
+// `onFlushUnreachable` are handed when the suspend goes ahead anyway, and a
+// host that wants to act on either has to be able to name the class.
+export type {
+	KubernetesFlushOptions,
+	KubernetesWorkspaceFlushRequest,
+} from './backends/kubernetes/workspace.js'
+export type { KubernetesFlushReport } from './backends/kubernetes/transport.js'
+export {
+	KubernetesFlushUnconfirmedError,
+	KubernetesFlushUnreachableError,
+	KubernetesFlushUnsupportedError,
+} from './backends/kubernetes/transport.js'
+export { FLUSH_FEATURE } from './backends/firecracker/protocol.js'
+// The API-request bound and the error it raises. Exported because
+// "distinguishable from a caller abort and from every other failure, by
+// type" is only true for a host that can name the class — and because a
+// host that sets `apiRequestTimeoutMs` wants the default and the floor it is
+// choosing against.
+// `KubernetesHttpMethod` rides along because `KubernetesApiTimeoutError.verb`
+// is one: a caller that can catch the class but cannot name the type of the
+// field it is reading is back to inlining the union or reaching for `any`.
+export {
+	DEFAULT_API_REQUEST_TIMEOUT_MS,
+	// Every API failure the four classes below do not name: a connect
+	// failure, and every non-2xx status outside 401/403/404/409/410. It
+	// carries the status and the `Retry-After` the server sent, because a
+	// burst past node capacity (429) and an API server that is down (a
+	// connect failure) were otherwise the same plain `Error`, separable only
+	// by matching a message any release is free to reword. It carries no
+	// retry policy — see `backends/kubernetes/index.ts` for who decides that.
+	KubernetesApiError,
+	type KubernetesApiFailureTransport,
+	KubernetesApiTimeoutError,
+	type KubernetesHttpMethod,
+	// A conditional write the API server would not apply. A host that fences
+	// its workspaces with a holder epoch normally catches
+	// `KubernetesWorkspacePreconditionError` instead — this one survives only
+	// when the object kept changing under the write or the patch body was
+	// wrong, and a caller that cannot name the class cannot tell it from a
+	// cluster failure.
+	KubernetesPatchNotAppliedError,
+	MIN_API_REQUEST_TIMEOUT_MS,
+} from './backends/kubernetes/k8s-client.js'
+// The three statuses the client maps to a class of their own, so a caller can
+// treat "already gone" as the state a teardown was asking for, re-read after a
+// 409, and tell a rejected credential from a cluster failure — by class, which
+// is the only way that survives a reworded message. They have been thrown
+// since the backend existed and were reachable only by importing a deep path.
+export {
+	KubernetesAlreadyGoneError,
+	KubernetesConflictError,
+	KubernetesCredentialError,
+} from './backends/kubernetes/k8s-client.js'
+// Why an acquire was refused, as a field rather than as prose: the seven
+// reasons, the class that carries one, and the measured list of controller
+// `Ready=False` reasons that mean "decided" rather than "not yet". A host
+// deciding whether to retry, to fail the run or to page an operator reads
+// `reason` and `retryable`; `cause` is the original failure, so a host that
+// already catches `ReadinessPollTimeout` or `KubernetesApiTimeoutError` finds
+// it there. See `backends/kubernetes/index.ts`.
+export {
+	KubernetesAcquireError,
+	type KubernetesAcquireFailureReason,
+	// The poll's own give-up, by type. It is the `cause` of a `'not-ready'`
+	// acquire refusal and is raised directly by the workspace lifecycle, which
+	// does not go through acquire.
+	ReadinessPollTimeout,
+	TERMINAL_CLAIM_REASONS,
+} from './backends/kubernetes/index.js'
+// The three ways egress verification refuses: a policy this engine cannot
+// express, no applied object at all, and an applied object that does not
+// match what this configuration translates to. Catchable by class for the
+// same reason the ingress refusal above is — an operator debugging two
+// default-on refusals in one release should not have to read messages to
+// tell them apart.
+export {
+	KubernetesEgressPolicyMismatchError,
+	KubernetesEgressPolicyNotAppliedError,
+	KubernetesUnenforceableEgressPolicyError,
+} from './backends/kubernetes/egress-policy.js'
+/** Default `KubernetesBackendConfig.streamHeartbeatMs` — see there. */
+export { DEFAULT_STREAM_HEARTBEAT_MS } from './backends/kubernetes/index.js'
+// Crash recovery and headroom for the task path: label a claim with a
+// host-supplied identity (`KubernetesBackendConfig.claimLabels`), find and
+// release a predecessor's claims by that label, and read pool headroom
+// before admitting more work. All three are additive — a host that sets no
+// `claimLabels` and calls neither function sees no change at all.
+export type {
+	KubernetesReadTaskCapacityOptions,
+	KubernetesReleaseTaskSandboxesOptions,
+	KubernetesTaskCapacity,
+} from './backends/kubernetes/index.js'
+// What a CLAIM-ONLY host is allowed to do, as data: the verbs the pool-only
+// path issues, each pinned to its call site in `backends/kubernetes/rbac.ts`.
+// `k8s/manifests/rbac-claimant.yaml` grants exactly this and a test parses
+// that file and compares it here, so an operator who has to prove a live
+// `Role` carries no more than this backend needs compares against the same
+// constant rather than against a list copied out of a page.
+export {
+	KUBERNETES_CLAIMANT_RBAC_RULES,
+	type KubernetesRbacRule,
+	type KubernetesRbacVerb,
+} from './backends/kubernetes/rbac.js'
+// The persistent workspace: a `Sandbox` that keeps a block disk across a
+// suspend, the union naming how a handle came by its object, plus the four
+// errors its lifecycle can refuse with — a template that cannot carry a disk,
+// a standing object that does not match this configuration, a call on a
+// suspended workspace, and a suspend whose pod outlived the wait. Declared in
+// `@namzu/sandbox` rather than on the SDK's `Sandbox` — see
+// `backends/kubernetes/workspace.ts`.
+export type {
+	KubernetesKillSessionOptions,
+	KubernetesWorkspace,
+	KubernetesWorkspaceAgentState,
+	KubernetesWorkspaceCancellationNotice,
+	KubernetesWorkspaceDestroyOptions,
+	KubernetesWorkspaceOptions,
+	KubernetesWorkspaceOrigin,
+	KubernetesWorkspaceStartFailurePolicy,
+	KubernetesWorkspaceSummary,
+	KubernetesWorkspaceSuspendOptions,
+	KubernetesWorkspaceSuspensionNotice,
+	KubernetesWorkspaceTransitionOptions,
+} from './backends/kubernetes/workspace.js'
+// What a workspace handle is bound to, what it says when the guest behind it
+// is replaced, and the two errors that identity produces. A host that keeps
+// per-workspace state — which processes it started, what is on the disk —
+// subscribes to `onGuestRestart` and compares `identity`; both are useless to
+// a host that cannot name their types.
+export type {
+	KubernetesGuestEvidence,
+	KubernetesGuestRestart,
+	KubernetesGuestRestartReason,
+	KubernetesWorkspaceIdentity,
+} from './backends/kubernetes/identity.js'
+export {
+	// The command's outcome is unknown AND the guest it ran in is gone. A
+	// subclass of `RemoteCancellationUnknownError`, so a host catching the
+	// base class keeps catching it; what it adds is which guest the command
+	// started on and which one is there now.
+	KubernetesWorkspaceGuestGoneError,
+	// A different Sandbox now stands under the workspace's deterministic
+	// name, or none does. The handle refuses rather than following it — the
+	// disk behind the name is not the disk it was opened on.
+	KubernetesWorkspaceReplacedError,
+} from './backends/kubernetes/identity.js'
+export {
+	KubernetesWorkspaceDiskError,
+	KubernetesWorkspaceMismatchError,
+	// A lifecycle write refused because this caller's holder epoch has been
+	// overtaken: the workspace belongs to another process now, nothing on the
+	// cluster changed and nothing about the handle changed. A host that fences
+	// its workspaces has to be able to tell this from a cluster failure, which
+	// is the whole reason the write is conditional.
+	KubernetesWorkspacePreconditionError,
+	KubernetesWorkspaceSuspendTimeoutError,
+	KubernetesWorkspaceSuspendedError,
+} from './backends/kubernetes/workspace.js'
 
 // ---------------------------------------------------------------------------
 // Backend strategy
@@ -120,6 +541,7 @@ export type SandboxBackendConfig =
 	| ContainerBackendConfig
 	| ACIStandbyPoolBackendConfig
 	| MicroVMBackendConfig
+	| KubernetesBackendConfig
 
 /**
  * Azure Container Instances Standby Pool backend. Container tier,
@@ -375,6 +797,200 @@ export interface AgentSnapshotRef {
 	readonly version: string
 }
 
+/**
+ * `microvm` tier, against a Kubernetes cluster running the agent-sandbox
+ * controller (kubernetes-sigs/agent-sandbox) with a VM-isolating
+ * RuntimeClass such as Kata.
+ *
+ * `microvm` because the tier names the strength of the boundary rather than
+ * the orchestrator behind it: a pod scheduled onto a Kata RuntimeClass runs
+ * in a hardware-virtualized guest, and the same field on the same tier is how
+ * a host says "give me a VM, I do not care who starts it".
+ *
+ * Sandboxes are claimed out of a `SandboxWarmPool` when {@link warmPoolName}
+ * names one, which is what makes the acquire sub-second; without it every
+ * create is a `Sandbox` built from {@link sandboxTemplateName}'s podTemplate
+ * and pays a full pod start. This package speaks the API server with bare
+ * `fetch` and carries no Kubernetes client dependency: credentials arrive
+ * through {@link access}, and kubeconfig parsing (context merging,
+ * exec credential plugins) stays in the host that owns it.
+ */
+export interface KubernetesBackendConfig {
+	readonly tier: 'microvm'
+	readonly service: 'kubernetes'
+	/** Namespace the claims, sandboxes and their pods live in. */
+	readonly namespace: string
+	/**
+	 * How to reach the API server. `{ inCluster: true }` reads the projected
+	 * ServiceAccount volume and the kubelet's `KUBERNETES_SERVICE_*` env, which
+	 * is the production path; otherwise the host supplies the server URL, an
+	 * optional cluster CA and a `getToken()` callback — the same boundary this
+	 * package already draws for ACI's `getArmToken` and Firecracker's
+	 * `getToken`.
+	 */
+	readonly access: KubernetesClusterAccess
+	/**
+	 * `SandboxTemplate` whose `podTemplate` a POOL-LESS create copies into the
+	 * `Sandbox` it posts. Required because `Sandbox.spec` has no `templateRef`
+	 * — only a `SandboxWarmPool` references a template — so the pod spec has to
+	 * be carried across by the client. The warm path does not read it; the
+	 * pool's own `sandboxTemplateRef` decides there.
+	 */
+	readonly sandboxTemplateName: string
+	/**
+	 * `SandboxWarmPool` to claim from. Absent → every create posts a `Sandbox`
+	 * directly, because `SandboxClaim.spec.warmPoolRef` is a required field and
+	 * a pool-less claim does not exist in the API.
+	 */
+	readonly warmPoolName?: string
+	/** TCP port the in-pod guest agent listens on. Default 1024. */
+	readonly agentPort?: number
+	/**
+	 * Which of a sandbox's two addresses the transport dials.
+	 *
+	 * `'service'` (default) is the Sandbox's `status.serviceFQDN`, which
+	 * outlives the pod and is re-resolved on every dial — and which ONLY the
+	 * cluster's own DNS answers. A host running outside the cluster fails
+	 * every call at name resolution, readiness included, so it reads as a
+	 * sandbox that never came up.
+	 *
+	 * `'pod-ip'` dials the bound pod's IP, read from the same `GET` that
+	 * reads its bind token. For a host outside the cluster with a route to
+	 * the pod network. It needs that route and a `NetworkPolicy` admitting
+	 * the host's address range on {@link agentPort}; the IP dies with its
+	 * pod, which the backend covers by re-reading it on every resume and once
+	 * after a connect failure. Nothing else changes: same bind token, same
+	 * privilege probe, same egress verification.
+	 */
+	readonly agentAddress?: KubernetesAgentAddressMode
+	/** Delay between readiness polls. Default 50ms. */
+	readonly readyPollIntervalMs?: number
+	/** Total deadline from create to an addressed, Ready sandbox. Default 60000ms. */
+	readonly readyTimeoutMs?: number
+	/**
+	 * Wall-clock lifetime written into every object this backend creates, so a
+	 * host that dies mid-run costs the cluster one expiry rather than a leaked
+	 * sandbox. Default 3600.
+	 */
+	readonly claimTtlSeconds?: number
+	/**
+	 * Every lease-renewal failure that is not "the object is already gone".
+	 *
+	 * The handle renews its own `shutdownTime` every half-TTL for as long as
+	 * it is alive, so a run that outlives `claimTtlSeconds` keeps its pod.
+	 * A failed renewal is retried on a short capped backoff — starting at one
+	 * second, not the next half-TTL tick — so a single API blip near a
+	 * scheduled renewal gets several more chances before anything expires;
+	 * this callback is where the diagnostic goes, because `@namzu/sandbox`
+	 * owns no logger and reads none from module scope. Setting it changes
+	 * nothing about behaviour.
+	 */
+	readonly onLeaseRenewalError?: (error: unknown) => void
+	/**
+	 * RuntimeClass for a POOL-LESS create. Refused together with
+	 * {@link warmPoolName}: a pooled sandbox is already running under the
+	 * RuntimeClass its `SandboxTemplate` named, and a claim cannot change it —
+	 * so accepting it there would quietly drop the choice of VM boundary.
+	 */
+	readonly runtimeClassName?: string
+	/**
+	 * Egress policy this backend expects an operator to have applied as a
+	 * `NetworkPolicy` (or, under `engine: 'cilium'`, a `CiliumNetworkPolicy`)
+	 * scoped to every Sandbox this backend produces. Unset means this backend
+	 * neither computes nor checks one — the cluster's default posture (the
+	 * `SandboxTemplate`'s own managed `NetworkPolicy`) is all that applies.
+	 *
+	 * This is a CONFIG-level, whole-backend policy, not a per-`create()` one:
+	 * `SandboxBackendOptions.egress` is still refused by name (see
+	 * `backends/kubernetes/index.ts`'s `assertEnforceable`), because the
+	 * enforcement point is one object attached to the template and cannot be
+	 * rewritten per running sandbox. `static` and `resolver` — hostname
+	 * allowlists — throw a named error at construction unless `engine` is
+	 * `'cilium'`: core `NetworkPolicy` has no FQDN concept at all.
+	 *
+	 * `policy` also takes two kinds that exist only here, because only a
+	 * `NetworkPolicy` can express them: `{ kind: 'no-network' }` (nothing
+	 * leaves the pod, the cluster resolver included — which `'deny-all'` never
+	 * meant, since it allows DNS and a cluster resolver forwards outside
+	 * names) and `{ kind: 'public-internet', exceptCidrs? }` (the internet,
+	 * minus the private ranges, carrier-grade NAT, link-local and one cloud
+	 * platform endpoint). `'deny-all'` and `'allow-all'` emit exactly the
+	 * manifests they always have.
+	 *
+	 * **Setting this now checks the UNION.** Since every policy selecting a
+	 * pod is unioned by the API server, the check reads the named object AND
+	 * enumerates the namespace's policies, refusing when any of them lets out
+	 * more than `policy` does. `verify: 'named-object-only'` restores the
+	 * single-object check exactly. See
+	 * `docs/sdk/kubernetes-sandbox.md`'s egress section.
+	 */
+	readonly egress?: KubernetesEgressConfig
+	/**
+	 * Whether this backend proves, before creating a sandbox, that an applied
+	 * policy actually closes {@link agentPort} on the pod it is about to hand
+	 * back — and against which policy resources.
+	 *
+	 * **Unset means verify.** This is the one field here whose absent value is
+	 * the strict one, because the deployment that needs the check is the one
+	 * that would never have switched it on: the guest agent's own source calls
+	 * the network rule in front of its port the boundary, and until this field
+	 * existed nothing confirmed there was one.
+	 *
+	 * `{ engine: 'cilium' }` also enumerates that CNI's own policy CRD;
+	 * `engine` otherwise defaults to `egress?.engine ?? 'core'`.
+	 *
+	 * `'unverified'` reads no policy and issues no request. It is the
+	 * supported answer for a deployment whose boundary a namespaced Role
+	 * cannot see — a cluster-scoped policy, a service mesh, a cloud security
+	 * group — and it is a claim the deployment makes on purpose rather than a
+	 * default it inherits. See `docs/sdk/kubernetes-sandbox.md`'s ingress
+	 * section.
+	 */
+	readonly ingress?: KubernetesIngressConfig
+	/**
+	 * How long a single Kubernetes API request may take, end to end —
+	 * resolving the token, connecting, and reading the reply. Default
+	 * `30000`; minimum `1000`; there is no value that turns it off.
+	 *
+	 * The caller's `signal` is optional everywhere and several of this
+	 * backend's requests are SHARED flights that run under whichever caller
+	 * arrived first, so a signal-less `destroy()` against an API server that
+	 * accepted a request and never answered used to pin every later caller
+	 * joined to it. Expiry rejects with `KubernetesApiTimeoutError`, which
+	 * says nothing about whether the request was applied — the paths that
+	 * send one already cope with not knowing.
+	 */
+	readonly apiRequestTimeoutMs?: number
+	/**
+	 * Interval of the liveness heartbeat `openTerminal` and
+	 * `openTcpConnection` streams negotiate with the guest. Default `15000`;
+	 * `0` sends none, which is exactly how every release before this one
+	 * behaved.
+	 *
+	 * A quiet shell is healthy, so nothing replaced the read-idle timer the
+	 * transport clears once a stream is ready: a partition that delivered no
+	 * FIN and no RST left `exited`/`closed` unresolved on the host and the
+	 * shell's process group alive in the guest. Three missed intervals end
+	 * the stream on both sides. It is negotiated per stream — the guest
+	 * echoes the interval in its `ready` event and sends nothing new unless
+	 * it did — so an older guest image behaves exactly as it does today.
+	 */
+	readonly streamHeartbeatMs?: number
+	/**
+	 * Extra labels written onto every `SandboxClaim` this backend POSTs —
+	 * `metadata.labels` only, never the pod's own labels. Unset means no
+	 * labels beyond what the controller itself writes, and every claim body
+	 * is byte-for-byte what it was before this option existed.
+	 *
+	 * The intended use is a host-instance identity, so a restarted host can
+	 * find and {@link releaseKubernetesTaskSandboxes} a crashed predecessor's
+	 * claims well before `claimTtlSeconds` reaps them on its own — see
+	 * {@link readKubernetesTaskCapacity} for reading pool headroom
+	 * alongside it.
+	 */
+	readonly claimLabels?: Record<string, string>
+}
+
 /**
  * Egress allowlist resolution. Host-supplied policy decides whether
  * an outbound request is allowed before the proxy opens a socket.
@@ -505,9 +1121,16 @@ export type SandboxProviderConfig =
 			readonly backend: ContainerBackendConfig
 			readonly layout: ContainerSandboxLayout
 	  })
+	| (SandboxProviderConfigBase & {
+			readonly backend: ACIStandbyPoolBackendConfig
+			readonly layout: ContainerSandboxLayout
+	  })
 	| (SandboxProviderConfigBase & {
 			readonly backend: MicroVMBackendConfig
 	  })
+	| (SandboxProviderConfigBase & {
+			readonly backend: KubernetesBackendConfig
+	  })
 
 interface SandboxProviderConfigBase {
 	readonly defaultEgress?: EgressPolicy
@@ -580,6 +1203,40 @@ export function createSandboxProvider(config: SandboxProviderConfig): SandboxPro
 
 function pickBackend(config: SandboxProviderConfig): SandboxBackend {
 	const backend = config.backend
+	// Checked ahead of the `docker` default below: `ACIStandbyPoolBackendConfig`
+	// is a real arm of `SandboxProviderConfig` (see the discriminated union
+	// above), discriminated from `ContainerBackendConfig` by `runtime`. A
+	// plain equality check here narrows `backend` to the ACI shape with no
+	// cast, and — because this branch always returns — narrows it AWAY for
+	// every check below, so the `docker` branch's `backend.runtime ?? 'docker'`
+	// still sees only `ContainerBackendConfig`.
+	if (backend.tier === 'container' && backend.runtime === 'aci-standby-pool') {
+		const layout = (config as Extract<SandboxProviderConfig, { layout: ContainerSandboxLayout }>)
+			.layout
+		const resolved = resolveLayout(layout)
+		return buildAciStandbyPoolBackend({
+			subscriptionId: backend.subscriptionId,
+			resourceGroup: backend.resourceGroup,
+			location: backend.location,
+			standbyPoolResourceId: backend.standbyPoolResourceId,
+			containerGroupProfileResourceId: backend.containerGroupProfileResourceId,
+			...(backend.containerGroupProfileRevision !== undefined
+				? { containerGroupProfileRevision: backend.containerGroupProfileRevision }
+				: {}),
+			layout: resolved,
+			getArmToken: backend.getArmToken,
+			...(backend.subnetId !== undefined ? { subnetId: backend.subnetId } : {}),
+			...(backend.readyPollIntervalMs !== undefined
+				? { readyPollIntervalMs: backend.readyPollIntervalMs }
+				: {}),
+			...(backend.readyTimeoutMs !== undefined ? { readyTimeoutMs: backend.readyTimeoutMs } : {}),
+			...(backend.workerPort !== undefined ? { workerPort: backend.workerPort } : {}),
+			...(backend.armApiVersion !== undefined ? { armApiVersion: backend.armApiVersion } : {}),
+			...(backend.containerNamePrefix !== undefined
+				? { containerNamePrefix: backend.containerNamePrefix }
+				: {}),
+		})
+	}
 	if (backend.tier === 'container' && (backend.runtime ?? 'docker') === 'docker') {
 		// `layout` is required for container-tier backends by the
 		// discriminated union — narrow safely without a non-null
@@ -605,41 +1262,6 @@ function pickBackend(config: SandboxProviderConfig): SandboxBackend {
 			...(backend.labels !== undefined ? { labels: backend.labels } : {}),
 		})
 	}
-	if (
-		backend.tier === 'container' &&
-		(backend as unknown as { runtime?: string }).runtime === 'aci-standby-pool'
-	) {
-		const aciBackend = backend as unknown as ACIStandbyPoolBackendConfig
-		const layout = (config as Extract<SandboxProviderConfig, { layout: ContainerSandboxLayout }>)
-			.layout
-		const resolved = resolveLayout(layout)
-		return buildAciStandbyPoolBackend({
-			subscriptionId: aciBackend.subscriptionId,
-			resourceGroup: aciBackend.resourceGroup,
-			location: aciBackend.location,
-			standbyPoolResourceId: aciBackend.standbyPoolResourceId,
-			containerGroupProfileResourceId: aciBackend.containerGroupProfileResourceId,
-			...(aciBackend.containerGroupProfileRevision !== undefined
-				? { containerGroupProfileRevision: aciBackend.containerGroupProfileRevision }
-				: {}),
-			layout: resolved,
-			getArmToken: aciBackend.getArmToken,
-			...(aciBackend.subnetId !== undefined ? { subnetId: aciBackend.subnetId } : {}),
-			...(aciBackend.readyPollIntervalMs !== undefined
-				? { readyPollIntervalMs: aciBackend.readyPollIntervalMs }
-				: {}),
-			...(aciBackend.readyTimeoutMs !== undefined
-				? { readyTimeoutMs: aciBackend.readyTimeoutMs }
-				: {}),
-			...(aciBackend.workerPort !== undefined ? { workerPort: aciBackend.workerPort } : {}),
-			...(aciBackend.armApiVersion !== undefined
-				? { armApiVersion: aciBackend.armApiVersion }
-				: {}),
-			...(aciBackend.containerNamePrefix !== undefined
-				? { containerNamePrefix: aciBackend.containerNamePrefix }
-				: {}),
-		})
-	}
 	if (backend.tier === 'container' && backend.runtime === 'runsc') {
 		const layout = (config as Extract<SandboxProviderConfig, { layout: ContainerSandboxLayout }>)
 			.layout
@@ -688,9 +1310,190 @@ function pickBackend(config: SandboxProviderConfig): SandboxBackend {
 				: {}),
 		})
 	}
+	// `microvm:kubernetes` — agent-sandbox on any cluster. Reached through a
+	// real arm of `SandboxProviderConfig`, so `backend` narrows here and every
+	// field below is read off the narrowed type, same as the ACI and docker
+	// branches above.
+	if (backend.tier === 'microvm' && backend.service === 'kubernetes') {
+		return buildKubernetesBackend(kubernetesInternalConfig(backend))
+	}
 	throw new SandboxBackendNotImplementedError(describeBackend(backend))
 }
 
+/**
+ * Public config → the kubernetes backend's own. One function so the two
+ * entry points that build against a cluster — {@link createSandboxProvider}
+ * for task sandboxes and {@link createKubernetesWorkspace} for persistent
+ * ones — cannot drift apart on which fields they forward.
+ */
+function kubernetesInternalConfig(
+	backend: KubernetesBackendConfig,
+): KubernetesBackendInternalConfig {
+	return {
+		access: backend.access,
+		namespace: backend.namespace,
+		sandboxTemplateName: backend.sandboxTemplateName,
+		...(backend.warmPoolName !== undefined ? { warmPoolName: backend.warmPoolName } : {}),
+		...(backend.agentPort !== undefined ? { agentPort: backend.agentPort } : {}),
+		...(backend.agentAddress !== undefined ? { agentAddress: backend.agentAddress } : {}),
+		...(backend.readyPollIntervalMs !== undefined
+			? { readyPollIntervalMs: backend.readyPollIntervalMs }
+			: {}),
+		...(backend.readyTimeoutMs !== undefined ? { readyTimeoutMs: backend.readyTimeoutMs } : {}),
+		...(backend.claimTtlSeconds !== undefined ? { claimTtlSeconds: backend.claimTtlSeconds } : {}),
+		...(backend.onLeaseRenewalError !== undefined
+			? { onLeaseRenewalError: backend.onLeaseRenewalError }
+			: {}),
+		...(backend.runtimeClassName !== undefined
+			? { runtimeClassName: backend.runtimeClassName }
+			: {}),
+		...(backend.egress !== undefined ? { egress: backend.egress } : {}),
+		...(backend.ingress !== undefined ? { ingress: backend.ingress } : {}),
+		...(backend.apiRequestTimeoutMs !== undefined
+			? { apiRequestTimeoutMs: backend.apiRequestTimeoutMs }
+			: {}),
+		...(backend.streamHeartbeatMs !== undefined
+			? { streamHeartbeatMs: backend.streamHeartbeatMs }
+			: {}),
+		...(backend.claimLabels !== undefined ? { claimLabels: backend.claimLabels } : {}),
+	}
+}
+
+/**
+ * Create — or reattach to — a persistent workspace on a cluster running the
+ * agent-sandbox controller.
+ *
+ * A workspace is the other half of this backend, and deliberately not
+ * something {@link createSandboxProvider} can hand out: a `SandboxProvider`
+ * promises an EPHEMERAL sandbox per run (`workspaceModes: ['ephemeral']`),
+ * while this returns one object with a name the caller chose, a disk that
+ * survives a suspend, and a lifetime nothing reaps on a timer. It is its own
+ * verb so that the difference is visible at the call site.
+ *
+ * `config.warmPoolName` is ignored here: a workspace is always a `Sandbox`
+ * POSTed directly, because a claim cannot carry the immutable disk spec.
+ * `config.sandboxTemplateName` is the default template, and
+ * `options.sandboxTemplateName` overrides it — a deployment normally has a
+ * task template with no disk and a workspace template with a block one.
+ *
+ * Resolves once the workspace is Ready, addressed and has proved it is
+ * deprivileged, exactly as `provider.create()` does for a task sandbox.
+ */
+export async function createKubernetesWorkspace(
+	config: KubernetesBackendConfig,
+	options: KubernetesWorkspaceOptions,
+): Promise<KubernetesWorkspace> {
+	return await buildKubernetesWorkspace(kubernetesInternalConfig(config), options)
+}
+
+/**
+ * Every workspace this backend owns in the namespace, read off the objects
+ * and waking none of them.
+ *
+ * The inventory {@link createKubernetesWorkspace} cannot give you: it adopts
+ * AND resumes, so taking stock through it would start a pod for every
+ * suspended workspace it looked at. This issues one GET of the sandboxes
+ * collection and sends no PATCH and no DELETE — a suspended workspace is
+ * still suspended afterwards.
+ *
+ * Needs `list` on `sandboxes` in the namespace, which is the one RBAC verb
+ * the task path did not already require.
+ */
+export async function listKubernetesWorkspaces(
+	config: KubernetesBackendConfig,
+	options?: KubernetesWorkspaceTransitionOptions,
+): Promise<readonly KubernetesWorkspaceSummary[]> {
+	return await listWorkspacesOnCluster(kubernetesInternalConfig(config), options)
+}
+
+/**
+ * Delete a workspace by id — the Sandbox, and with it the Pod, the Service
+ * and the PVC — without adopting or resuming it first.
+ *
+ * Exactly what `destroy({ deleteDisk: true })` does to the cluster, with the
+ * same guarantees: an object already gone counts as deleted, and a DELETE
+ * that fails rejects and stays retryable. The files are gone and nothing
+ * brings them back.
+ *
+ * It is the retention verb. Removing a month-old suspended workspace through
+ * a handle meant starting its pod and probing it purely to tell it to go
+ * away; the name is deterministic, so the object never needed opening.
+ */
+export async function deleteKubernetesWorkspace(
+	config: KubernetesBackendConfig,
+	workspaceId: string,
+	options?: KubernetesWorkspaceTransitionOptions,
+): Promise<void> {
+	await deleteWorkspaceOnCluster(kubernetesInternalConfig(config), workspaceId, options)
+}
+
+/**
+ * Suspend a workspace by id: send the `operatingMode: Suspended` patch and
+ * wait for the pod to actually stop, without adopting the workspace.
+ *
+ * Resolves only once the pod is gone or in a terminal phase — a suspend is a
+ * promise that the disk is quiesced, and the patch being accepted says only
+ * that the controller has been asked. A pod that outlives `readyTimeoutMs`
+ * rejects with `KubernetesWorkspaceSuspendTimeoutError`, leaving the object
+ * as the patch left it.
+ *
+ * A handle another process is holding is not told. It finds out on its next
+ * call — which fails at the transport and is re-read into a
+ * `KubernetesWorkspaceSuspendedError` — or when that process calls
+ * `refresh()`.
+ *
+ * It takes the suspend options shape and REFUSES `quiesce` rather than
+ * accepting the flag and dropping it: this verb never dials the agent, so
+ * there is no connection here on which anything could be stopped. Quiescing
+ * needs a handle — `createKubernetesWorkspace()`, then
+ * `suspend({ quiesce: true })`.
+ */
+export async function suspendKubernetesWorkspace(
+	config: KubernetesBackendConfig,
+	workspaceId: string,
+	options?: KubernetesWorkspaceSuspendOptions,
+): Promise<void> {
+	await suspendWorkspaceOnCluster(kubernetesInternalConfig(config), workspaceId, options)
+}
+
+/**
+ * Recover a crashed host's task-path claims: LIST every `SandboxClaim`
+ * carrying `options.labelSelector`, `DELETE` each, and report what was
+ * removed.
+ *
+ * Deletes claims only — the controller's own ownerReferences take the bound
+ * Sandbox, its Pod and its Service down behind each one; nothing here reads
+ * or touches those objects directly. `labelSelector` is REQUIRED and refused
+ * before any request goes out if it is empty: falling back to matching every
+ * claim would delete a live fleet's work.
+ *
+ * Pairs with `config.claimLabels`: a host stamps its own identity onto every
+ * claim it creates, and a restarted instance passes that same selector here
+ * to reclaim its predecessor's warm-pool capacity well before
+ * `claimTtlSeconds` would reap it on its own.
+ */
+export async function releaseKubernetesTaskSandboxes(
+	config: KubernetesBackendConfig,
+	options: KubernetesReleaseTaskSandboxesOptions,
+): Promise<{ readonly deleted: number; readonly names: readonly string[] }> {
+	return await releaseTaskSandboxesOnCluster(kubernetesInternalConfig(config), options)
+}
+
+/**
+ * Read task-pool headroom before admitting more work: three GETs
+ * (`SandboxWarmPool`, the claims collection, the pods collection), no
+ * writes.
+ *
+ * Requires `config.warmPoolName` — a pool-less backend (every create is a
+ * direct Sandbox) has no `SandboxWarmPool` to report on.
+ */
+export async function readKubernetesTaskCapacity(
+	config: KubernetesBackendConfig,
+	options?: KubernetesReadTaskCapacityOptions,
+): Promise<KubernetesTaskCapacity> {
+	return await readTaskCapacityOnCluster(kubernetesInternalConfig(config), options)
+}
+
 /**
  * Human-readable backend label for error messages. Returns the
  * tier plus the concrete service / runtime when present, e.g.