server/v0.2.2

## What's New

### ⚠️ Breaking Changes

- **Credential Vault requires `dns+nft` enforcement** — DNS-only egress can no longer carry credential-bound traffic. Migrate to `[egress] mode = "dns+nft"`; `defaultAction: allow` still works but is deprecated and warns. #1136

- **`X-Forwarded-Proto` no longer trusted by default** — the server proxy strips client-supplied forwarded headers and rebuilds them from the connection. Deployments that terminate TLS in front of the egress sidecar must list their proxy addresses in the new `OPENSANDBOX_EGRESS_CREDENTIAL_VAULT_TRUSTED_PROXY_CIDRS`. #1138

- **`OPENSANDBOX_EGRESS_MITMPROXY_SCRIPT` removed from the env allowlist** — the variable let a sandbox point the egress sidecar's `mitmdump -s` at any file under the shared `/opt/opensandbox` emptyDir, enabling code execution in the sidecar and Credential Vault plaintext access. Requests carrying it are now rejected. Ship custom addons in a purpose-built egress image via `ENV`. #1194

### 🔒 Security

- **Secure-access token now enforced on the server proxy** — the lifecycle proxy at `/sandboxes/{id}/proxy/{port}/...` previously skipped API-key checks and never validated the `OpenSandbox-Secure-Access` header (CVSSv3.1 ~7.5). Both HTTP and WebSocket paths now require a matching header (constant-time compare) and strip the token before forwarding. #1191

- **Sandbox pods no longer mount a service-account token** — the `kubernetes.service_account` config is removed and `automountServiceAccountToken: false` is set on both providers. Nothing in the sandbox consumed the token. Operators depending on the SA's `imagePullSecrets` should move `serviceAccountName` into their agent-sandbox template. #1227

- **21 CVE-remediating dependency bumps** — `pydantic-settings`, `python-multipart`, `starlette`, `cryptography`, `pyjwt`, `undici`, `js-yaml`. Direct deps pinned in `pyproject.toml`, transitives via `[tool.uv] constraint-dependencies` and `pnpm.overrides`. #1145

### ✨ Features

- **Multi-tenancy provider with file and HTTP backends** — sandboxes and snapshots can be isolated per tenant via K8s namespaces. Ships a file provider (TOML with mtime hot-reload) and an HTTP provider (per-key TTL cache + singleflight). Tenant context is propagated per request through auth middleware; unavailable providers return 503. Closes #972 #497. #1184

- **`sandbox.create` latency reported via metrics events** — new `POST /v1/metrics/events` accepts fire-and-forget `MetricsEvent` payloads and optionally records them as an OTEL histogram (`opensandbox.sandbox.create.duration`). Python/Go/JS SDKs already hook this on every create. Configure via `[otel]`. #1307

- **Sandbox extensions returned in lifecycle responses** — `CreateSandboxResponse`, `getSandbox`, and `listSandboxes` now surface `opensandbox.extensions.*` back to callers, matching the values set at create time. K8s reads from pod annotations; Docker persists them as container labels. Closes #1060. #1112 #1167

- **Snapshot list supports exact-name filtering** — `GET /snapshots` accepts an optional `name` query parameter, honored through the API, service, and SQLite repository while preserving pagination. Exposed in the Python, JavaScript, Go, C#, and Kotlin SDKs. Closes #1205. #1301

- **Configurable Docker port range for bridge-mode sandboxes** — new `[docker] port_range_min` / `port_range_max` fields (default `40000-60000`) narrow host-port allocation so multiple bridge-mode sandboxes can expose distinct execd ports (host mode always binds 44772). #1182

- **`OPENSANDBOX_EGRESS_POLICY_FILE` and `OPENSANDBOX_EGRESS_SANDBOX_ID` now allowlisted** — sandbox creates can opt into egress policy-file persistence and per-sandbox OTLP attribution (OSEP-0010) via the standard `env` field. #1190 #1335

- **JDK trust store hardened for MITM CA** — `bootstrap.sh` now discovers every JDK on the system and imports the egress MITM CA into each `cacerts` via `keytool`. Fixes PKIX failures on tarball / Alpine / distroless JDKs when using the credential proxy. Idempotent and best-effort. Closes #1201. #1229

### 🐛 Bug Fixes

- **Docker `listSandboxes` no longer flakes on concurrent deletion** — docker-py's high-level `containers.list()` does a follow-up inspect per match, so a sibling cleanup mid-listing failed the whole call with 500. The service now uses the low-level `docker_client.api.containers(...)` summary endpoint and maps `NotFound` from single-container lookups to 404. List view drops `entrypoint`, exit code, and `FinishedAt` fidelity (callers needing those must use `getSandbox`). #1342

