@mseep/open-computer-use 1.0.0

package/docs/future-architecture/research/06-agent-sandbox.md

@@ -0,0 +1,142 @@
+<!-- SPDX-License-Identifier: FSL-1.1-Apache-2.0 -->
+<!-- Copyright (c) 2025 Open Computer Use Contributors -->
+
+# 06 — kubernetes-sigs/agent-sandbox (CRD base for `KubernetesProvider`)
+
+> Source: [kubernetes-sigs/agent-sandbox](https://github.com/kubernetes-sigs/agent-sandbox). Google-backed, SIG Apps, v1alpha1.
+> Direct base for [Phase 5](../roadmap.md#phase-5--helm-hardening--kubernetesprovider) `KubernetesProvider`.
+
+## 1. CRD shapes & field semantics
+
+### `Sandbox` — core singleton workload
+
+- **Where.** `api/v1alpha1/sandbox_types.go:129-244`.
+- **Fields.**
+  - `podTemplate` (required) — embeds `corev1.PodSpec` + optional labels/annotations.
+  - `volumeClaimTemplates[]` — dynamically provisioned PVCs; merged into `Pod.Spec.Volumes`.
+  - `replicas` — binary (0/1) for suspend/resume.
+  - `service` — bool; auto-creates headless Service.
+  - `lifecycle.shutdownTime` — absolute expiry; `lifecycle.shutdownPolicy` ∈ {Delete, Retain}.
+- **Status.** Conditions: `Ready`, `Suspended`, `Finished`. `serviceFQDN`, `podIPs[]`.
+
+### `SandboxTemplate` — reusable blueprint
+
+- **Where.** `extensions/api/v1alpha1/sandboxtemplate_types.go:73-154`.
+- **Fields.** Inherits Sandbox fields, plus:
+  - `networkPolicyManagement` ∈ {Managed, Unmanaged}.
+  - `networkPolicy` — custom Ingress/Egress; **if omitted → "Secure by Default"** (Sandbox Router ingress only, no internal egress).
+  - `envVarsInjectionPolicy` ∈ {Allowed, Overrides, Disallowed} — gates whether a Claim can inject env vars.
+- **No status subresource** — read-only template.
+
+### `SandboxClaim` — user-facing claim
+
+- **Where.** `extensions/api/v1alpha1/sandboxclaim_types.go:124-194`.
+- **Fields.**
+  - `sandboxTemplateRef.name` (required, same namespace).
+  - `lifecycle` (mirrors Sandbox + `ttlSecondsAfterFinished`).
+  - `warmpool` ∈ {none, default, named-pool} — default attempts adoption from warm pool.
+  - `additionalPodMetadata` — labels/annotations propagated; restricted domains (`kubernetes.io`, `k8s.io`, `agents.x-k8s.io` forbidden).
+  - `env[]` — gated by template's `envVarsInjectionPolicy`.
+- **Status.** Mirrors Sandbox + claim-specific (`Ready`, `Expired`, `Finished`).
+
+### `SandboxWarmPool` — pre-warmed reservoir
+
+- **Where.** `extensions/api/v1alpha1/sandboxwarmpool_types.go:31-107`.
+- **Fields.** `replicas` (HPA-compatible), `sandboxTemplateRef`, `updateStrategy.type` ∈ {Recreate, OnReplenish}.
+- **Status.** `replicas`, `readyReplicas`, `selector` (label for pool member discovery).
+
+## 2. Controller reconciliation patterns
+
+### Sandbox controller
+
+- **Where.** `controllers/sandbox_controller.go:82-100`.
+- **Behaviors.**
+  - Tracks pod via controllerRef + `agents.x-k8s.io/pod-name` annotation when adopted from pool.
+  - Volume merging — PVC-backed volumes from `volumeClaimTemplates` override by name (StatefulSet-like).
+  - Lifecycle: polls `shutdownTime` expiry, deletes Pod+Service per `shutdownPolicy`.
+  - Service provisioning — headless Service with same name.
+  - Finalizers cascade Pod/PVC deletion.
+
+### SandboxClaim controller
+
+- **Where.** `extensions/controllers/sandboxclaim_controller.go:140-282`.
+- **Critical patterns.**
+  - **Fast-path warm-pool adoption before template lookup** — minimizes cold-start latency.
+  - Lazy template validation — requeue without error if missing (no log spam).
+  - Synchronous metadata validation (reject if bad labels).
+  - **Namespace isolation enforced** — no cross-namespace adoption.
+  - Tracks `observedTime` per claim UID — measures cold-start.
+  - Dual timers: `shutdownTime` (absolute) and `ttlSecondsAfterFinished` (relative to Finished condition).
+  - NetworkPolicy reconciliation is **non-blocking** — continues if fetch fails.
+
+### SandboxWarmPool controller
+
+- **Where.** `extensions/controllers/sandboxwarmpool_controller.go:63-120`.
+- **Behaviors.** Lists by hash label; creates/deletes to match `replicas`. `Recreate` deletes stale immediately; `OnReplenish` waits for adoption.
+
+### SandboxTemplate controller
+
+- **Where.** `extensions/controllers/sandboxtemplate_controller.go:52-100`.
+- **Behaviors.** Creates/updates **single shared NetworkPolicy** per template (not per pod). NP name = `<template.Name>-network-policy`. Secure Default = ingress only from Sandbox Router, egress to public internet excluding RFC1918 + metadata server.
+
+## 3. RuntimeClass integration
+
+- **Mechanism.** **No explicit CRD field** — `podTemplate.spec.runtimeClassName` is passed through to Pod for kubelet resolution.
+- **Examples.** `examples/kata-gke-sandbox/README.md:42-60` uses `runtimeClassName: kata-qemu`. `examples/quickstart/gvisor.md:45-55` uses `runtimeClassName: gvisor`.
+- **Per-tenant tiering.** Different templates → different runtimes. **No dynamic per-claim override** in the core API.
+- **For us.** Aligns with [ADR-0004](../adr/0004-pluggable-runtime-via-runtimeclass.md). We propagate `SandboxTemplate.runtime_class` into the embedded `podTemplate.spec.runtimeClassName`. If we need per-claim override (e.g. session tier), we add a custom mutation (admission webhook or template selection in L4).
+
+## 4. NetworkPolicy assumptions ⚠️
+
+- **Single shared NP per template** — pod selector via hash label `agents.x-k8s.io/sandbox-template-ref-hash`.
+- **Secure Default details (when `networkPolicy` omitted):**
+  - Ingress: only from Sandbox Router.
+  - Egress: public internet, **excluding RFC1918 + metadata server** (no cluster DNS by default).
+  - ⚠ **Sidecars (Istio, monitoring) on separate ports must be explicitly allowed** in custom rules.
+- **Operators must add cluster-DNS allowance** — easy to miss.
+- **For us.** Phase 5 must add custom NetworkPolicy that allows kube-dns + our egress-proxy svc + Sandbox Router ingress. Document the sidecar caveat loudly in our Helm `values.yaml`.
+
+## 5. RBAC model
+
+- **Where.** `k8s/rbac.generated.yaml:1-60` (core) + `k8s/extensions-rbac.generated.yaml:1-88` (extensions).
+- **Core controller.** ClusterRole `agent-sandbox-controller` — sandboxes (+ status, finalizers), pods, PVCs, services, events, leases (leader-elect).
+- **Extensions controller.** Adds CRDs (sandboxclaims, templates, warmpools + status/finalizers), Pod patching (adoption), NetworkPolicy CRUD.
+- **Verbs.** Standard CRUD set.
+- **For us.** Reuse as-is via Helm.
+
+## 6. Status subresource design
+
+- **Conditions** — `metav1.Condition` (type, status, reason, message, observedGeneration).
+- **Sandbox.** `Ready` (DependenciesReady/NotReady/SandboxSuspended) | `Suspended` (PodTerminated/PodNotTerminated) | `Finished` (PodSucceeded/PodFailed).
+- **`serviceFQDN`** — controller-flag `--cluster-domain` configurable.
+- **`podIPs[]`** — direct from Pod status, mirrored for fast L4 routing (matches our cross-cutting pattern 9: app-layer routing, not ClientIP).
+
+## 7. Webhooks
+
+- **None.** All validation is synchronous in controllers + OpenAPI schema (kubebuilder markers).
+- **For us.** Defer admission webhooks; add later only if cross-resource validation is needed.
+
+## 8. Project maturity signals
+
+- **Version.** v1alpha1 (pre-beta). Roadmap mentions Beta/GA as future.
+- **Governance.** kubernetes-sigs project; SIG Apps; CLA; OWNERS file. Auto-stale 30 d, auto-close 15 d. AI-assisted first-pass review (Copilot).
+- **Adoption.** No explicit prod-user list. Kata + gVisor examples lean GKE. Backed by Google + community.
+- **Release cadence.** Manual via `RELEASE.md`; no release tags in shallow clone.
+- **For us.** Vendor the CRDs **with our own copy under version control** (Phase 5 research). Don't blindly track upstream main during alpha.
+
+## 9. Skip notes
+
+- **No per-claim RuntimeClass override** — different templates needed.
+- **No webhook validation** — sync in controllers.
+- **Sidecars need explicit NP rules.**
+- **No dynamic cluster-domain discovery** — operator sets controller flag.
+
+## Phase-5 implementation checklist
+
+1. Vendor `Sandbox`/`SandboxTemplate`/`SandboxClaim`/`SandboxWarmPool` types under our own CRD group (or upstream `agents.x-k8s.io` directly — decide in `phase-5-research.md`).
+2. Map our `SandboxProvider.spawn(template, ctx)` → create `SandboxClaim`; watch `Ready` condition.
+3. Use Secure-Default NetworkPolicy + override to allow our egress-proxy svc + kube-dns.
+4. Per-tenant template = per-tenant RuntimeClass (sysbox / gVisor / kata-ch).
+5. Warm pool: `SandboxWarmPool` with `replicas` driven by L4 demand prediction.
+6. Fast-path adoption is a controller-internal optimization — our L4 just sees fast `Ready`.
+7. App-layer session routing — L4 reads `Status.sandbox.podIPs[0]` from Claim, forwards HTTP directly.

package/docs/future-architecture/research/07-chromedp.md

@@ -0,0 +1,78 @@
+<!-- SPDX-License-Identifier: FSL-1.1-Apache-2.0 -->
+<!-- Copyright (c) 2025 Open Computer Use Contributors -->
+
+# 07 — chromedp (Go direct-CDP client)
+
+> Source: [chromedp/chromedp](https://github.com/chromedp/chromedp).
+> Candidate for Phase 7 (Go guest agent — drives Chromium in-sandbox) and Phase 6 (L4 — tunnels CDP frames from user UI to sandbox).
+
+## 1. CDP transport — single WebSocket, session-multiplexed
+
+- **Where.** `conn.go:42-142`.
+- **What.** One WebSocket per browser (`gobwas/ws`), JSON marshalling with reused encoder/decoder buffers. Session ID multiplexing handles multi-tab.
+- **Constraint.** Chrome doesn't support frame fragmentation; single frame max 100 MiB.
+- **Why for us.** Phase 7 — efficient single-conn model exactly matches our agent's "one Chromium, many targets".
+
+## 2. Action / task model — minimal `Action` interface
+
+- **Where.** `chromedp.go:718-743`.
+- **What.** `type Action interface { Do(context.Context) error }`. Executor bound via context value. `Tasks` is `[]Action` — trivially composable for sequential workflows.
+- **Why for us.** Phase 7 — sub-agent flows (login → navigate → click → screenshot) are sequential `Tasks`. No DSL invention needed.
+
+## 3. Event subscriptions — synchronous, context-scoped
+
+- **Where.** `chromedp.go:786-836`.
+- **What.** `ListenTarget`, `ListenBrowser` — callbacks invoked synchronously per event. Cancellation tied to ctx.
+- **Footgun.** Blocking I/O inside a listener **deadlocks the CDP loop**. Listeners must be fast-and-async (channel-send only).
+- **Why for us.** Phase 7. Document the non-blocking rule in our agent codebase loudly.
+
+## 4. Screenshot — pull-based; live screencast = raw CDP
+
+- **Where.** `screenshot.go:106-162`.
+- **What.** `CaptureScreenshot` is on-demand. For ≥10 fps live streaming, **chromedp doesn't help directly** — call `Page.startScreencast` via raw CDP commands and subscribe to `Page.screencastFrame`.
+- **Why for us.** Phase 7. For Computer Use we need the screencast path — chromedp gives us the wire (CDP target, message routing) but the screencast loop is custom.
+
+## 5. Input synthesis — clicks, keys, scroll
+
+- **Where.** `input.go:28-94, 166-192`.
+- **What.** Mouse clicks at coords or DOM nodes; keyboard via key encoding; viewport scroll honors device pixel ratio and modifiers.
+- **Why for us.** Phase 7. Direct fit for Computer Use action-injection — saves us writing our own CDP `Input.dispatchMouseEvent` wrappers.
+
+## 6. Browser lifecycle — pluggable Allocator
+
+- **Where.** `allocate.go`, `chromedp.go:122-220`.
+- **What.** `Allocator` interface abstracts launching. `ExecAllocator` runs a local Chromium process. **Context ownership rule:** cancel parent → close browser; cancel child → close tab only. Multi-tab via context inheritance.
+- **Why for us.** Phase 7 — we own Chromium launch flags (sandbox off inside microVM, screencast on). Allocator pattern keeps that clean.
+
+## 7. Pooling & routing — single conn, session-mux
+
+- **Where.** `browser.go:38-90, 269-337`.
+- **What.** One conn per browser; messages routed by session-ID. Sufficient for "one browser per sandbox" — our case.
+- **Why for us.** Phase 7 = direct fit. Phase 6 = **NOT directly usable** because L4 multiplexes many users' CDP across many sandboxes — that's a gateway, not a chromedp use case.
+
+## 8. Errors & cancellation — context-driven
+
+- **Where.** `errors.go`, `browser.go:182-240`.
+- **What.** Small set of domain-specific errors. Cancellation via standard ctx. **No built-in retry, no transparent reconnect.**
+- **Why for us.** Phase 7 — wrap with our own retry + reconnect for crashed-Chromium recovery.
+
+## 9. Trade-off vs raw CDP
+
+- **chromedp wins.** Action composition, input synthesis, multi-tab management, browser lifecycle.
+- **Raw CDP wins.** Screencast streaming, custom Target subscription, lowest-latency frame paths, smaller dependency footprint.
+- **Verdict for Phase 7.** Use **chromedp for control** (clicks, navigate, screenshots, DOM); use **raw CDP for screencast** (`Page.startScreencast` directly on the WS). chromedp exposes the conn for this hybrid use.
+- **Verdict for Phase 6.** Don't use chromedp in L4. L4 is a CDP **proxy** — it shouldn't parse CDP messages, just shovel WebSocket frames.
+
+## Phase-7 implementation checklist
+
+1. `chromedp.NewContext(parent)` — one per sandbox session.
+2. Launch flags: `--no-sandbox` (we are inside microVM), `--remote-debugging-port=...` (or use chromedp's own allocator).
+3. Action composition for `bash`/`python`/`view`/`click`/`type` MCP tools.
+4. **Custom screencast loop** — bypass chromedp Action API; subscribe to `Page.screencastFrame` events; forward binary to caller over WS at `/v1/cdp` or `/v1/screencast`.
+5. Listener discipline — channel-send only, no blocking I/O.
+6. Restart logic — chromedp gives none; we add reconnect + Chromium relaunch on crash.
+
+## Verdict
+
+- **Phase 7 agent:** adopt for control plane (clicks/navigate/etc); raw CDP for screencast.
+- **Phase 6 L4:** skip — use opaque WS proxy.

package/docs/future-architecture/research/08-microsandbox.md

@@ -0,0 +1,78 @@
+<!-- SPDX-License-Identifier: FSL-1.1-Apache-2.0 -->
+<!-- Copyright (c) 2025 Open Computer Use Contributors -->
+
+# 08 — microsandbox (single-node microVM daemon)
+
+> Source: [microsandbox/microsandbox](https://github.com/microsandbox/microsandbox). Rust, libkrun-based, single-node.
+> Reference for Phase 2 (HTTP pool-manager sidecar shape) and the optional DirectCHProvider analog (Phase 9+).
+
+## 1. REST/SDK surface — sandbox lifecycle
+
+- **Where.** `crates/microsandbox/lib/sandbox/mod.rs:95-150`.
+- **What.** Builder pattern: `builder() → create() / create_detached() → start() → stop() / kill()`. State persisted in SQLite. Status enum: `Running | Draining | Paused | Stopped | Crashed`.
+- **Why for us.** Phase 2 — direct template for our pool-manager HTTP API. Status enum especially — we'd add `Idle` (in pool) and `Leased` (assigned to session).
+
+## 2. Guest-agent wire protocol — CBOR over virtio-serial
+
+- **Where.** `crates/protocol/lib/message.rs:46-70`.
+- **What.** Binary framing: `[len: u32 BE][id: u32 BE][flags: u8][CBOR(...)]`. Message types: `Ready`, `ExecRequest`/`ExecStdout`/`ExecExited`, `FsRequest`/`FsResponse`, `Shutdown`. u32 correlation IDs.
+- **Why for us.** Phase 7 — useful comparison vs our HTTP+WS+vsock path. CBOR's binary efficiency is nice but HTTP+WS already wins us tool ecosystem (curl, devtools, easy debugging). Adopt the **correlation-ID pattern** for our streaming exec; skip the wire format.
+
+## 3. VMM abstraction — pluggable backends
+
+- **Where.** `crates/runtime/lib/vm.rs:1-50`.
+- **What.** Trait-based VMM backend. Microsandbox uses **libkrun (macOS-only)**; the trait is portable to Firecracker / QEMU / crosvm.
+- **Why for us.** Phase 9 — sets the template for our `Hypervisor` trait if we ever build a DirectCH/DirectFC provider. We **substitute libkrun with CH** as primary.
+
+## 4. CLI ↔ daemon — relay socket + reconnect
+
+- **Where.** `crates/cli/lib/commands/create.rs`.
+- **What.** Thin CLI spawns VMs as **detached child processes**; agent relay socket for CLI ↔ sandbox IPC (CBOR). Sandboxes persist in SQLite — CLI can reconnect post-exit.
+- **Why for us.** Phase 2 — we want a **persistent HTTP daemon** rather than CLI-spawned subprocesses (matches Docker socket replacement goal). Useful: the reconnect-via-DB pattern for crash recovery.
+
+## 5. Project layout — Rust workspace, mappable to Go modules
+
+- **Where.** Repo `Cargo.toml` workspace.
+- **What.** `microsandbox` (SDK) | `cli` | `protocol` (shared host↔guest) | `runtime` (guest) | `network` | `filesystem` | `image` | `db`.
+- **Why for us.** Phase 2/6 Go layout. Map directly:
+  - `microsandbox` → `pkg/sandboxmgr` (SDK / library).
+  - `cli` → `cmd/sandboxctl`.
+  - `protocol` → `pkg/agentproto` (shared).
+  - `runtime` → `cmd/agent`.
+  - `network` / `filesystem` / `image` / `db` → `internal/*`.
+- Compare with [coder's layout](./03-coder.md) §10 — both converge on the same shape, different language.
+
+## 6. Network model — smoltcp + policy
+
+- **Where.** `crates/network/lib/lib.rs`.
+- **What.** In-process **smoltcp** networking stack with policy enforcement (advanced). Per-sandbox IPs + per-rule egress.
+- **Why for us.** Phase 2 — **simpler approach**: TAP/TUN + iptables. Defer smoltcp until we have a strong reason (full userspace stack isolation in microVM).
+
+## 7. Image / template format
+
+- **Where.** `crates/image/lib/lib.rs`.
+- **What.** Standard OCI pulling + EROFS (read-only, compressed) base + ext4 writable overlay. Content-addressed layer cache. Snapshot export/import for fast clones.
+- **Why for us.** Phase 3 — EROFS as the read-only base for skill blobs is interesting (vs our planned squashfs). Worth comparing in `phase-3-research.md`.
+
+## 8. Persistence — SQLite (read/write pool split)
+
+- **Where.** `crates/db/lib/pool.rs`.
+- **What.** SQLite + WAL mode; **separate read pool (multi-conn) + write pool (single-conn)**. SeaORM ORM. Migrations versioned in code.
+- **Tables.** `sandbox`, `run`, `image_ref`, `layer`, `manifest`, `volume`, `sandbox_metric`.
+- **Why for us.** Phase 2 pool-manager sidecar — **SQLite is enough** for single-node PoC. The read/write pool split is a smart pattern even at SQLite scale.
+- **Phase 6.** Move to Postgres for HA L4 control plane (matches [coder's pattern](./03-coder.md) §7).
+
+## Adoption priorities
+
+| Phase | Take | Skip / substitute |
+|---|---|---|
+| 2 | Lifecycle state enum; correlation-IDs; SQLite r/w pool split; reconnect-via-DB | smoltcp networking (use TAP+iptables); CBOR wire (use HTTP+WS) |
+| 3 | EROFS base for read-only mounts (compare with squashfs) | OCI layer extraction internals — too coupled to libkrun |
+| 6 | Crate layout → Go module layout | libkrun integration |
+| 8 | VMM trait pattern | libkrun backend (substitute CH/FC) |
+
+## Skip notes
+
+- libkrun is **macOS-first**; for Linux production we go CH / FC.
+- Microsandbox is **beta**; don't treat as production reference, treat as design reference.
+- No multi-node coordination — we add etcd / Postgres in Phase 6+.

package/docs/future-architecture/research/09-agentbox.md

@@ -0,0 +1,135 @@
+<!-- SPDX-License-Identifier: FSL-1.1-Apache-2.0 -->
+<!-- Copyright (c) 2025 Open Computer Use Contributors -->
+
+# 09 — Michaelliv/agentbox (egress proxy reference)
+
+> Source: [Michaelliv/agentbox](https://github.com/Michaelliv/agentbox). Python asyncio reference for JWT-allowlist egress proxy. Companion blog: https://michaellivs.com/blog/sandboxed-execution-environment/.
+> Direct input for [Phase 8](../roadmap.md).
+
+## 1. JWT — HS256, allow-list as comma-delimited claim
+
+- **Where.** `agentbox/sandbox_manager.py:133-165`.
+- **Shape.**
+  ```text
+  Header:  {"typ":"JWT","alg":"HS256"}
+  Payload: {
+    "iss":"sandbox-egress-control",
+    "session_id":"uuid",
+    "tenant_id":"optional",
+    "allowed_hosts":"pypi.org,github.com,*.example.com",
+    "exp": now + 4h
+  }
+  Signature: HMAC-SHA256(header.payload, signing_key)
+  ```
+- **Why for us (Phase 8 MVP).** Stateless; proxy verifies signature + expiry, no DB round-trip. 4-hour `exp` matches our session-lifetime cap (cross-cutting pattern 16).
+- **Production note.** HS256 = shared symmetric key — works when proxy + L4 are colocated. For untrusted-host scenarios switch to **RS256** with public-key distribution (proxy only needs the public key).
+
+## 2. Allowlist matching — wildcard suffix + port stripping
+
+- **Where.** `agentbox/egress_proxy.py:130-151`.
+- **Semantics.**
+  - Exact match: `"github.com" == "github.com"`.
+  - Wildcard suffix: `"*.github.io"` matches `"user.github.io"` AND `"github.io"` itself.
+  - Port stripped: `"pypi.org:443"` → `"pypi.org"`.
+- **Footguns.**
+  - No IP-literal blocking (allowlist is hostname-only).
+  - `*.com` matches **any** `.com` — relies on admin discipline.
+  - No double-wildcard (`**.example.com` not supported).
+- **Port to Go.** `strings.HasSuffix`. Add RFC-1123 validation to reject malformed entries.
+
+## 3. CONNECT proxy (HTTPS) — bidirectional pipe
+
+- **Where.** `agentbox/egress_proxy.py:153-222`.
+- **Flow.** Client `CONNECT host:port HTTP/1.1` → proxy verifies host + token → `200 Connection Established` → two asyncio tasks pipe 8KB chunks both ways until EOF.
+- **Why for us.** Phase 8 — HTTPS is opaque to L7 inspection; CONNECT is the only practical path.
+- **Production gaps.** No timeout on pipe (slow upload hangs forever). No bytes-transferred audit. No rate-limit. Exceptions silently close (no detail to client).
+
+## 4. HTTP proxy (non-HTTPS) — Host-header filter + header sanitization
+
+- **Where.** `agentbox/egress_proxy.py:224-292`.
+- **What.** Parses request URL (HTTP/1.1 absolute-form), validates host, strips `Host`, `Proxy-Authorization`, `Proxy-Connection`, forwards request body verbatim. Returns full response (no streaming — loaded in memory).
+- **Why for us.** Phase 8 fallback for plaintext HTTP (rare but possible). Skip the in-memory load for production — use streaming.
+
+## 5. Proxy auth wire format — `Basic base64(sandbox:jwt_<token>)`
+
+- **Where.** `agentbox/egress_proxy.py:91-113`.
+- **Container wire-up.**
+  ```bash
+  HTTP_PROXY=http://sandbox:jwt_<token>@proxy_host:15004
+  HTTPS_PROXY=http://sandbox:jwt_<token>@proxy_host:15004
+  ```
+- **Why for us.** Phase 8 — sandbox just sets env vars; any HTTP client (curl, requests, urllib, npm, pip) picks it up automatically. The `jwt_` prefix distinguishes from password auth.
+- **Production note.** Proxy URL over cleartext is a vulnerability across untrusted networks. Phase 8 MVP runs proxy on loopback; production puts proxy behind mTLS or a Unix socket if cross-network.
+
+## 6. Session lifecycle — JWT on session create, no refresh
+
+- **Where.** `agentbox/sandbox_manager.py:167-178` + `:254-320`.
+- **Flow.** `CreateSession(allowed_hosts=[...])` → `_generate_proxy_jwt()` → `_generate_proxy_url()` → injected into container's `HTTP_PROXY`.
+- **Why for us.** Phase 8 — token expires with session; no refresh needed at <1 K concurrent sessions.
+- **Limitation.** Container outliving 4-hour token → silent network fails. For long sessions, add a `/refresh` endpoint that mints a new JWT from existing session_id.
+
+## 7. Audit logging — stderr only, unstructured
+
+- **Where.** `agentbox/egress_proxy.py:173, 256`.
+- **Today.**
+  ```python
+  logger.info(f"Proxying CONNECT to {host}:{port}")
+  logger.info(f"Proxying {request.method} to {url}")
+  logger.warning(f"Blocked CONNECT to {host}:{port}")
+  ```
+- **Gaps for our Phase 8.**
+  - No request ID / correlation across proxy + container.
+  - No bytes transferred / latency.
+  - `tenant_id` in JWT but **not logged** — we must add it for multi-tenant audit.
+  - Blocked = log host but not reason (typo vs. missing entry).
+- **Target.** Structured JSON: `{ts, session_id, tenant_id, target, port, verdict, reason, bytes_out, latency_ms, jwt_id}` → ship to immutable audit sink (matches cross-cutting pattern 10).
+
+## 8. Signing-key management — `secrets.token_hex(32)`, in-process
+
+- **Where.** `agentbox/sandbox_manager.py:76-86`.
+- **Today.** Auto-generated 256-bit hex if not provided via `SIGNING_KEY` env. Both manager + proxy must share it (loopback).
+- **Gaps.** No rotation; no versioning (rotation invalidates all live tokens); symmetric key compromise = total proxy compromise.
+- **Phase 4 + 9.** Source from our secret broker; rotate ≤ 90 d; consider RS256 + `kid` header for graceful rotation (old + new public keys overlap).
+
+## 9. DNS — client-driven (proxy trusts container's resolution)
+
+- **Where.** `agentbox/egress_proxy.py:176-177` — `asyncio.open_connection(host, port)` uses OS resolver.
+- **Implication.** Allowlist is hostname-based. **DNS rebinding** theoretically possible but mitigated because the client is *inside our sandbox* (we control its resolv.conf).
+- **For Phase 8 research.** Decide: trust container DNS (simpler) vs proxy-resolves-itself (defends against rebinding). E2B's three-port pattern ([`02-e2b-infra.md`](./02-e2b-infra.md) §6) is an orthogonal axis.
+
+## 10. Streaming perf
+
+- **Where.** `agentbox/egress_proxy.py:191-205`. 8 KB chunks, `await writer.drain()` for backpressure.
+- **Scale.** Single Python process handles ~1 K concurrent CONNECT tunnels. Per-tunnel saturates network bandwidth. CPU mostly idle.
+- **Go port wins.** Goroutines lighter than asyncio tasks → 10× concurrency. `io.Copy` (or `io.CopyBuffer` for chunk control). Add `TCP_NODELAY` for latency-sensitive paths.
+
+## Porting checklist (Python → Go for production)
+
+| Pattern | Today | Go equivalent | Production-ready? |
+|---|---|---|---|
+| JWT HS256 sign/verify | `hmac.new(..., sha256)` | `crypto/hmac` + `crypto/sha256` | ✓ (also add RS256) |
+| JWT lib | manual b64 + check | `github.com/golang-jwt/jwt/v5` | ✓ |
+| Wildcard match | `endswith` | `strings.HasSuffix` | ✓ |
+| CONNECT tunnel | asyncio bidi | goroutine pair + `io.Copy` | ✓ (add timeout) |
+| HTTP proxy | aiohttp | `httputil.ReverseProxy` | ✓ |
+| Basic-auth parse | `base64.b64decode` | `encoding/base64` | ✓ |
+| Session lifecycle | 4h, no refresh | Same + add `/refresh` | ✓ |
+| Logging | stderr | `zap` / `slog` JSON | ⚠ add structured |
+| Signing key | `secrets.token_hex` | `crypto/rand` | ✓ (rotate via KMS) |
+| DNS | OS resolver | OS resolver (or `net.Resolver`) | ✓ |
+
+## Production gaps to close in Phase 8
+
+1. **Token refresh endpoint** for sessions > 4 h.
+2. **Structured audit logging** → immutable sink with 90 d retention.
+3. **Per-tenant rate limiting** (token bucket).
+4. **RS256** alongside HS256.
+5. **Timeouts** on CONNECT pipes.
+6. **Graceful shutdown** that drains in-flight tunnels.
+7. **mTLS or Unix socket** for proxy access — never cleartext across networks.
+
+## Phase-9 strategy (locked)
+
+- **MVP**: keep agentbox in place — Python, HS256, 4 h JWT, simple allowlist.
+- **Port to Go** *after* MVP proves the JWT/allowlist semantics. Target: same wire format; bug-for-bug compatible token format so sandboxes don't have to change.
+- **Compose with E2B's three-port firewall** (see [`02-e2b-infra.md`](./02-e2b-infra.md) §6) — they're complementary: agentbox authorizes (who can egress where); E2B-style firewall filters protocols (no protocol confusion on non-HTTP ports).

package/docs/future-architecture/research/10-sysbox.md

@@ -0,0 +1,100 @@
+<!-- SPDX-License-Identifier: FSL-1.1-Apache-2.0 -->
+<!-- Copyright (c) 2025 Open Computer Use Contributors -->
+
+# 10 — sysbox (default L2 for internal/trusted tier)
+
+> Source: [nestybox/sysbox](https://github.com/nestybox/sysbox). User-namespace + procfs/sysfs emulation.
+> Already used by our current Helm chart (`RuntimeClass: sysbox-runc`). [Phase 5](../roadmap.md#phase-5--helm-hardening--kubernetesprovider) formalizes it as the default L2.
+
+## 1. Installation — `sysbox-deploy-k8s` DaemonSet
+
+- **Where.** `sysbox-k8s-manifests/sysbox-install.yaml:42-181`. Image `registry.nestybox.com/nestybox/sysbox-deploy-k8s:v0.7.0`.
+- **What.** Auto-installs binaries (`sysbox-runc`, `sysbox-fs`, `sysbox-mgr`) on labeled nodes; configures containerd/CRI-O; registers RuntimeClass. Tolerates `sysbox-runtime: not-running` during install; relabels `sysbox-runtime: running` post-success. Rolling update.
+- **Why for us.** Phase 5 — direct analog to [kata-deploy](./01-kata-containers.md#5-kata-deploy-daemonset--installcleanup-probes-node-affinity). Bundle into Helm dependencies.
+- **Footgun.** Requires privileged init container (unavoidable — patches systemd units and kernel modules). Pre-2.0.5 containerd → falls back to CRI-O; mandate **containerd v2.0.5+** to skip that path.
+
+## 2. RuntimeClass — `sysbox-runc`
+
+- **Where.** `sysbox-install.yaml:173-180`.
+- **What.** `node.k8s.io/v1` RuntimeClass; handler = `sysbox-runc`. `nodeSelector: sysbox-runtime: running` pins pods to installed nodes.
+- **K8s ≥ v1.30 + containerd ≥ v2.0.5.** Supports formal user-namespace via `pod.spec.hostUsers: false` (cleaner than CRI-O's annotation `io.kubernetes.cri-o.userns-mode: "auto:size=65536"`).
+- **Why for us.** Phase 5 default template runtime.
+- **Footgun.** Pre-1.30 clusters → fall back to CRI-O annotation; document separately.
+
+## 3. What sysbox adds vs runc
+
+- **Where.** `README.md:19-62`, `design.md:1-45`, `dind.md:23-129`.
+- **Key gains.**
+  - **User-namespace isolation** — root inside container = `nobody:nogroup` on host.
+  - **procfs / sysfs virtualization** — FUSE-mounted by `sysbox-fs`; hides host resources; container-local sysctl.
+  - **Immutable rootfs mounts** — prevents mount-escape tricks.
+  - **DinD without `--privileged`** — inner Docker daemon runs unprivileged.
+- **For us.** Phase 5 internal tier — VM-class isolation without VM cost, ~50 ms cold start, ~5 MB RAM overhead.
+- **NOT enough alone for untrusted.** Kernel CVEs still apply → pair with kata-ch (Phase 9).
+
+## 4. Component triad — `sysbox-runc`, `sysbox-fs`, `sysbox-mgr`
+
+- **Where.** `design.md:13-46`.
+- **What.**
+  - **`sysbox-runc`** — OCI runtime fork; per create/start/delete; gRPC client to sysbox-mgr.
+  - **`sysbox-fs`** — FUSE daemon; emulates `/proc`, `/sys`; resident for container lifetime.
+  - **`sysbox-mgr`** — stateful daemon; allocates per-container UID ranges from `/etc/subuid`, `/etc/subgid`; coordinates cgroup limits.
+- **For us.** Monitoring must track all three. gRPC failures between them are the failure mode. DaemonSet handles restart in k8s; on bare metal use `Restart=always` + throttling.
+
+## 5. systemd-in-container — works out of the box
+
+- **Where.** `design.md:198-225`, `dind.md:103-129`.
+- **What.** sysbox detects PID 1 = systemd and: allows `/proc/sys` writes (normally user-ns-blocked), auto-mounts cgroup v2, whitelists mount/umount. `command: ["/sbin/init"]` just works.
+- **For us.** Phase 5 — relevant if a template ever bundles multiple services. Use Nestybox-provided Ubuntu Jammy/Focal systemd-docker images as base.
+
+## 6. License — Apache 2.0 (CE only)
+
+- **Where.** `README.md:198-211`, `install-k8s.md:154-297` (EE marked DEPRECATED).
+- **What.** **Sysbox CE** = Apache 2.0. **Sysbox-EE** deprecated since May 2022 (Docker acquired Nestybox). EE distribution stopped.
+- **For us.** Compatible with our license policy ([ADR-0006](../adr/0006-no-agpl-no-bsl-dependencies.md)). Support is community / GitHub issues / Slack.
+
+## 7. Known CVEs (kernel-shared caveats)
+
+- **Where.** `security-cve.md:1-169`.
+- **Critical four.**
+
+  | CVE | Affects | Fix |
+  |---|---|---|
+  | CVE-2022-0185 (user-ns escape) | Kernel < 5.16 | Kernel ≥ 5.16 |
+  | CVE-2022-0847 (Dirty Pipe) | Kernel < 5.16.11 / 5.15.25 / 5.10.102 | Patched kernel |
+  | CVE-2022-0811 (CRI-O sysctl) | `sysbox-deploy-k8s` < v0.5.1 | DaemonSet ≥ v0.5.1 |
+  | CVE-2024-21626 (runc fd leak) | **NOT affected** — sysbox has user-ns fallback | — |
+
+- **For us.** Phase 5 — gate sysbox templates on `kernel-version: >=5.16` node label. Annual CVE audit.
+- **Why this is acceptable.** sysbox is OS-virtualization, not VM-isolation. We accept the trade-off for **internal trusted** tier; eliminate it via kata-ch for **untrusted** (Phase 9).
+
+## 8. Containerd vs CRI-O integration
+
+- **Where.** `install-k8s.md:90-108`.
+- **What.** K8s ≥ 1.30 + containerd ≥ 2.0.5 → OCI runtime spec, drops `sysbox-runc` into `/usr/bin/`, updates `config.toml`. Older → falls back to **customized CRI-O** (heavier, requires kubelet restart).
+- **For us.** **Mandate K8s ≥ 1.30 + containerd ≥ 2.0.5** in Helm pre-install hook. Hard requirement, not soft recommendation.
+
+## 9. Performance
+
+- **Where.** `README.md:324-340`, `dind.md:199-204`.
+- **What.** Cold start ~50 ms (vs runc 30 ms). RAM overhead ~5 MB / pod (vs runc 2 MB, gVisor 15–25 MB). CPU overhead negligible. Inner-container network has slight overhead due to extra bridge.
+- **For us.** Phase 5 SLO budgets — 50 ms pod-spawn is fine. 5 MB × 1000 pods = 5 GB host RAM (acceptable).
+
+## 10. Operator footguns
+
+| Don't | Why | Do |
+|---|---|---|
+| Mount host `/var/lib/docker` into container | Breaks isolation; concurrent cache violations | Let inner Docker manage its own |
+| Configure inner Docker with userns-remap | Not supported; redundant with sysbox user-ns | Leave default |
+| Share inner Docker data-root across containers | Lock contention → failures | sysbox-mgr errors out anyway |
+| Skip `hostUsers: false` (or CRI-O annotation) | Pod runs root w/o user-ns — half the security gone | Always set it |
+| Run on kernel < 5.4 | Sysbox unsupported | Kernel ≥ 5.16 (for CVEs above) |
+
+## Adoption checklist for Phase 5
+
+1. Add `sysbox-deploy-k8s` DaemonSet to Helm chart (or document as prereq).
+2. Helm pre-install hook: validate `kubectl version ≥ 1.30` + containerd ≥ 2.0.5 + kernel ≥ 5.16 on a sample of nodes.
+3. Default template: `runtimeClassName: sysbox-runc`, `hostUsers: false`.
+4. Document footguns in `values.yaml` comments.
+5. Plan kernel ≥ 5.16 enforcement via node label + scheduler taint (Phase 5 acceptance).
+6. Phase 9: layer kata-ch beside sysbox for untrusted tier.

package/docs/future-architecture/research/11-firecracker-containerd.md

@@ -0,0 +1,93 @@
+<!-- SPDX-License-Identifier: FSL-1.1-Apache-2.0 -->
+<!-- Copyright (c) 2025 Open Computer Use Contributors -->
+
+# 11 — firecracker-containerd (FC via containerd + COW snapshotter)
+
+> Source: [firecracker-microvm/firecracker-containerd](https://github.com/firecracker-microvm/firecracker-containerd). AWS's containerd integration for Firecracker.
+> Relevant for [Phase 9](../roadmap.md) (kata-fc alternative path) and [Phase 10](../roadmap.md#phase-10--snapshotrestore--multi-region) (COW snapshotting for fast cold-start / warm pool).
+
+## 1. Demux snapshotter — out-of-VM proxy ⭐
+
+- **Where.** `snapshotter/README.md`; `snapshotter/demux/snapshotter.go` (Prepare:109, Commit:145, Remove:159, Usage:77); `snapshotter/app/service.go`; cache: `snapshotter/demux/cache/cache.go`.
+- **What.** containerd snapshotter plugin that proxies snapshot ops (Prepare/Commit/Remove/Mounts) **over vsock** to remote snapshotters running **inside** the microVM. In-VM snapshotter resolves via `GET /address?namespace={vmid}` → vsock socket path + metrics port.
+- **Why for Phase 10.** **The** enabler for COW rootfs and warm-pool cold-start. Workflow:
+  1. Prepare snapshot from parent (immutable base image) → CoW view.
+  2. Commit on container exit → releases snapshot resources.
+  3. All I/O through in-VM snapshotter for block-level dedup.
+- **For us.** Reference for our snapshot strategy in Phase 10 — even if we go with Cloud Hypervisor primary, this is the **architectural pattern** for "snapshotter inside the VM, control plane outside".
+
+## 2. vsock + TTRPC agent ↔ shim handshake
+
+- **Where.** Shim: `runtime/service.go` (vmReady channel, `agentClient taskAPI.TaskService` at line 138, vsock port allocation 74–76). Agent: `agent/service.go` (TaskService wrapping runc 46–72). Proto: `proto/firecracker.proto` (CreateVM, PauseVM, ResumeVM, StopVM, GetVMInfo, SetMetadata). Dial pattern: `runtime/service.go:~607` (`vsock.DialContext`).
+- **What.**
+  1. **VM bootstrap** — `CreateVM` spins up FC, waits for agent on vsock (vmReady channel).
+  2. **Task routing** — Create/Exec/Delete/Kill from shim → agent over ttrpc-vsock.
+  3. **Port allocation** — per-container unique vsock I/O port (min 11000, allocated at runtime/service.go 432–443).
+  4. Agent **wraps `runc.New()`** (agent/service.go:99) — forwards containerd task API directly. Containers-in-VMs transparent to the containerd control plane.
+- **Why for us.** Phase 9 — exact model for how a host-side shim talks to an in-VM agent. We adopt the **bootstrap timing + vsock port lifecycle** pattern; we **skip TTRPC** in favor of HTTP+WS (per ADR direction).
+
+## 3. Control API — VM lifecycle ≠ task lifecycle
+
+- **Where.** `proto/firecracker.proto` (CreateVMRequest, CreateVMResponse), `firecracker-control/service.go`, `runtime/service.go`.
+- **What.** Two-layer API:
+  - **VM lifecycle** (control plugin) — long-lived, multi-container.
+  - **Task lifecycle** (V2 runtime shim) — per-container, short-lived.
+  - **Reuse pattern**: orchestrator calls `CreateVM` once per workload group → VMID reused for N task creates → mounts different drives per task → **`ExitAfterAllTasksDeleted: true`** auto-cleans the VM when last task exits.
+- **vs Kata.** Kata creates 1 VM per pod (1:1). firecracker-containerd reuses 1 VM across M tasks (1:M) → much higher density for short-lived workloads.
+- **For us.** Phase 9 — **interesting alternative** to the per-session VM model. Trade-off: 1:M reuse → less per-session isolation. Use only for tightly-related batches inside same tenant; never across tenants.
+
+## 4. Drive mounting — pre-allocated stubs + dynamic updates
+
+- **Where.** `proto/firecracker.proto` (RootDrive, DriveMounts, ContainerCount); `runtime/service.go:CreateContainerStubs()`; `agent/drive_handler.go` (in-VM mount handler, MountDrive TTRPC).
+- **What.** Firecracker has **no hot-plug**. Workaround:
+  1. Runtime pre-allocates N stub drive files on VM creation (`ContainerCount`).
+  2. At task-creation, runtime updates `FirecrackerConfig.Drives[i].Path` to actual container image **while VM runs**.
+  3. CoW via the demux snapshotter (§1) — each container's rootfs is a unique snapshot.
+- **For us.** Phase 10 warm-pool insight: even Firecracker's no-hot-plug limit can be worked around with **pre-allocation**. One VM with 32 stub drives = 32 sequential containers without reboot.
+
+## 5. Network setup — TC redirect + CNI chain
+
+- **Where.** `docs/networking.md` (rationale 62–110), `runtime/service.go:1031-1046` (NetworkInterfaces).
+- **What.** Linux Traffic Control U32 filter redirects packets between VM's TAP device ↔ veth in a CNI-configured netns. CNI chain: `[ptp (veth) → tc-redirect-tap (redirect veth ↔ tap)]`.
+- **Why.**
+  - **TC redirect** = ~10–20 % CPU savings vs bridge.
+  - **Chained CNI** = composable policy (DNS via host-local IPAM, internet via `ipMasq=true`).
+  - **Per-VM netns isolation** = multi-tenant ready.
+  - **No VM IP needed** — TC redirect lets guest see same MAC/IP as veth → DHCP-free boot.
+- **For us.** Phase 9 — reference network pattern when wiring kata-fc templates; documents how CNI chains compose under Firecracker.
+
+## 6. Metrics & logging — FIFOs + HTTP discovery for snapshotter
+
+- **Where.** `proto/firecracker.proto:40-41` (LogFifoPath, MetricsFifoPath); `docs/logging.md` (per-library log levels); `snapshotter/README.md` (Prometheus `GET /metrics/{port}`).
+- **What.** FC metrics + logs → named pipes (FIFOs). Snapshotter metrics discovered via HTTP resolver. Per-library log levels (`firecracker:debug`, `firecracker-containerd:error`, etc.).
+- **For us.** Phase 10 warm-pool health — drain FIFOs periodically; alert on stall. Use snapshotter metrics for CoW efficiency (snapshot count, dedup ratio).
+
+## 7. Task lifecycle — cleanup-stack pattern
+
+- **Where.** `agent/service.go` (`execCleanups` map 50–51, `addCleanup`/`doCleanup` 132–150); `runtime/service.go`.
+- **What.** Each Create registers rollback handlers; on failure or Delete, run in **reverse order**. Multi-container per VM works because `ExitAfterAllTasksDeleted` is checked before VM shutdown.
+- **For us.** Phase 9 — clean pattern for "any step of sandbox-create fails → unwind cleanly". Same shape as E2B's multi-resource rollback ([`02-e2b-infra.md`](./02-e2b-infra.md) §4).
+
+## 8. When to pick this over kata-fc?
+
+| Dimension | firecracker-containerd | kata-fc |
+|---|---|---|
+| VM : task | 1 : M | 1 : 1 |
+| Cold start | CoW via demux snapshotter | devmapper snapshots |
+| Network setup | Manual CNI + TC redirect | Kata handles CNI |
+| Warm pool fit | **Excellent** | Good |
+| Boot latency | ~100 ms | 200–400 ms |
+| K8s native | Indirect (containerd) | Direct (RuntimeClass) |
+
+**Use firecracker-containerd when** workload is many-short-tasks-per-VM (serverless-shaped); snapshotter-driven cold-start matters; want containerd API without k8s overhead; need <100 ms cold start via VM reuse.
+
+**Use kata-fc when** target is Kubernetes (CRI-standard, RuntimeClass); 1 VM : 1 pod is acceptable; want mature ecosystem.
+
+**Our default = kata-fc** (Phase 9). firecracker-containerd is on the table for a future high-density tier where a single trusted-tenant batch can share one VM (rare; doesn't match Computer Use's per-session model).
+
+## Phase-10 takeaways
+
+1. **Demux snapshotter** is the architectural pattern for fast cold start — *snapshotter lives inside the VM, control plane outside*. Adapt to Cloud Hypervisor + virtio-fs in our snapshot pipeline.
+2. **Pre-allocated stub drives** work around hypervisor hot-plug limits — useful template-design knowledge.
+3. **Cleanup-stack pattern** standardizes rollback across our spawn pipelines.
+4. **FIFOs drain in real time** — observability pipeline must keep up.