Secure, Fast, and Extensible Sandbox runtime for AI agents.
docs(release): draft 1.2.0 umbrella release notes
高然5ed820eeb17c
diff --git a/docs/releases/1.2.0.md b/docs/releases/1.2.0.mdnew file mode 100644index 000000000..516a290a9--- /dev/null+++ b/docs/releases/1.2.0.md@@ -0,0 +1,212 @@+Stable cut of the `1.2.0` line, carrying everything merged since `release-1.1.1` through two release candidates plus a post-rc hardening delta. Images shipped with the rcs; SDK/CLI/server packages publish at `1.2.0`. Everyone on `1.1.x` should upgrade. Baseline for every section below: `release-1.1.1`.++## Highlights++- Auto-pause and wake-on-access for fast sandboxes (OSEP-0024) lands end to end: the ingress records activity and parks requests to paused sandboxes until the restore completes, the server runs an idle sweeper behind an opt-in `lifecycle.idlePolicy` create field, and all five SDKs get the wake-retry contract — off by default, additive only ([#2156](https://github.com/opensandbox-group/OpenSandbox/pull/2156) [#2180](https://github.com/opensandbox-group/OpenSandbox/pull/2180) [#2192](https://github.com/opensandbox-group/OpenSandbox/pull/2192) [#2198](https://github.com/opensandbox-group/OpenSandbox/pull/2198) [#2218](https://github.com/opensandbox-group/OpenSandbox/pull/2218))+- Credential Vault (OSEP-0022) lands end to end for fast sandboxes: the egress sidecar holds the vault with durable per-subject persistence and sealed pause/resume transfer, the server exposes the user-reachable vault API with credential values never appearing on any public read, and the MITM CA is pinned per pool so an egress restart no longer rotates the trust anchor under live sandboxes — plus port-scoped egress rules end to end in the classic profile ([#2249](https://github.com/opensandbox-group/OpenSandbox/pull/2249) [#2252](https://github.com/opensandbox-group/OpenSandbox/pull/2252) [#2255](https://github.com/opensandbox-group/OpenSandbox/pull/2255) [#2263](https://github.com/opensandbox-group/OpenSandbox/pull/2263) [#2251](https://github.com/opensandbox-group/OpenSandbox/pull/2251) [#2212](https://github.com/opensandbox-group/OpenSandbox/pull/2212))+- Fast Sandbox snapshots and template builds can publish to and boot from OCI registries (OverlayBD OCI lifecycle), and a reliability campaign removes whole-call timeouts from SDK file transfers in all five languages, makes execd report sandbox-scoped CPU/memory and OOM kills, and fixes a long list of Docker-backend correctness and PTY/session output issues ([#2338](https://github.com/opensandbox-group/OpenSandbox/pull/2338) [#2165](https://github.com/opensandbox-group/OpenSandbox/pull/2165) [#2200](https://github.com/opensandbox-group/OpenSandbox/pull/2200) [#2191](https://github.com/opensandbox-group/OpenSandbox/pull/2191))++## Server++- Implement the server side of OSEP-0024 auto-pause for fast sandboxes: the `lifecycle.idlePolicy` create field (`idleTimeoutSeconds` 30–86400, `onIdle: pause`, `wakeOnAccess`, optional `activeProbe`) persists as a reserved Sandbox CR annotation; an idle sweeper enumerates opted-in fsb sandboxes, checks activity in Redis, takes a per-sandbox pause lock, and issues an idempotent FastPath `PauseSandbox`; a declared `activeProbe` runs through the ingress gateway, and an `OpenSandbox-Skip-Activity` sentinel suppresses one observation and is stripped on both gateway and proxy hops. Config moves under `[automation.idle_pause]`, and `redis.dsn` is validated at load when the sweeper is enabled ([#2192](https://github.com/opensandbox-group/OpenSandbox/pull/2192) [#2181](https://github.com/opensandbox-group/OpenSandbox/pull/2181) [#2215](https://github.com/opensandbox-group/OpenSandbox/pull/2215))+- Implement the Credential Vault API (OSEP-0022, fast-sandbox profile): `POST|GET|PATCH|DELETE /v1/sandboxes/{id}/credential-vault` pushes complete vault revisions over the FastPath handler relay and treats the relay response as the synchronous egress-validated ack — the CRD never carries vault material and every public read is sanitized server-side; PATCH composes in memory with `expectedRevision` as the cross-replica backstop, non-fsb backends proxy the sidecar's `/credential-vault` surface, and the fsb `credentialProxy` create-time rejection is lifted ([#2263](https://github.com/opensandbox-group/OpenSandbox/pull/2263))+- Bake the pinned MITM CA into server-created SandboxTemplates (OSEP-0022): new `[kubernetes] template_mitm_ca_secret` config (default off) emits `spec.egressMitmCertificate` — the certificate entry only, never the private key — on every template; the Secret must exist in each template namespace (ops-runbook distribution), and a missed copy fails the build observably ([#2288](https://github.com/opensandbox-group/OpenSandbox/pull/2288))+- Add `lifecycle.renewalPolicy` (OSEP-0009): the renew-on-access opt-in moves from the opaque `extensions["access.renew.extend.seconds"]` key to a structured `renewalPolicy.extendSeconds` (300–86400); the legacy key is deprecated (supported throughout 1.x, removed in 2.0), and fast sandbox rejects it with 400 rather than silently accepting a no-op ([#2296](https://github.com/opensandbox-group/OpenSandbox/pull/2296))+- Implement the diagnostics context endpoint (spec in [#2236](https://github.com/opensandbox-group/OpenSandbox/pull/2236)): `GET /v1/sandboxes/{sandboxId}/diagnostics/context` returns the sandbox ID, lifecycle state, backend type, and backend-defined identifiers for Docker, Kubernetes, and Fast Sandbox without connecting to execd — Kubernetes context stays available before a Pod is allocated; extension backends that don't implement it return 501 ([#2292](https://github.com/opensandbox-group/OpenSandbox/pull/2292))+- Forward the still-encoded path through the sandbox proxy: Starlette bound the `{full_path:path}` route from the percent-decoded path, so a decoded `?` started a query, `%2F` became a separator, and `%2E%2E` segments were resolved — closing a prefix-escape on Docker host-mapped endpoints; the proxy now takes the client's still-encoded tail from the raw path (validating it decodes to the routed path) and reads the query from the raw query string, so backends receive request targets byte-for-byte, matching the ingress gateway ([#2228](https://github.com/opensandbox-group/OpenSandbox/pull/2228))+- Keep blocking Docker calls off the event loop: proxy endpoint lookups, network-existence validation, and per-PVC volume inspect/create ran synchronously inside async handlers, so a slow Docker daemon (e.g. during a large pull) froze every other request including proxy traffic; they now run on worker threads with tenant context preserved, and volume-validation failures still clean up auto-created volumes ([#2268](https://github.com/opensandbox-group/OpenSandbox/pull/2268) [#2366](https://github.com/opensandbox-group/OpenSandbox/pull/2366))+- Stop reporting image-inherited labels as sandbox state on Docker: metadata reads fell back to every non-reserved container label — including labels merged in from the image — and restored containers inherited reserved labels such as `expires-at`, host ports, and the egress token; in the worst case a restored TTL sandbox was deleted as already expired after a server restart. Creates now record the request's metadata keys in a reserved label and read back only those keys, and reserved labels present on the image but not set by the sandbox are blanked before container start ([#2363](https://github.com/opensandbox-group/OpenSandbox/pull/2363) [#2269](https://github.com/opensandbox-group/OpenSandbox/pull/2269))+- Reject gVisor snapshots that would silently drop writes: `docker commit` under gVisor's default `--overlay2=root:self` can report `READY` while restoring none of the sandbox's writes; snapshot preflight now refuses gVisor unless the effective args include `--overlay2=none`, and create fails closed when the filesystem diff is filestore-only ([#2241](https://github.com/opensandbox-group/OpenSandbox/pull/2241))+- Keep an fsb snapshot whose create reply was lost: a `UNAVAILABLE`/`DEADLINE_EXCEEDED` from FastPath after the request was durably accepted returned 500 without writing a row, stranding the SandboxSnapshot and its published artifacts with no record; the create now probes for the snapshot before failing and reports it as submitted when FastPath persisted it ([#2361](https://github.com/opensandbox-group/OpenSandbox/pull/2361))+- Fix the remaining Docker-backend rough edges: BatchSandbox expiry reports `Terminated`/`SANDBOX_EXPIRED` instead of `Running` past `spec.expireTime` ([#2238](https://github.com/opensandbox-group/OpenSandbox/pull/2238)); concurrent lifecycle conflicts map to 404/409 instead of 500 ([#2387](https://github.com/opensandbox-group/OpenSandbox/pull/2387)); concurrent metadata patches no longer race into 500s or dropped keys ([#2267](https://github.com/opensandbox-group/OpenSandbox/pull/2267) [#2281](https://github.com/opensandbox-group/OpenSandbox/pull/2281)); `createdAt` stays stable across reads and pause/resume transitions are recorded ([#2405](https://github.com/opensandbox-group/OpenSandbox/pull/2405)); network policy actions are validated and unknown fields return 422 ([#2383](https://github.com/opensandbox-group/OpenSandbox/pull/2383) [#2385](https://github.com/opensandbox-group/OpenSandbox/pull/2385)); the sandbox image is read from the container config so a `docker rmi -f`'d image no longer 500s `GET /sandboxes` ([#2353](https://github.com/opensandbox-group/OpenSandbox/pull/2353)); template reads trust the database projection instead of syncing the CR on every create-gate check ([#2326](https://github.com/opensandbox-group/OpenSandbox/pull/2326)); the renew cooldown applies to every renew source when the Redis consumer is enabled ([#2276](https://github.com/opensandbox-group/OpenSandbox/pull/2276) [#2279](https://github.com/opensandbox-group/OpenSandbox/pull/2279)); BatchSandbox pods default to `restartPolicy: Never` so a kubelet restart can no longer wipe the writable layer while reporting `Succeed` ([#2128](https://github.com/opensandbox-group/OpenSandbox/pull/2128)); podman's `pasta`/`slirp4netns`/`none` network modes pass through (with `networkPolicy` rejected, since there is no bridge to attach to) ([#2203](https://github.com/opensandbox-group/OpenSandbox/pull/2203)); Docker timestamps with unusual fractional seconds no longer silently report the current time ([#2220](https://github.com/opensandbox-group/OpenSandbox/pull/2220)); and the execd cache container honors `[docker]` security profiles and `secure_runtime` ([#2254](https://github.com/opensandbox-group/OpenSandbox/pull/2254))++## SDKs++Code changes below ride the `1.2.0` packages.++- Add the OSEP-0024 SDK contract to all five languages: a typed `lifecycle.idlePolicy` create field with client-side fail-fast validation, plus the wake-retry contract — on a `503` carrying the gateway-owned `OpenSandbox-Wake: expired` marker (its presence proves the request was parked and never forwarded, making any-method retry safe), the SDK resends after `Retry-After` under a bounded budget (default 5 attempts / 60 s, per-client knobs) and exhaustion raises a typed wake-timeout exception; SSE/streaming transports bypass wake retry ([#2198](https://github.com/opensandbox-group/OpenSandbox/pull/2198) [#2218](https://github.com/opensandbox-group/OpenSandbox/pull/2218))+- Add the Credential Vault client contract to all five SDKs (OSEP-0022): template-backed sandboxes route vault calls through the server on the same template-origin signal as network policy, while sidecar-direct adapters stay untouched ([#2263](https://github.com/opensandbox-group/OpenSandbox/pull/2263))+- Stop capping file uploads and downloads at the request timeout (30 s default) in all five SDKs — the whole-call timeout covered sending the body and reading the response, so any large or slow transfer failed mid-flight even while healthy; transfers now run on a dedicated client with no whole-call deadline that still bounds the wait for response headers, so a stalled transfer still fails instead of hanging ([#2165](https://github.com/opensandbox-group/OpenSandbox/pull/2165) [#2186](https://github.com/opensandbox-group/OpenSandbox/pull/2186) [#2196](https://github.com/opensandbox-group/OpenSandbox/pull/2196) [#2206](https://github.com/opensandbox-group/OpenSandbox/pull/2206))+- Implement diagnostics across the SDK surface (with [#2292](https://github.com/opensandbox-group/OpenSandbox/pull/2292)): `context` is exposed through both the manager and sandbox facades in all five languages, and JavaScript, Go, and C# gain public logs/events APIs matching the existing Python/JVM surface ([#2292](https://github.com/opensandbox-group/OpenSandbox/pull/2292))+- Add `lifecycle.renewalPolicy` to all five SDKs (OSEP-0009): a typed create field with client-side fail-fast validation (`extendSeconds` 300–86400), replacing the opaque extensions key ([#2296](https://github.com/opensandbox-group/OpenSandbox/pull/2296))+- Support port-scoped egress rules in all five SDKs: `NetworkRule.ports` (TCP 1–65535, at most 256 per rule, `target` now optional) with client-side validation mirroring the server (range, duplicates, cap, domain+ports rejected); JavaScript encodes the target-or-ports invariant as a union type ([#2212](https://github.com/opensandbox-group/OpenSandbox/pull/2212))+- Surface the authoritative `execution_complete.exit_code` in Go and Kotlin, preferring it over the previous `evalue`/inferred-0 fallbacks while staying compatible with older servers ([#2330](https://github.com/opensandbox-group/OpenSandbox/pull/2330)); honor an explicitly supplied `OPEN-SANDBOX-API-KEY` header over the configured key regardless of header-name casing in JavaScript, C#, and Kotlin ([#2348](https://github.com/opensandbox-group/OpenSandbox/pull/2348) [#2372](https://github.com/opensandbox-group/OpenSandbox/pull/2372) [#2375](https://github.com/opensandbox-group/OpenSandbox/pull/2375)); suppress `sandbox.create` metrics for client-pool warmup creates in Go, Python, and JavaScript ([#2199](https://github.com/opensandbox-group/OpenSandbox/pull/2199))++### Python++- Normalize the connection domain: a trailing slash or `/v1` in `domain` / `OPEN_SANDBOX_DOMAIN` produced `//v1/...` URLs that the server 404'd — the same variable worked in every other SDK; Python now strips both ([#2347](https://github.com/opensandbox-group/OpenSandbox/pull/2347))+- Reuse SSL contexts across owned transports: CA certificates were reloaded on every call, blocking the event loop under asyncio concurrency — measured create P50 improves ~18–28% under concurrency ([#2360](https://github.com/opensandbox-group/OpenSandbox/pull/2360))+- Preserve the first SSE event after a UTF-8 BOM (including one split across network chunks) ([#2226](https://github.com/opensandbox-group/OpenSandbox/pull/2226)); close wake-timeout response bodies on cancellation ([#2371](https://github.com/opensandbox-group/OpenSandbox/pull/2371)); raise the shared structured error from Code Interpreter `codes.run` failures instead of a hand-built exception that lost `retry_after` ([#2364](https://github.com/opensandbox-group/OpenSandbox/pull/2364)); stop propagating a cancelled endpoint fetch to concurrent waiters ([#2277](https://github.com/opensandbox-group/OpenSandbox/pull/2277)); forward `credential_proxy` through sandbox pools, which silently dropped it before ([#2283](https://github.com/opensandbox-group/OpenSandbox/pull/2283)); stop reporting failed file replacements as successful ([#2222](https://github.com/opensandbox-group/OpenSandbox/pull/2222)); clean up cancelled async pool startup instead of getting stuck in `STARTING` ([#2209](https://github.com/opensandbox-group/OpenSandbox/pull/2209)); regenerate the lifecycle client to drop stale hardcoded defaults (wire behavior unchanged) ([#2280](https://github.com/opensandbox-group/OpenSandbox/pull/2280))++### JavaScript++- Preserve execution events with CR line endings: the SSE parsers only split on LF, so a valid CR-delimited stream silently dropped the execution ID, output, and completion event ([#2374](https://github.com/opensandbox-group/OpenSandbox/pull/2374))+- Scope in-flight endpoint-cache invalidation to each sandbox, so invalidating sandbox B no longer discards a pending fetch's result for sandbox A ([#2349](https://github.com/opensandbox-group/OpenSandbox/pull/2349))++### Kotlin++- Keep an explicit API key header ahead of the configured key in any casing, and stop attaching an empty key header when unconfigured ([#2375](https://github.com/opensandbox-group/OpenSandbox/pull/2375))++### C#++- Honor an explicit API key header regardless of casing: the case-sensitive check added a second, conflicting default entry, and the metrics reporter replaced the caller's credential ([#2372](https://github.com/opensandbox-group/OpenSandbox/pull/2372))++### Go++- Stop retrying non-idempotent writes by default: with retry enabled, 27 POST/PATCH call sites (sandbox/session/command/file/snapshot/vault mutations) could execute twice and still return success — POST/PATCH no longer retry status codes by default, retry only transport failures proven to be pre-send (dial/CONNECT/TLS before request bytes), and SSE bootstraps bypass the retry loop; callers who accept duplicate-execution risk can opt in via `RetryConfig.RetryableStatusCodesNonIdempotent` ([#2342](https://github.com/opensandbox-group/OpenSandbox/pull/2342))+- Strip the tenant API key from direct-mode data-plane requests: a tenant key supplied through `ConnectionConfig.Headers` was delivered to execd and the egress sidecar inside the untrusted sandbox — completing the credential-exposure fixes across all five SDKs ([#2337](https://github.com/opensandbox-group/OpenSandbox/pull/2337))+- Authenticate proxied data-plane requests with the API key header instead of smuggling the tenant key into the sandbox, fixing 401s in multi-tenant proxy mode ([#2274](https://github.com/opensandbox-group/OpenSandbox/pull/2274)); strip all sandbox-prefixed and authentication headers on cross-origin redirects ([#2178](https://github.com/opensandbox-group/OpenSandbox/pull/2178)); surface `execution_complete.exit_code` ([#2330](https://github.com/opensandbox-group/OpenSandbox/pull/2330))++## Controller++- Retain a BatchSandbox until cleanup completes: a deleted sandbox could disappear from the lifecycle API (GET 404) while its owned pod still ran, letting a replacement sandbox write the same persistent directory before the old writer exited; deletion now uses foreground cascading deletion alongside the existing finalizers — queries report `Stopping` during managed cleanup, and 404 arrives only after the runtime is gone ([#2154](https://github.com/opensandbox-group/OpenSandbox/pull/2154))+- Fix task-executor treating an empty exit file as exit code 0, which reported a failed or interrupted task as `Succeeded` when the shim was killed mid-write ([#2270](https://github.com/opensandbox-group/OpenSandbox/pull/2270))++## Execd++- Report sandbox-scoped CPU/memory metrics and OOM kills: `GET /metrics` read the host's `/proc` inside the container, so dashboards showed host-wide numbers; usage now comes from the sandbox's own cgroup when limits are configured (host view kept for unlimited guests), and a cgroupfs poller diffs the kernel OOM kill counter every 5 s to export `execd.system.oom.kills` with structured warn logs — no capabilities required ([#2200](https://github.com/opensandbox-group/OpenSandbox/pull/2200) [#2191](https://github.com/opensandbox-group/OpenSandbox/pull/2191))+- Serve the session-private `/tmp` through the files API: the strict isolation profile's `/tmp` was an anonymous tmpfs with no host-side path, so files-API paths under `/tmp` failed and callers had to shuttle artifacts through base64 shell commands; `/tmp` is now a host-backed per-session directory bind-mounted into the namespace — same private semantics, but readable and writable through the existing files endpoints ([#2424](https://github.com/opensandbox-group/OpenSandbox/pull/2424))+- Support browser PTY WebSocket authentication: browsers cannot set `X-EXECD-ACCESS-TOKEN` on a native WebSocket handshake, so terminal connections needed a BFF relay; the PTY upgrade now accepts the existing execd token via the `opensandbox-pty` subprotocol's credential entry (Kubernetes-style) with no new token issuer and header precedence preserved for SDK/CLI clients ([#2334](https://github.com/opensandbox-group/OpenSandbox/pull/2334))+- Keep isolated sessions alive when a foreground run is cancelled or disconnected: the run's context derived from the HTTP request, so a disconnect or `timeout_seconds` expiry SIGINT'd the whole process group including the persistent session shell — the session died and every later run 404'd; runs now interrupt only the running command (with a bounded SIGKILL escalation) while the session survives, and silent foreground runs emit periodic SSE pings so gateway idle timeouts no longer close the stream ([#2351](https://github.com/opensandbox-group/OpenSandbox/pull/2351))+- Preserve bash session output line endings: `run_in_session` stdout events dropped `\n`/`\r` bytes, so blank lines were unrecoverable and concatenating events did not reconstruct the output; event text now carries its original line ending — consumers should concatenate event text per run ([#2318](https://github.com/opensandbox-group/OpenSandbox/pull/2318))+- End a Jupyter execution when its kernel dies or the connection drops: both cases previously left the code-interpreter request open indefinitely with SSE pings keeping it alive; they now fail the execution (`KernelDied` / `KernelConnectionLost`) exactly once ([#2401](https://github.com/opensandbox-group/OpenSandbox/pull/2401))+- Keep reading session output past a line longer than 16 MiB: the read loop stopped at the cap — bash sessions hung until the 24 h default timeout, and isolated sessions leaked output into the next run; over-long lines are now passed on in pieces (never splitting UTF-8) ([#2275](https://github.com/opensandbox-group/OpenSandbox/pull/2275))+- Run large background code in isolated sessions: the wrapper passed code as a single `bash -c` argument, and Linux caps one exec argument at 128 KiB — background code above that failed with only `Argument list too long`; it is now delivered through stdin like the foreground path ([#2400](https://github.com/opensandbox-group/OpenSandbox/pull/2400)); probe private-network capability so restricted runtimes get a structured error for `share_net=false` sessions instead of an opaque EOF ([#2333](https://github.com/opensandbox-group/OpenSandbox/pull/2333))+- And the smaller fixes: report `exit_code` explicitly on command completion and errors ([#2303](https://github.com/opensandbox-group/OpenSandbox/pull/2303) [#2316](https://github.com/opensandbox-group/OpenSandbox/pull/2316)); send run errors after the stream started as framed SSE `error` events instead of a bare JSON body the Python SDK dropped ([#2354](https://github.com/opensandbox-group/OpenSandbox/pull/2354)); keep PTY output buffered until drained when the shell exits, so the last screen of output is no longer lost ([#2362](https://github.com/opensandbox-group/OpenSandbox/pull/2362)); always send the `WSCloseTakenOver` (4001) close frame on PTY takeover, even mid-write ([#2376](https://github.com/opensandbox-group/OpenSandbox/pull/2376) [#2378](https://github.com/opensandbox-group/OpenSandbox/pull/2378)); write an isolated run's script while reading its output so a chatty run can no longer deadlock on the stdin/stdout pipes ([#2399](https://github.com/opensandbox-group/OpenSandbox/pull/2399)); reject out-of-scope absolute paths in the session files view instead of silently touching the wrong file ([#2322](https://github.com/opensandbox-group/OpenSandbox/pull/2322)); serve `binds` mount points through the isolated session files API ([#2299](https://github.com/opensandbox-group/OpenSandbox/pull/2299)); truncate command output files before unlink so daemons holding the fd can't cause invisible disk growth ([#2295](https://github.com/opensandbox-group/OpenSandbox/pull/2295)); omit invalid upper-usage metrics and fail quota admission closed on scan errors ([#2257](https://github.com/opensandbox-group/OpenSandbox/pull/2257)); deduplicate JDK MITM CA imports across shared trust stores (~6.2 s → ~0.6 s for four JDKs) ([#2310](https://github.com/opensandbox-group/OpenSandbox/pull/2310)); default PTY sessions to `TERM=xterm-256color` when unset ([#2313](https://github.com/opensandbox-group/OpenSandbox/pull/2313)); percent-encode quotes and backslashes in `Content-Disposition` filenames ([#2161](https://github.com/opensandbox-group/OpenSandbox/pull/2161)); and parse the `Range` header before setting download headers so a malformed range returns a clean JSON 416 ([#2216](https://github.com/opensandbox-group/OpenSandbox/pull/2216))++## Networking++### egress++The OSEP-0022 vault items concern the `fast-sandbox` profile's credential-vault surface; the OSEP-0023 items remain scoped to the default-off experimental revision runtime.++- Add the egress-held vault for fast sandboxes (OSEP-0022), landing in stages: the internal `/vault/{sandboxUid}` relay surface with create-only POST (409 on duplicate, atomic across server replicas), full-revision PUT with `expectedRevision` and an `expectedIncarnation` precondition so a stale writer can never land on a reset's successor, value-including GET, and DELETE that keeps the policy ([#2249](https://github.com/opensandbox-group/OpenSandbox/pull/2249)); durable per-subject persistence — one file per subject under a Pod-scoped volume (optional tmpfs), the same commit protocol as policy files so **acked means durable and applied**, incarnation-fenced reload, and purge on unbind ([#2252](https://github.com/opensandbox-group/OpenSandbox/pull/2252)); and the superseded fastlet-proxy vault route removed ([#2247](https://github.com/opensandbox-group/OpenSandbox/pull/2247))+- Carry the vault across pause/resume (OSEP-0022 "Vault Lifecycle"): `VAULT_EXPORT` copies the vault file into the snapshot bundle strictly before runtime teardown and seals the subject (all vault ops answer 409 while paused; enforcement continues), and `VAULT_IMPORT` is the only authorized incarnation transfer — a genuine export failure fails the pause checkpoint so teardown never runs without a bundle, and a `vaultTransfer` capability signal lets an egress without vault persistence skip the transfer instead of failing ([#2255](https://github.com/opensandbox-group/OpenSandbox/pull/2255) [#2290](https://github.com/opensandbox-group/OpenSandbox/pull/2290))+- Pin the fast-sandbox MITM CA (OSEP-0022): the pool-pinned, versioned CA is seeded from a read-only secret mount into the mitmdump confdir, replacing generate-on-start — an egress restart no longer rotates the CA and silently invalidates every live sandbox's TLS trust; a missing or mismatched CA refuses only the MITM addon with `mitmCaFingerprint` / `mitmCaDown` surfaced on `/healthz` ([#2251](https://github.com/opensandbox-group/OpenSandbox/pull/2251))+- Define stale-subject takeover on slot reuse: the fast-sandbox dispatch key is the slot IP and slots are reused, so a `SET_BINDING` can claim a key still held by a dead-but-registered subject — egress now treats that as authoritative, tearing down the stale subject's nft rules, DNS refcount, MITM redirect, and vault slice before registering the successor deny-first ([#2250](https://github.com/opensandbox-group/OpenSandbox/pull/2250))+- Align the fast-sandbox network policy with the vault pattern: the recorded policy becomes egress-held state — a `/policy/{sandboxUid}` relay surface with revision preconditions, durable per-subject files, `POLICY_EXPORT`/`POLICY_IMPORT` snapshot transfer, and, after an egress restart, the committed file superseding the replayed create-time binding input ([#2309](https://github.com/opensandbox-group/OpenSandbox/pull/2309))+- Support port-scoped egress rules end to end (classic profile): `NetworkRule.ports` (TCP 1–65535, ≤256 per rule) makes `target` optional — port-only rules, or ports combined with an IP/CIDR; domain+`ports` is rejected since domain rules evaluate at the DNS proxy layer; an operator-shipped `reachable.ports.cap` whitelist is enforced as an always-deny ahead of every user rule so even `defaultAction: allow` cannot open a non-whitelisted port, and the fast-sandbox route rejects `ports` with 400 until the fastlet nft path can enforce them (fail-closed, documented) ([#2212](https://github.com/opensandbox-group/OpenSandbox/pull/2212))+- Exempt the MITM redirect target from port-scoped rules: with the operator port floor and transparent MITM both active, every intercepted flow was silently blackholed — the iptables REDIRECT rewrote dport 80/443 to the local listener before the filter chain ran, so the floor-complement drop judged the rewritten port; the listener tuple is now accepted ahead of every port-scoped rule, adding no new reachability, and a non-whitelisted intercepted port now fails visibly at the proxy instead of passing silently ([#2435](https://github.com/opensandbox-group/OpenSandbox/pull/2435))+- Continue the OSEP-0023 experimental foundation **[EXPERIMENTAL]** across the line: live credential-bound Vault admission with per-request rotation ([#2176](https://github.com/opensandbox-group/OpenSandbox/pull/2176)), acknowledged Policy revisions before publication ([#2182](https://github.com/opensandbox-group/OpenSandbox/pull/2182)), HTTP/2 admission with bounded drain ([#2201](https://github.com/opensandbox-group/OpenSandbox/pull/2201)), runtime-fault containment on an unexpected MITM exit ([#2172](https://github.com/opensandbox-group/OpenSandbox/pull/2172)), atomic revision policy-file persistence ([#2162](https://github.com/opensandbox-group/OpenSandbox/pull/2162)), nft apply-effect classification ([#2167](https://github.com/opensandbox-group/OpenSandbox/pull/2167)), static TLS passthrough selectors with startup rejection for conflicting native lists ([#2229](https://github.com/opensandbox-group/OpenSandbox/pull/2229)), TLS admission counters ([#2265](https://github.com/opensandbox-group/OpenSandbox/pull/2265)), the installation-only subject revision IPC foundation ([#2284](https://github.com/opensandbox-group/OpenSandbox/pull/2284)), and converged Fast Sandbox subject transitions ahead of the v2 lifecycle consumers ([#2294](https://github.com/opensandbox-group/OpenSandbox/pull/2294))+- And the smaller items: ship `egress-trace`, a read-only admission viewer inside the egress image (live policy state, nft sets, DNS leases, per-connection verdicts, and a `probe` subcommand; decrypted contents are never shown) ([#2230](https://github.com/opensandbox-group/OpenSandbox/pull/2230)); forward DNS queries over TCP when the client used TCP, so large truncated answers (SPF/DKIM TXT, many-record responses) finally arrive ([#2358](https://github.com/opensandbox-group/OpenSandbox/pull/2358)); preserve shared gateway DNS rules when the last subject on one fast-sandbox gateway releases, which previously removed the entire shared nft table ([#2427](https://github.com/opensandbox-group/OpenSandbox/pull/2427)); trim fsyncs from the create-time policy bootstrap and add per-stage create-latency instrumentation — real warm delivery measured sub-100 ms end to end with policy enforced ([#2327](https://github.com/opensandbox-group/OpenSandbox/pull/2327))++### ingress++- Implement OSEP-0024 activity tracking and wake-on-access: with `--activity-enabled`, every routed request records a monotonic activity timestamp to Redis — fire-and-forget, never on the hot path; with `--wake-enabled`, a request routed to a paused fast sandbox is parked instead of answered 503: one `ResumeSandbox` per replica per sandbox under a checkpoint-fenced singleflight, a bounded parking lot, and stale-route replay restricted to idempotent methods with reproducible bodies; the wake-timeout answer carries the OSEP-defined marker (`503` + `Retry-After: 1` + `OpenSandbox-Wake: expired`), stripped from every upstream response so a sandbox cannot forge provenance; with both flags unset, behavior is byte-identical to before ([#2156](https://github.com/opensandbox-group/OpenSandbox/pull/2156) [#2180](https://github.com/opensandbox-group/OpenSandbox/pull/2180))+- Stop rewriting unclean request paths: `http.ServeMux` answered paths with `//`, `.`, or `..` segments with a 301 to the cleaned path — so requests never reached the sandbox and a followed POST became a GET; the gateway now dispatches status endpoints by exact escaped path and proxies everything else unchanged ([#2403](https://github.com/opensandbox-group/OpenSandbox/pull/2403))++## Fast Sandbox++- Publish snapshots and template builds to OCI registries: each OverlayBD build can target an OCI registry (rootfs and snapfiles images, no name index — Sandboxes boot from `status.manifestRef`), Fastlets enable OCI by default with an explicit opt-out, OverlayBD templates require OCI storage, the controller consolidates snapshot artifact cleanup and refreshes Fastlet capacity after runtime deletion, and a bounded manifest cache survives Fastlet replacement; the SandboxSnapshot CRD gains `oci://` manifest references and makes `spec.templateName` optional for OCI snapshots ([#2338](https://github.com/opensandbox-group/OpenSandbox/pull/2338))+- Make sandbox deletion reliable: deletion now sends a fenced Fastlet delete before any runtime-absence check, so a transport failure or empty inspect response is no longer treated as proof the sandbox is gone (which could orphan the microVM while the CR disappeared); the Fastlet records a per-identity tombstone so a delayed create cannot revive a deleted sandbox. Create placement also recovers faster: FastPath refreshes its candidate list within a bounded budget after proven rejections ([#2214](https://github.com/opensandbox-group/OpenSandbox/pull/2214))+- And the smaller items: batch guest NAT updates into one `iptables-restore --noflush` so reapplying a guest address no longer accumulates rules ([#2214](https://github.com/opensandbox-group/OpenSandbox/pull/2214)); defer `SET_BINDING` while the network attachment has no IP, stop SandboxPool status-update loops, gate route removal on runtime deletion, and canonicalize Docker Hub credential hosts ([#2338](https://github.com/opensandbox-group/OpenSandbox/pull/2338)); and emit per-create phase timing from Fastlets, feeding the create-latency evidence pipeline (steady-state warm delivery measured at 16–17 ms past create) ([#2327](https://github.com/opensandbox-group/OpenSandbox/pull/2327))++## Misc++- Console: land the developer console MVP (all five planned PRs) — a FastAPI BFF with httpOnly sessions proxying the lifecycle, snapshots, and diagnostics APIs, plus a React SPA covering tenant overview, sandbox list/create/detail with logs, snapshots and diagnostics pages, and admin/platform-ops views (`/api/admin/sandboxes` aggregation, pools and overview KPIs, env-gated K8s probes) with deployment docs and CI ([#2129](https://github.com/opensandbox-group/OpenSandbox/pull/2129) [#2130](https://github.com/opensandbox-group/OpenSandbox/pull/2130) [#2131](https://github.com/opensandbox-group/OpenSandbox/pull/2131) [#2132](https://github.com/opensandbox-group/OpenSandbox/pull/2132) [#2133](https://github.com/opensandbox-group/OpenSandbox/pull/2133) [#2271](https://github.com/opensandbox-group/OpenSandbox/pull/2271))+- CLI: add `osb terminal <sandbox-id>` — a real PTY inside the sandbox over the execd PTY WebSocket, with raw mode, resize, replay on reconnect, and remote exit code propagation ([#2313](https://github.com/opensandbox-group/OpenSandbox/pull/2313)); plus smaller fixes: config values coerce to their declared types, output stays writable on non-UTF-8 streams, `osb config set` uses a real TOML parser preserving comments, installed skills land where each tool reads them, and out-of-range durations report as validation errors ([#2169](https://github.com/opensandbox-group/OpenSandbox/pull/2169) [#2187](https://github.com/opensandbox-group/OpenSandbox/pull/2187) [#2194](https://github.com/opensandbox-group/OpenSandbox/pull/2194) [#2208](https://github.com/opensandbox-group/OpenSandbox/pull/2208) [#2272](https://github.com/opensandbox-group/OpenSandbox/pull/2272))+- OSEPs: accept and document OSEP-0024 (proposal plus architecture page and user guide) ([#2152](https://github.com/opensandbox-group/OpenSandbox/pull/2152) [#2217](https://github.com/opensandbox-group/OpenSandbox/pull/2217)); revise OSEP-0022 around the sealed-revision binding and the per-pool pinned CA ([#2174](https://github.com/opensandbox-group/OpenSandbox/pull/2174) [#2282](https://github.com/opensandbox-group/OpenSandbox/pull/2282)); and withdraw the planned runtime driver ask ([#2259](https://github.com/opensandbox-group/OpenSandbox/pull/2259))+- Docs: unify component telemetry metrics into one reference at `docs/guides/telemetry.md` ([#2205](https://github.com/opensandbox-group/OpenSandbox/pull/2205)); redesign the docs homepage with an animated dark theme ([#2345](https://github.com/opensandbox-group/OpenSandbox/pull/2345)); highlight the project's AAIF (Agentic AI Foundation / Linux Foundation) affiliation and update the legal footer ([#2395](https://github.com/opensandbox-group/OpenSandbox/pull/2395) [#2343](https://github.com/opensandbox-group/OpenSandbox/pull/2343)); update the gVisor notes for current upstream reality ([#2431](https://github.com/opensandbox-group/OpenSandbox/pull/2431)); and the usual upkeep — refreshed network architecture pages, markdown reflow across 148 files, CONTRIBUTING/test-path/PR-size-policy corrections, and `AGENTS.md` dedupe ([#2210](https://github.com/opensandbox-group/OpenSandbox/pull/2210) [#2285](https://github.com/opensandbox-group/OpenSandbox/pull/2285) [#2175](https://github.com/opensandbox-group/OpenSandbox/pull/2175) [#2339](https://github.com/opensandbox-group/OpenSandbox/pull/2339) [#2412](https://github.com/opensandbox-group/OpenSandbox/pull/2412) [#2211](https://github.com/opensandbox-group/OpenSandbox/pull/2211) [#2225](https://github.com/opensandbox-group/OpenSandbox/pull/2225))+- Security/dependency bumps: resolve 41 of 46 open Dependabot security alerts across Go, Python, and npm manifests (klauspost/compress, moby/sys/user, certifi, setuptools, undici, fast-uri, …); five egress `h2` alerts remain open by design — three are not exploitable in this deployment, and the two real request-smuggling CVEs need a base-image/mitmproxy 12 migration tracked as follow-up ([#2411](https://github.com/opensandbox-group/OpenSandbox/pull/2411))+- Fast-sandbox integration environment: split the 2.4k-line entry script into entry + env + verify parts with sharpened policy-transfer coverage ([#2319](https://github.com/opensandbox-group/OpenSandbox/pull/2319)); drive the verify stages through the published `osb` CLI and add an opt-in `IDLE_PAUSE=1` profile verifying the full auto-pause → wake loop ([#2171](https://github.com/opensandbox-group/OpenSandbox/pull/2171) [#2202](https://github.com/opensandbox-group/OpenSandbox/pull/2202)); split the template verify matrix into per-stack steps ([#2389](https://github.com/opensandbox-group/OpenSandbox/pull/2389)); and let fast-sandbox upstream PRs trigger the OpenSandbox KVM integration suite against their head SHA pre-merge ([#2335](https://github.com/opensandbox-group/OpenSandbox/pull/2335))+- node-agent: fix syscall BPF verification failing when system header changes affect only DWARF checksums ([#2325](https://github.com/opensandbox-group/OpenSandbox/pull/2325))+- Tests/CI: cache Go modules for the Kubernetes nightly e2e jobs ([#2306](https://github.com/opensandbox-group/OpenSandbox/pull/2306)); close the credential-vault happy path in the fast-sandbox smoke ([#2256](https://github.com/opensandbox-group/OpenSandbox/pull/2256)); require the Fast Sandbox IP-rebind kernel regression in privileged CI ([#2415](https://github.com/opensandbox-group/OpenSandbox/pull/2415)); dump fastlet Pod container logs on pause/resume verify failure ([#2290](https://github.com/opensandbox-group/OpenSandbox/pull/2290)); align the node-agent log-collection e2e with execd's preserved trailing newline ([#2164](https://github.com/opensandbox-group/OpenSandbox/pull/2164)); and make the umbrella release workflow dispatch-only ([#2223](https://github.com/opensandbox-group/OpenSandbox/pull/2223))+- Examples: add an all-in-one Docker image for the DeerFlow example bundling the OpenSandbox server and the DeerFlow backend, for one-command workshop starts ([#2262](https://github.com/opensandbox-group/OpenSandbox/pull/2262))+- release: inject the server package version into the server image build so `/version` no longer reports a fallback dev version ([#2356](https://github.com/opensandbox-group/OpenSandbox/pull/2356)); bump platform version to `1.2.0` across charts and image references++## Upgrade & Compatibility++- Breaking (Go SDK): POST/PATCH requests are no longer retried by default — status-code retries for writes require explicit opt-in via `RetryConfig.RetryableStatusCodesNonIdempotent`, and ambiguous transport failures (read/write timeouts, unexpected EOF) are no longer retried for writes; callers that relied on write retries must handle the returned error or opt in ([#2342](https://github.com/opensandbox-group/OpenSandbox/pull/2342))+- Behavior change: bash-session stdout event text now includes its original line endings, and blank lines appear as events — consumers must concatenate event text per run to recover exact output instead of treating each event as a newline-free line ([#2318](https://github.com/opensandbox-group/OpenSandbox/pull/2318))+- Behavior change: a BatchSandbox past its `spec.expireTime` now reports `Terminated` / `SANDBOX_EXPIRED` instead of `Running`, even while the pod is still Ready — callers that treat `Running` as alive should check expiry ([#2238](https://github.com/opensandbox-group/OpenSandbox/pull/2238))+- Behavior change: BatchSandbox pods now default to `restartPolicy: Never` — deployments that relied on the implicit `Always` and want restarts must set it explicitly in their `batchsandbox_template_file` ([#2128](https://github.com/opensandbox-group/OpenSandbox/pull/2128))+- Behavior change: deleted sandboxes stay queryable in `Stopping` until runtime cleanup completes, and only then return 404 — clients sharing a persistent directory should wait for the 404 before starting a replacement ([#2154](https://github.com/opensandbox-group/OpenSandbox/pull/2154))+- Behavior change: Docker-backed snapshots of gVisor containers without `--overlay2=none` are rejected with `SNAPSHOT::UNSUPPORTED_RUNTIME` (409) instead of publishing a silently incomplete image ([#2241](https://github.com/opensandbox-group/OpenSandbox/pull/2241))+- Behavior change: execd CPU/memory metrics report sandbox-scoped values when the sandbox cgroup has limits configured (previously host-wide); metric names and wire format are unchanged, but dashboards will shift ([#2200](https://github.com/opensandbox-group/OpenSandbox/pull/2200))+- Behavior change: on Docker, labels inherited from the image no longer appear as sandbox metadata, restored sandboxes no longer inherit the source's reserved labels, and `image.uri` reports the reference the sandbox was created with ([#2363](https://github.com/opensandbox-group/OpenSandbox/pull/2363) [#2269](https://github.com/opensandbox-group/OpenSandbox/pull/2269) [#2353](https://github.com/opensandbox-group/OpenSandbox/pull/2353))+- Behavior change: unknown `NetworkPolicy`/`NetworkRule` fields now return 422 and unrecognized create-time actions return 400 (previously silently ignored); trailing newlines in labels and resource names are rejected; contract-valid inputs are unchanged ([#2383](https://github.com/opensandbox-group/OpenSandbox/pull/2383) [#2385](https://github.com/opensandbox-group/OpenSandbox/pull/2385))+- Behavior change: `networkPolicy` is rejected for Docker network modes `none`/`pasta`/`slirp4netns` — previously accepted silently for `none` ([#2203](https://github.com/opensandbox-group/OpenSandbox/pull/2203))+- Behavior change (Go SDK, direct mode): the tenant API key supplied through `ConnectionConfig.Headers` is no longer sent to execd/egress inside the sandbox ([#2337](https://github.com/opensandbox-group/OpenSandbox/pull/2337))+- Behavior change: template reads (`GET /templates`, the create gate) report the database projection with freshness bounded by watch delivery (normally milliseconds) — a create racing a just-finished build can see a brief retryable 404 ([#2326](https://github.com/opensandbox-group/OpenSandbox/pull/2326))+- Behavior change: isolated-session files-API paths outside the session's mounts are rejected with an error instead of silently resolving into the workspace ([#2322](https://github.com/opensandbox-group/OpenSandbox/pull/2322))+- Behavior change (experimental egress live mode only): nonempty native `ignore_hosts`/`allow_hosts` now reject startup — migrate static TLS bypass entries to `OPENSANDBOX_EGRESS_MITMPROXY_PASSTHROUGH_HOSTS` ([#2229](https://github.com/opensandbox-group/OpenSandbox/pull/2229))+- Behavior change: execd upper-directory quota admission fails closed when `upper_max_bytes > 0` and a usage scan fails (previously the quota check was silently bypassed) ([#2257](https://github.com/opensandbox-group/OpenSandbox/pull/2257))+- Deprecation: the `extensions["access.renew.extend.seconds"]` create key is deprecated in favor of `lifecycle.renewalPolicy.extendSeconds` — supported throughout 1.x, removed in 2.0; setting both is accepted only when values match ([#2296](https://github.com/opensandbox-group/OpenSandbox/pull/2296))+- Fast Sandbox: OverlayBD templates now require OCI storage, and snapshot `spec.templateName` is optional with `status.manifestRef` admitting `oci://` — update consumers that assumed the name index or a required `templateName` ([#2338](https://github.com/opensandbox-group/OpenSandbox/pull/2338))+- Images: `opensandbox/<component>:release-1.2.0` (all three registries)+- Packages: server / CLI / SDKs all at `1.2.0`+- Charts: render from this tag (`helm template ./manifests/charts/opensandbox`)+- Kubernetes: supported range v1.21 – v1.34 (charts declare `kubeVersion: ">=1.21.1-0"`)+- Skew: server ↔ CLI/SDK same line supported; ±1 minor warns++## 👥 Contributors++Thanks to these contributors ❤️++- @Aling33+- @BootstrapperSBL+- @Claire-ovo+- @Dev-next-gen+- @EtiennePerot+- @GodBlf+- @Jackmeson1+- @JasonBuildAI+- @Jinzhengxu+- @Jun516+- @KennyMcSimpson+- @MaxFreedomPollard+- @Pangjiping+- @acodercat+- @alex-feel+- @comqx+- @hardness1020+- @hittyt+- @hpliStartAgain+- @jiangjiang248+- @jianpingpei+- @jwx0925+- @kittimzhe+- @markankamaransheogarat-sys+- @mengdehong+- @ninan-nn+- @pingkui+- @ranjianghong526-hash+- @ratishjain12+- @xxwtiancai+- @yangjj-iso+- @zw11591-sketch++## Artifacts++- BOM: [docs/releases/1.2.0.yaml](./1.2.0.yaml)+- Images: `opensandbox/<component>:release-1.2.0` (Docker Hub / GHCR / ACR)+- Packages: PyPI ×5, npm ×2, Maven Central ×5, NuGet ×2 — all at `1.2.0`+- Go module: `github.com/alibaba/OpenSandbox/sdks/sandbox/[email protected]`++## Installation++```bash+# Platform (Kubernetes) — render the chart at this tag and apply+git clone https://github.com/opensandbox-group/OpenSandbox+cd OpenSandbox+git checkout release-1.2.0+helm dependency build manifests/charts/opensandbox # package file:// sub-charts (not committed)+# Before first install, configure the server API key and enable the ingress+# gateway (required on Kubernetes; the bare render disables it, and the server+# refuses to start with an empty api_key) — see the deployment guide:+# https://open-sandbox.ai/deployment/+helm template ./manifests/charts/opensandbox | kubectl apply -f -+# or point your GitOps platform (Argo / Flux) at the repo path + tag++# SDKs+pip install opensandbox==1.2.0 # Python+npm install @alibaba-group/[email protected] # JavaScript+# Kotlin/JVM: implementation("com.alibaba.opensandbox:sandbox:1.2.0")+dotnet add package Alibaba.OpenSandbox --version 1.2.0+go get github.com/alibaba/OpenSandbox/sdks/sandbox/[email protected]++# Run the server locally+uvx opensandbox-server==1.2.0+```++Verify what you installed against the BOM: see [Release Verification](https://open-sandbox.ai/community/release-verification).