- **K8s informer honors `informer_resync_seconds`** — periodic full resync was silently disabled while watch mode was active. Watch streams are now capped by the remaining resync interval. Fixes #1322. #1323

- **`networkPolicy` rejected in pool mode** — combining `extensions.poolRef` with a `networkPolicy` is unsupported; requests are now rejected at schema validation with a defense-in-depth guard in `BatchSandboxProvider`. Closes #1315. #1319

- **Diagnostics scoped to the tenant namespace** — K8s pod/log/event lookups use the request-scoped tenant namespace instead of the server default. Non-tenant requests unchanged. Closes #1304. #1305

- **`use_server_proxy` preserves the API mount prefix** — the API is mounted both bare and under `/v1`, but proxied endpoints were derived from `request.base_url` and dropped the prefix, breaking ingress deployments that path-split `/v1/*`. The rewritten endpoint now keeps the prefix; `server.eip` is still respected verbatim. #1297

- **Renewed Docker sandbox expirations survive restart** — timers were rebuilt from immutable container labels, so a renewed sandbox reverted to its original TTL. Renewals now write an override into the file-backed metadata store; old callbacks that observe a renewal rearm cleanly. Closes #1200. #1267

- **PVC `readOnly` propagated to the volume source** — the flag was only applied to the mount, not to `persistentVolumeClaim.readOnly` on the pod spec. Both are now aligned. Closes #545. #1246

- **Fail fast for missing `poolRef` pools** — `extensions.poolRef` is validated against the Pool CRD before creating a `BatchSandbox`, returning `KUBERNETES::POOL_NOT_FOUND` instead of failing downstream. Fixes #1175. #1176

- **Docker egress no longer crashes on hosts without IPv6 procfs entries** — `egress.disable_ipv6=true` unconditionally injected `net.ipv6.conf.*.disable_ipv6` sysctls. The injection is now skipped when the required procfs knobs are missing. Fixes #1168. #1172

- **Event loop no longer blocked during Docker image pull** — provisioning runs on a daemon thread with an `asyncio.Future` so health checks stay responsive. New `timeout_graceful_shutdown` config (default 5s) makes SIGINT actually exit. #1171

- **K8s diagnostics logs endpoint works on multi-container pods** — `read_namespaced_pod_log` was called without a `container` argument, so every standard sandbox (with `egress` sidecar + `execd-installer` init) returned 500. The endpoint now defaults to the `sandbox` container, accepts `?container=` for sidecar/init logs, and maps K8s errors to structured 400/403/404/502. Fixes #1150. #1151

### 📦 Misc

- **`renew_intent` marked stable** — OSEP-0009 is out of experimental; drops `[EXPERIMENTAL]` / 🧪 markers from config docstrings, example TOML, startup logs, and `configuration.md`. No behavior change. #1350

- **Removed unused `PendingSandbox` machinery and fixed the spec** — Docker and K8s both provision synchronously; the async worker, related helpers, and their tests were dead code (−357 lines). The `POST /sandboxes` 202 response description in `specs/sandbox-lifecycle.yml` also described a `Pending → Running` polling flow that was never implemented — now corrected. #1178

- **GHCR image publishing** — component images (server, k8s, execd, egress, ingress) are now published to GitHub Container Registry alongside Docker Hub and Aliyun. Refs #1160. #1161

- **Package metadata and docs point at `opensandbox-group/OpenSandbox`** — user-facing links across README, docs, Helm chart, examples, and `server`/`cli` `pyproject.toml` updated. No package rename. #1197 #1140

- **Auto-bumps** — `execd` v1.0.20 → v1.0.21 (#1144 #1279); `egress` v1.1.3 → v1.1.4 (#1142 #1278).

## 👥 Contributors

Thanks to these contributors ❤️

- @1363653611
- @bcho
- @FAUST-BENCHOU
- @ferponse
- @GreenShadeZhang
- @Gujiassh
- @hellomypastor
- @jianpingpei
- @jwx0925
- @Pangjiping
- @ruirui6946
- @shenshouer
- @tea-artist

---

- PyPI: opensandbox-server==0.2.2
- Docker Hub: opensandbox/server:v0.2.2
- Aliyun Registry: sandbox-registry.cn-zhangjiakou.cr.aliyuncs.com/opensandbox/server:v0.2.2
- GHCR: ghcr.io/opensandbox-group/server:v0.2.2