@mseep/open-computer-use 1.0.0

package/docs/future-architecture/README.md

@@ -0,0 +1,152 @@
+<!-- SPDX-License-Identifier: FSL-1.1-Apache-2.0 -->
+<!-- Copyright (c) 2025 Open Computer Use Contributors -->
+
+# Future Architecture
+
+This directory is the **single source of truth for the target architecture and migration roadmap** of Open Computer Use. It supersedes the previous `docs/requirements/` (renamed to here on 2026-05-17; see [ADR-0007](./adr/0007-superseded-by-future-architecture.md)).
+
+The model is an internal runtime-agnostic, 4-layer design, adapted to our concrete codebase, constraints, and team preferences.
+
+## TL;DR
+
+- **4 layers:** Control Plane (L4) → Orchestrator/Provider (L3) → Sandbox Runtime (L2) → Guest Agent (L1).
+- **11-phase roadmap** (0, 0.5, 1–10). Each phase strips one specific blocker. **No phase breaks the Docker Compose PoC** — that's an [explicit non-blocking invariant](./roadmap.md#non-blocking-invariants).
+- **Order reshuffle** (post-review): egress proxy (now Phase 8) ships **before** Kata untrusted tier (now Phase 9) — otherwise "untrusted" is a lie.
+- **Locked decisions (ADRs):**
+  - **Languages:** Go control plane ([ADR-0001](./adr/0001-control-plane-language-go.md)); **Rust guest agent** ([ADR-0002](./adr/0002-guest-agent-language-go.md), rewritten 2026-05-18; matches the microVM-agent runtime stack).
+  - **Internal transport:** connect-go on L4↔L3; L3↔L1 re-evaluated at Phase 7 (connect-rust vs a WS-frame protocol) per [ADR-0008](./adr/0008-internal-grpc-external-rest-mcp.md).
+  - **External protocols:** MCP user-facing ([ADR-0005](./adr/0005-mcp-as-control-plane-gateway.md)); REST for admin; CDP/ttyd is WebSocket passthrough; optional dialect adapters per [ADR-0009](./adr/0009-external-protocol-dialects.md).
+  - **Deployment:** Docker-first then k8s ([ADR-0003](./adr/0003-docker-poc-first-then-k8s.md)); pluggable runtime via `RuntimeClass` ([ADR-0004](./adr/0004-pluggable-runtime-via-runtimeclass.md)).
+  - **Dependencies:** no AGPL/BSL ([ADR-0006](./adr/0006-no-agpl-no-bsl-dependencies.md)).
+  - **AWS Lambda:** inspiration, not runtime ([ADR-0010](./adr/0010-lambda-as-inspiration-not-runtime.md)).
+
+## Reference architectures we draw from
+
+- **AWS Lambda** ([`references.md`](./references.md) Lambda framing, [ADR-0010](./adr/0010-lambda-as-inspiration-not-runtime.md)) — pattern source for Firecracker tiering and snapshot-pool cold-start economics. Inspiration only.
+- **Snapstart-style hot-swap** (internal design note) — Phase 10 cold-start design.
+- **E2B `envd`** ([`research/02`](./research/02-e2b-infra.md)) — production-shape L1 comparison.
+- **Coder** ([`research/03`](./research/03-coder.md)) — multi-region workspace-proxy pattern.
+- **Per-phase research-then-sign-off cadence.** Every phase begins with a research pass against the public reference repositories listed under "Further reading" **and** the matching digest in [`research/`](./research/), produces `phase-N-research.md`, and requires owner approval before code starts. **Mandatory pre-read:** the matching phase row in [`antipatterns.md`](./antipatterns.md) — 36 antipatterns mapped to phases, each with our locked decision.
+
+## Document map
+
+**Live spec (read every phase):**
+
+```text
+docs/future-architecture/
+├── README.md                       ← you are here
+├── roadmap.md                      11 phases (0, 0.5, 1–10), invariants, failure modes, rollback
+├── antipatterns.md                 ⭐ operational decision log, per-phase index
+├── gaps.md                         Pre-mortem gap inventory (A–M); suggestions, not commitments
+├── design-notes.md                 Candidate solutions, not yet locked; sibling of gaps.md
+├── phase-template.md               Skeleton for phase-N-research.md and phase-N-plan.md
+├── references.md                   External repos + projects, annotated
+├── architecture/                   Target design — 4-layer spec
+│   ├── 01-layers.md                4-layer overview + ASCII diagram + mapping to today's code
+│   ├── 02-layer4-control-plane.md  Go service: MCP gateway, OIDC, admin UI, secret broker
+│   ├── 03-layer3-providers.md      SandboxProvider interface + Docker/K8s/Direct impls
+│   ├── 04-layer2-runtimes.md       runc / sysbox / gVisor / kata-fc / kata-ch matrix
+│   ├── 05-layer1-guest-agent.md    Rust agent contract, PID-1 duties, MCP tool exec
+│   ├── 06-storage.md               4-tier: image / squashfs skills / workspace / S3 user-data
+│   ├── 07-security.md              Threat model, secret rotation, egress, image signing, audit
+│   ├── 08-networking.md            NetworkPolicy default-deny, egress proxy, CDP routing
+│   ├── 09-templates.md             SandboxTemplate spec, tenant→template resolver
+│   └── 10-observability.md         Metrics, traces, audit log, SLOs
+└── adr/                            Locked decisions
+    ├── 0001-control-plane-language-go.md       (Phase 6 re-eval gate added 2026-05-18)
+    ├── 0002-guest-agent-language-go.md         (rewritten 2026-05-18: Rust, not Go)
+    ├── 0003-docker-poc-first-then-k8s.md
+    ├── 0004-pluggable-runtime-via-runtimeclass.md
+    ├── 0005-mcp-as-control-plane-gateway.md
+    ├── 0006-no-agpl-no-bsl-dependencies.md
+    ├── 0007-superseded-by-future-architecture.md
+    ├── 0008-internal-grpc-external-rest-mcp.md (Phase 7 gate tightened 2026-05-18)
+    ├── 0009-external-protocol-dialects.md
+    └── 0010-lambda-as-inspiration-not-runtime.md   (added 2026-05-18)
+```
+
+**Research archive (read at start of relevant phase only):**
+
+```text
+└── research/                       Per-repo digests; reference-only, decay OK
+    ├── 01-kata-containers.md          (Phase 7, 9)
+    ├── 02-e2b-infra.md                (Phase 2, 3, 6, 7, 8)
+    ├── 03-coder.md                    (Phase 6)
+    ├── 04-cloud-hypervisor.md         (Phase 9, 10)
+    ├── 05-firecracker.md              (Phase 9, 10)
+    ├── 06-agent-sandbox.md            (Phase 5)
+    ├── 07-chromedp.md                 (Phase 7)
+    ├── 08-microsandbox.md             (Phase 2, 9)
+    ├── 09-agentbox.md                 (Phase 8)
+    ├── 10-sysbox.md                   (Phase 5)
+    ├── 11-firecracker-containerd.md   (Phase 9, 10)
+    ├── 12-docker-socket-proxy.md      (Phase 2, 8)
+    ├── 14-e2b-desktop-and-surf.md     (Phase 7)
+    └── 18-open-webui-terminals-observed.md (Phase 6, 8)
+```
+
+## Further reading
+
+Public open-source projects studied for the patterns the phases reuse:
+
+```text
+kubernetes-sigs/agent-sandbox        github.com/kubernetes-sigs/agent-sandbox
+Michaelliv/agentbox                  github.com/Michaelliv/agentbox
+chromedp/chromedp                    github.com/chromedp/chromedp
+cloud-hypervisor/cloud-hypervisor    github.com/cloud-hypervisor/cloud-hypervisor
+coder/coder                          github.com/coder/coder
+e2b-dev/desktop                      github.com/e2b-dev/desktop
+e2b-dev/surf                         github.com/e2b-dev/surf
+e2b-dev/infra                        github.com/e2b-dev/infra
+Tecnativa/docker-socket-proxy        github.com/Tecnativa/docker-socket-proxy
+firecracker-microvm/firecracker      github.com/firecracker-microvm/firecracker
+firecracker-microvm/firecracker-containerd  github.com/firecracker-microvm/firecracker-containerd
+kata-containers/kata-containers      github.com/kata-containers/kata-containers
+microsandbox/microsandbox            github.com/microsandbox/microsandbox
+nestybox/sysbox                      github.com/nestybox/sysbox
+anthropic-experimental/sandbox-runtime  github.com/anthropic-experimental/sandbox-runtime
+```
+
+Each phase in [roadmap.md](./roadmap.md) carries a checklist of which of these to study before that phase's research doc is written. Don't read the repos cold — start from [`research/`](./research/) which has per-repo "what to take" digests with file:line citations.
+
+## Per-phase research-then-sign-off cadence
+
+Mandatory for **every** phase (not just the greenfield ones):
+
+1. **Pre-read.** Open [`antipatterns.md`](./antipatterns.md) — find your phase row — read every linked entry. These are PR-review checkpoints with our locked choice already filled in. Don't reintroduce them.
+2. **Research.** Investigate the listed public reference repos via their `research/` digest. External docs as needed.
+3. **Write `phase-N-research.md`** from [`phase-template.md`](./phase-template.md). Options, recommendation, trade-offs, success metrics.
+4. **Discuss + sign off with owner.** No code begins until approval.
+5. **Plan.** Invoke `gsd-plan-phase` to break the phase into atomic tasks. Result: `phase-N-plan.md`.
+6. **Execute** on a `dev/future-architecture/phase-N-*` branch.
+7. **Verify** against acceptance criteria.
+8. **Merge** into `dev/future-architecture` (default) or `main` (if independently shippable).
+9. **Retro.** If the phase revealed that an earlier phase was wrong, follow [roadmap.md § Failure modes](./roadmap.md#failure-modes--cross-phase-retros).
+
+## Branching strategy
+
+1. **This directory** (the docs + ADRs) lands on a docs branch and is **merged to `main`** as the locked source of truth. Pure docs, no code risk.
+2. **After merge**, all roadmap execution moves to a long-lived branch — proposed name `dev/future-architecture` — cut from `main`. `main` stays shippable.
+3. Each phase ships as a PR from `dev/future-architecture/phase-N-*` → `dev/future-architecture` (default), or → `main` directly if the phase is independently shippable and reversible (Phase 1 is the example: pure additive abstraction).
+4. `dev/future-architecture` is rebased on `main` regularly so production hotfixes never diverge.
+
+## What this document tree does NOT do
+
+- It is not user-facing docs — see `docs/INSTALL.md`, `docs/FEATURES.md`, `docs/CLOUD.md` for runtime-relevant content.
+- It is not a backlog — GitHub Issues for that.
+- It does not authorize any code change. Each phase has its own sign-off gate.
+- If a doc here conflicts with the running system, **the running system wins until that phase ships**.
+
+## Constraints inherited from the project
+
+- All text **English only** (project-wide rule).
+- License hygiene: no AGPL, no BSL in direct deps ([ADR-0006](./adr/0006-no-agpl-no-bsl-dependencies.md)).
+- Docker Compose PoC must keep working through every phase ([ADR-0003](./adr/0003-docker-poc-first-then-k8s.md)).
+- The MCP user-facing contract is frozen ([ADR-0005](./adr/0005-mcp-as-control-plane-gateway.md)).
+
+## Next steps
+
+1. Owner reviews + merges this directory.
+2. Cut `dev/future-architecture` from `main`.
+3. Invoke `gsd-new-milestone` for "future-architecture migration v1" anchored to [roadmap.md](./roadmap.md).
+4. Begin Phase 1: read antipatterns row → write `phase-1-research.md` from `phase-template.md`.

package/docs/future-architecture/adr/0001-control-plane-language-go.md

@@ -0,0 +1,80 @@
+<!-- SPDX-License-Identifier: FSL-1.1-Apache-2.0 -->
+<!-- Copyright (c) 2025 Open Computer Use Contributors -->
+
+# ADR-0001 — Control plane language: Go
+
+> Superseded by [`docs/architecture/adr/0012-implementation-language.md`](../../architecture/adr/0012-implementation-language.md), which carries the Go host-side decision forward on bank-readiness terms.
+
+- **Status:** Superseded
+- **Date:** 2026-05-17
+- **Deciders:** project owner
+- **Supersedes:** —
+- **Superseded by:** —
+
+## Context
+
+The current control plane (`computer-use-server/`) is Python FastAPI. The roadmap (`../roadmap.md`) cuts over to a greenfield control plane in Phase 6. We must commit to a language for that rewrite now, because every prior phase (Phases 1–5 inside Python) must avoid Python-only design choices that don't translate.
+
+Constraints:
+- Target deployment includes AWS and GCP managed k8s, on-prem RKE2, and Docker Compose for PoC.
+- Heavy k8s API interaction (`KubernetesProvider`, `agent-sandbox` CRDs).
+- MCP gateway must support long-lived streaming connections (CDP, ttyd, MCP responses).
+- Operator skill set on the project (owner explicitly stated preference and unfamiliarity with Rust).
+
+## Decision
+
+**The new control plane (Phase 6+) will be written in Go.**
+
+## Rationale
+
+- **k8s ecosystem fit.** `client-go` is the canonical k8s API client; every CRD controller, every k8s tool, every operator pattern is Go-first. `kubernetes-sigs/agent-sandbox` (our L3 CRD basis) is Go.
+- **Single SDK story across clouds.** AWS SDK v2 and GCP SDK are both mature in Go.
+- **Operator preference.** Project owner is comfortable with Go, not Rust. Code we can't maintain confidently is a liability.
+- **Static binary.** Trivial container packaging, easy ops.
+- **Streaming concurrency model.** Goroutines + channels map well to long-lived MCP/CDP WebSocket gateways.
+- **Boring choice.** Operations community knows Go-on-k8s; hiring is easier.
+
+## Alternatives considered
+
+### Stay with Python (FastAPI)
+- **Pro:** zero migration cost, current team velocity, MCP SDK ecosystem strong.
+- **Con:** k8s controller story is weak; long-running connections under GIL get hairy at scale; no static binary; type safety weaker for a long-lived production service.
+- **Verdict:** continue using Python through Phases 1–5 (refactor in place); rewrite in Go at Phase 6.
+
+### Rust
+- **Pro:** memory safety, smallest binary, fastest runtime, aligns with kata-agent's Layer-1 language preference. Would also let us share code between L1 (agent) and L4 (control plane).
+- **Con:** project owner is not productive in Rust; k8s ecosystem in Rust is immature (`kube-rs` exists but is a fraction of `client-go`'s coverage); slower iteration on a control-plane-heavy codebase.
+- **Verdict:** rejected for L4. L1 may revisit ([ADR-0002](./0002-guest-agent-language-go.md)).
+
+### TypeScript / Node
+- **Pro:** good for admin UI sharing types.
+- **Con:** worse k8s story than Go, weaker for long-lived streams, worse SDK story for AWS/GCP at the same depth as Go.
+- **Verdict:** rejected. Admin UI is a separate concern and can ship in TS independently.
+
+## Consequences
+
+**Positive:**
+- Phase 6 produces a long-lived, easy-to-operate binary.
+- Future hires and contributors have a familiar stack.
+- Direct path to writing a custom k8s controller if `agent-sandbox` CRDs need extension.
+
+**Negative:**
+- Phase 6 is a non-trivial rewrite (not just a port — design improves at the same time).
+- Bilingual maintenance period: Phase 6 runs Python and Go side-by-side until parity is reached.
+- L1 (Go) and L4 (Go) share a language; we lose the option to share *code* with a Rust L1 if that direction is later reconsidered.
+
+**Neutral:**
+- Interfaces (L4 ↔ L3, L3 ↔ L1) stay language-agnostic (HTTP/gRPC), so the L1 language decision ([ADR-0002](./0002-guest-agent-language-go.md)) is independent.
+
+## Verification
+
+- Phase 6 research doc (`phase-6-research.md`) must confirm web framework + k8s client + MCP-on-Go strategy before code starts.
+- Parity acceptance: integration tests (`tests/integration/test_mcp_*.py`) pass against the new Go endpoint unchanged.
+
+## Phase 6 re-evaluation gate (added 2026-05-18)
+
+[ADR-0002](./0002-guest-agent-language-go.md) flipped L1 to Rust after this ADR was accepted. That changes the two-language calculus referenced under "Negative consequences" above — we no longer have a single-language stack. Phase 6 research must therefore answer one extra question before Go code starts:
+
+> Given that L1 is Rust, does L4 still want to be Go? The default answer remains **yes** (k8s ecosystem fit, owner familiarity, streaming concurrency, hiring) and this ADR is **not pre-superseded**. The gate exists so the Phase 6 author cannot ship Go code without having considered the alternative explicitly.
+
+If Phase 6 research instead concludes that L4 should also be Rust, supersede this ADR rather than amending it.

package/docs/future-architecture/adr/0002-guest-agent-language-go.md

@@ -0,0 +1,84 @@
+<!-- SPDX-License-Identifier: FSL-1.1-Apache-2.0 -->
+<!-- Copyright (c) 2025 Open Computer Use Contributors -->
+
+# ADR-0002 — Guest agent language: Rust
+
+> Superseded by [`docs/architecture/adr/0012-implementation-language.md`](../../architecture/adr/0012-implementation-language.md), which carries the Rust guest-agent decision forward (this file keeps its `-go` filename for git-history continuity though the decision is Rust).
+
+- **Status:** Superseded (rewritten 2026-05-18; supersedes the prior Go decision recorded under the same number)
+- **Date:** 2026-05-18 (original 2026-05-17 version was Go-with-Rust-as-option; rewritten in place after the L1 protocol surface was prototyped and Rust proved the better starting point)
+- **Related:** [ADR-0001](./0001-control-plane-language-go.md), [ADR-0008](./0008-internal-grpc-external-rest-mcp.md)
+- **Filename note:** kept as `0002-guest-agent-language-go.md` for git-history continuity; the title and content are now Rust.
+
+## Context
+
+Phase 7 of the roadmap replaces today's Python entrypoint + in-image MCP server with a small static binary as PID 1. The candidate languages are **Rust** (kata-agent, msb-agent, Firecracker, Cloud Hypervisor) and **Go** (consistent with ADR-0001's L4 choice, E2B's `envd`).
+
+This decision matters more for L1 than for L4 because the in-sandbox agent is the **inner attack target**: untrusted code, prompt-injected agents, or compromised dependencies inside the sandbox all interact with L1 first. RCE in L1's HTTP / WS handling buys the attacker the agent's full powers (which are deliberately small, but still).
+
+The earlier (2026-05-17) version of this ADR picked Go for operator-preference reasons. That was written before we prototyped the concrete L1 protocol surface. With that material now in hand, Rust is the better starting point — it matches the precedent at every microVM-runtime project we depend on, and the L1 contract turns out to be a near-1:1 match for the established agent-in-microVM pattern.
+
+## Decision
+
+**Rust.** Phase 7 ships a Rust binary as the L1 guest agent. The crate footprint is the standard microVM-agent set: `tokio`, `hyper`, `tokio-tungstenite`, `tokio-vsock`, `ring`, `jsonwebtoken`, `clap`, `nix`, `serde_json`.
+
+Go stays on the table only as a **fallback** if the Phase 7 research gate (below) surfaces a concrete blocker we cannot route around.
+
+## Rationale (for Rust)
+
+- **Precedent at the runtime layer.** Every adjacent agent-in-microVM project is Rust: kata-agent, msb-agent, Firecracker, Cloud Hypervisor. We are not the first ones doing this; the language choice has been litigated.
+- **Memory safety on the RCE target.** L1's WS handler is a direct RCE target. Rust's safety class eliminates a category of bugs Go does not, and the small static-PIE binary surface is easier to audit.
+- **Smaller binary.** A comparable Rust agent is ~4 MB static-PIE; a Go equivalent would be 10–15 MB. For a binary that ships inside every sandbox image, the delta matters at scale.
+- **Async runtime fit.** `tokio` is excellent for L1's workload (long-lived WS, multiple streams, vsock).
+- **vsock crates are mature in Rust** (`tokio-vsock`). Go's vsock support exists but is less common.
+- **Protocol-shaped surface.** First-byte JSON-vs-JWT dispatch, Ed25519 verification with `ring`, capabilities negotiation — small, well-bounded primitives where Rust's ergonomics fit cleanly.
+- **Owner reconsideration.** The original ADR rejected Rust on owner-productivity grounds. After prototyping the protocol surface, the owner has flipped that call: the L1 surface is small and protocol-shaped, which is where Rust's friction is lowest.
+
+## What Go would have bought us (kept for the record)
+
+- **Single language across L4 + L1** with ADR-0001. Lost — but L4 ↔ L1 talks over a wire protocol, not shared code, so the loss is shallow.
+- **`chromedp` exists.** Mature direct-CDP client. Mitigation: Phase 7 research evaluates a Rust CDP client (`chromiumoxide`) or treats CDP as a pure WebSocket passthrough (see ADR-0008) and does not parse it on the L1 side.
+- **Operator familiarity.** Owner accepts the productivity hit on the L1 side; L4 stays Go ([ADR-0001](./0001-control-plane-language-go.md)) so the day-to-day operator surface is unchanged.
+
+## Decision gate (Phase 7 research)
+
+`phase-7-research.md` must confirm before code starts:
+
+1. **CDP driving from Rust.** `chromiumoxide` vs raw WebSocket passthrough — pick one and justify. No chromedp parity required if the L1 doesn't drive CDP itself.
+2. **Build & toolchain.** musl static-PIE target, cross-compile for `linux/amd64` and `linux/arm64`, reproducible builds.
+3. **vsock transport feasibility.** `tokio-vsock` on the runtimes we target (runc, sysbox, kata-fc, kata-ch). This also feeds the ADR-0008 Phase 7 gate.
+4. **MCP server hosting.** Rust MCP server libraries are younger than Go's; if the only mature one is unfit, decide whether to (a) hand-roll JSON-RPC dispatch, (b) accept the youngest mature crate, or (c) keep MCP termination in L4 and have L1 expose only the typed RPC.
+5. **Owner productivity check.** Honest assessment after spiking the agent skeleton.
+
+If answers favor Go, supersede this ADR with a new one (not by editing this file again). The interface ([05-layer1-guest-agent.md](../architecture/05-layer1-guest-agent.md)) is language-agnostic — L4 doesn't care.
+
+## Alternatives considered
+
+### Go (the prior decision under this number)
+- **Pro:** single language with L4, `chromedp`, E2B precedent, owner-familiar.
+- **Con:** Larger binary; weaker memory-safety story on the RCE target; out of line with every adjacent microVM-agent project.
+- **Verdict:** rejected as the *target* with a Phase 7 escape hatch. The original Go-leaning ADR text is preserved in git history (`git log` on this file).
+
+### Keep Python (status quo)
+- **Pro:** zero migration cost.
+- **Con:** big attack surface, no static binary, no vsock readiness, no realistic path to microVM Layer-1.
+- **Verdict:** rejected as the *target*. Python entrypoint stays as the transitional L1 through Phases 1–6.
+
+### C / C++
+- **Verdict:** rejected. Memory-safety properties worse than both Go and Rust; offers nothing they don't.
+
+## Consequences
+
+**Positive:**
+- L1 binary is smaller (target ~4–6 MB) and audit-able.
+- L1 lines up with kata-agent, msb-agent — known idioms, known crates.
+- Capabilities negotiation, Ed25519 JWT, first-byte dispatch are well-trodden patterns rather than novel work.
+
+**Negative:**
+- Two-language stack (Rust L1 + Go L4). On-call needs to read both. The wire boundary between them is the firewall: contracts in `.proto` / JSON, no shared code.
+- Slower L1 iteration vs. Go in the early Phase 7 weeks. Mitigated by the small surface area of the agent.
+- We give up `chromedp` — Phase 7 research must close that gap.
+
+**Neutral:**
+- ADR-0008's "connect-go on L3↔L1" line now reads "connect-rust" in effect. ADR-0008 has a Phase 7 gate ([its §"Negative"](./0008-internal-grpc-external-rest-mcp.md)) that already calls this out; the gate is tightened in the 2026-05-18 edit of that ADR.
+- ADR-0001 (L4=Go) stays unchanged. Its Phase 6 gate now also re-confirms Go-vs-Rust on the L4 side given that L1 went Rust.

package/docs/future-architecture/adr/0003-docker-poc-first-then-k8s.md

@@ -0,0 +1,37 @@
+<!-- SPDX-License-Identifier: FSL-1.1-Apache-2.0 -->
+<!-- Copyright (c) 2025 Open Computer Use Contributors -->
+
+# ADR-0003 — Deployment ordering: Docker PoC first, then any k8s
+
+- **Status:** Accepted
+- **Date:** 2026-05-17
+
+## Context
+
+The roadmap targets multiple deployment shapes: Docker Compose (PoC), RKE2 on-prem, AWS EKS, and other k8s flavors. We need to commit to an order so each phase has a clear target.
+
+User direction: *Docker PoC first, any k8s flavor second.*
+
+## Decision
+
+1. **Docker Compose is the PoC target.** Every phase must leave Compose runnable.
+2. **k8s is treated as flavor-agnostic.** Helm chart is the single artifact. RKE2 and AWS EKS are the two reference test targets; nothing in the code privileges one.
+3. **No flavor-specific shortcuts.** No EKS-only IAM dance baked into the chart, no RKE2-only manifest, no GKE-only autopilot tricks. Cloud-specific glue lives in Helm values overrides, never in templates.
+
+## Rationale
+
+- Compose is the fastest dev loop and the most reproducible PoC for community contributors. Breaking it imposes setup tax on everyone.
+- k8s flavor diversity is real: target deployments span on-prem (RKE2) and cloud-managed (EKS, GKE, AKS). One chart that works on any conformant k8s ≥ 1.28 maximizes reach.
+- The user explicitly does not want to prioritize one k8s flavor over another.
+
+## Consequences
+
+- Every PR must include "Compose still works" as part of acceptance.
+- Phase 5 (Helm hardening + KubernetesProvider) tests on **both** kind/k3d (local k8s) and a real RKE2 or EKS cluster before merge.
+- bare-metal-only L2 runtimes (kata-fc, kata-ch — Phase 9) require explicit bare-metal node pool — documented as a precondition, not assumed.
+
+## Alternatives considered
+
+- **k8s first, Compose deprecated** — rejected. Loses local dev story, community contributors hate it.
+- **Pick one k8s flavor** — rejected. User said "any k8s".
+- **Docker Compose forever** — rejected. Production tenancy / isolation / scale requires k8s.

package/docs/future-architecture/adr/0004-pluggable-runtime-via-runtimeclass.md

@@ -0,0 +1,34 @@
+<!-- SPDX-License-Identifier: FSL-1.1-Apache-2.0 -->
+<!-- Copyright (c) 2025 Open Computer Use Contributors -->
+
+# ADR-0004 — Pluggable runtime via Kubernetes RuntimeClass (and per-template selection)
+
+- **Status:** Accepted
+- **Date:** 2026-05-17
+
+## Context
+
+We need to swap L2 runtimes (runc / sysbox / gVisor / kata-fc / kata-ch) per template, not per cluster. Internal sandboxes go to sysbox; public Computer Use goes to kata-ch; dev goes to runc. All in the same cluster.
+
+## Decision
+
+- **In k8s:** runtime selection is `Pod.spec.runtimeClassName`, carried from `SandboxTemplate.runtime_class`.
+- **Outside k8s:** the provider (`DirectCHProvider`, `DockerComposeProvider`) honors the same field, mapping it to its native mechanism.
+- **No runtime detection.** Templates declare; cluster operators install the matching RuntimeClasses.
+
+## Rationale
+
+- `runtimeClassName` is the standard k8s primitive. No reinvention.
+- Per-template choice is what tenant tiering requires.
+- Separation of concerns: operators install runtimes (kata-deploy DaemonSet etc.); template authors choose them.
+
+## Consequences
+
+- Helm chart documents required RuntimeClasses per template.
+- Bare-metal node pool with taints required when any template uses `kata-*`.
+- Phase 5 ships with `sysbox` only; Phase 7 adds `gVisor`; Phase 9 adds `kata-fc` / `kata-ch`.
+
+## Alternatives
+
+- **Single cluster-wide runtime** — rejected, no tenant tiering possible.
+- **Custom CRD with runtime-detection** — rejected, reinvents RuntimeClass.

package/docs/future-architecture/adr/0005-mcp-as-control-plane-gateway.md

@@ -0,0 +1,34 @@
+<!-- SPDX-License-Identifier: FSL-1.1-Apache-2.0 -->
+<!-- Copyright (c) 2025 Open Computer Use Contributors -->
+
+# ADR-0005 — MCP stays the user-facing protocol; admin UI uses a separate API
+
+- **Status:** Accepted
+- **Date:** 2026-05-17
+
+## Context
+
+Today users (Open WebUI and direct clients) talk to us via MCP at `/mcp`. We're adding an admin UI for operators. We need to decide whether to unify on MCP or separate the surfaces.
+
+## Decision
+
+- **MCP** is the **only** user-facing protocol. Frozen contract — every phase preserves it.
+- **Admin UI** consumes a separate **REST/GraphQL** API on the same control-plane process, behind separate OIDC scope.
+- **No MCP-for-admin.** Admin operations don't fit JSON-RPC tool-call semantics well, and conflating roles raises auth blast-radius.
+
+## Rationale
+
+- MCP is the AI-tool protocol; designed for "agent calls tool". Admin operations ("list sessions", "rotate keys") are CRUD, not tool calls.
+- Separate APIs let auth scopes be distinct and minimal.
+- We don't fork MCP; we don't extend it with non-standard methods.
+
+## Consequences
+
+- L4 exposes two distinct HTTP routes: `/mcp` (MCP gateway) and `/admin/*` (admin API).
+- Admin UI is its own deployment / SPA; backend stays in Go control plane.
+- Open WebUI integration is unaffected.
+
+## Alternatives
+
+- **MCP-only (admin via custom MCP tools)** — rejected, abuses the protocol, mixes auth scopes.
+- **Two separate processes** — rejected for now; can split later if admin scale demands it.

package/docs/future-architecture/adr/0006-no-agpl-no-bsl-dependencies.md

@@ -0,0 +1,41 @@
+<!-- SPDX-License-Identifier: FSL-1.1-Apache-2.0 -->
+<!-- Copyright (c) 2025 Open Computer Use Contributors -->
+
+# ADR-0006 — No AGPL, no BSL in direct dependencies
+
+- **Status:** Accepted
+- **Date:** 2026-05-17
+
+## Context
+
+Our project is BUSL-1.1 (with MIT for select skills, per `CLAUDE.md`). Several adjacent projects in this space carry licenses that would either contaminate our codebase or restrict our ability to ship.
+
+## Decision
+
+**Disallowed in direct dependencies:**
+- **GPL v2 / v3** — copyleft, contaminates linked code.
+- **AGPL v3** — strongest copyleft, contaminates even SaaS use.
+- **BSL (Business Source License)** — not OSI-open-source; HashiCorp Nomad post-acquisition.
+
+**Allowed:** Apache 2.0, MIT, BSD-2/3, MPL 2.0, LGPL 2.1+ (link only).
+
+**Implications:**
+- **Daytona** (AGPL v3) — never adopted, even for reference patterns we'd copy code from.
+- **Nomad** (BSL) — no Nomad provider, no Nomad client in our stack. E2B's Nomad-specific code is *reference-only*.
+
+## Rationale
+
+- BUSL-1.1 + AGPL = legal headache for downstream users.
+- BSL isn't OSI-open-source; building on it limits our distribution flexibility.
+- Strict license hygiene now is cheaper than disentangling later.
+
+## Consequences
+
+- Every new direct dependency PR must include a license check.
+- CI should enforce a license-allowlist scan (Phase 5+ deliverable).
+- Some convenience tools are off the table; alternatives must be found (e.g., for Nomad-style scheduling we'd build on k8s instead).
+
+## Alternatives
+
+- **Allow AGPL via "mere aggregation" loophole** — rejected. Legal risk too high; the loophole is contested.
+- **Switch project license to AGPL** — rejected. Out of scope of this ADR.

package/docs/future-architecture/adr/0007-superseded-by-future-architecture.md

@@ -0,0 +1,37 @@
+<!-- SPDX-License-Identifier: FSL-1.1-Apache-2.0 -->
+<!-- Copyright (c) 2025 Open Computer Use Contributors -->
+
+# ADR-0007 — Old `docs/requirements/` superseded by `docs/future-architecture/`
+
+- **Status:** Accepted (historical note)
+- **Date:** 2026-05-17
+
+## Context
+
+The directory `docs/requirements/` previously held our k8s architecture and 6-phase roadmap (committed 2026-05-16). On 2026-05-17 we:
+
+1. Renamed the directory to `docs/future-architecture/` via `git mv` (history preserved).
+2. Rewrote the contents around the internal 4-layer model.
+3. Re-folded the old 6 phases into the new 10-phase roadmap.
+
+## Decision
+
+- `docs/requirements/` no longer exists. All references to it should point at `docs/future-architecture/`.
+- The old `roadmap.md` content is **not lost** — its phases live on as new phases 1, 3, 5, 8 (see [`../roadmap.md`](../roadmap.md)).
+- The old `k8s-architecture.md` 4-tier storage model lives on as [`../architecture/06-storage.md`](../architecture/06-storage.md).
+- The `RuntimeBackend` protocol sketch lives on as [`../architecture/03-layer3-providers.md`](../architecture/03-layer3-providers.md)'s `SandboxProvider`.
+
+## Why we didn't keep the old files as ADRs
+
+- They were *plans*, not decisions. The new docs supersede them entirely.
+- `git log --follow` preserves history; nothing is lost.
+- Keeping zombie files invites stale advice.
+
+## Verification
+
+```bash
+git log --follow docs/future-architecture/roadmap.md
+git log --follow docs/future-architecture/architecture/06-storage.md
+```
+
+Both should show pre-rename commits on `docs/requirements/roadmap.md` and `docs/requirements/k8s-architecture.md`.

package/docs/future-architecture/adr/0008-internal-grpc-external-rest-mcp.md

@@ -0,0 +1,106 @@
+<!-- SPDX-License-Identifier: FSL-1.1-Apache-2.0 -->
+<!-- Copyright (c) 2025 Open Computer Use Contributors -->
+
+# ADR-0008 — Internal transport: connect-go on L4↔L3 (Phase 7 picks L3↔L1). External: MCP + REST. CDP/ttyd: WebSocket passthrough.
+
+- **Status:** Accepted (Phase 7 gate tightened 2026-05-18 after [ADR-0002](./0002-guest-agent-language-go.md) flipped L1 to Rust)
+- **Date:** 2026-05-17 (original) · 2026-05-18 (Phase 7 gate edit)
+- **Related:** [ADR-0001](./0001-control-plane-language-go.md), [ADR-0002](./0002-guest-agent-language-go.md), [ADR-0005](./0005-mcp-as-control-plane-gateway.md)
+
+## Context
+
+The architecture has three transport boundaries that are too easy to conflate:
+
+1. **External, user-facing** — user agents and Open WebUI call us.
+2. **External, operator-facing** — admin UI calls us.
+3. **Internal** — L4 ↔ L3 ↔ L1.
+4. **External, opaque passthrough** — CDP frames and ttyd between user UI and the sandbox's Chromium.
+
+Until now docs said "HTTP/gRPC" everywhere — ambiguous. An industry-observed "HTTP+WS API" pattern describes a *user-facing* agent transport; for us L1 is internal, not user-facing. Different decomposition → different transport choice.
+
+## Decision
+
+| Boundary | Protocol | Rationale |
+|---|---|---|
+| User → L4 (agents, Open WebUI) | **MCP** (JSON-RPC over HTTP/WebSocket) | Frozen contract per [ADR-0005](./0005-mcp-as-control-plane-gateway.md) |
+| Admin UI → L4 | **REST** (OpenAPI-described) | Standard for SPAs, generates browser clients trivially, debuggable via curl/Postman |
+| L4 ↔ L3 (provider) | **connect-go** (mTLS) | Schema-first; gRPC streaming + Connect/HTTP-JSON from one `.proto`. L4 is Go ([ADR-0001](./0001-control-plane-language-go.md)). |
+| L3 ↔ L1 (agent) | **Open — Phase 7 picks** between connect-rust (typed `.proto` over vsock/TCP) and a WS-frame protocol over `tokio-vsock` | L1 is Rust ([ADR-0002](./0002-guest-agent-language-go.md), rewritten 2026-05-18); the language flip changes the trade-off vs. the original Go-era pick. Gate language below. |
+| User UI ↔ sandbox CDP/ttyd | **WebSocket passthrough** via L4 | L4 does **not** parse; shovels frames opaquely |
+
+**connect-go** specifically (not pure grpc-go):
+- Single server speaks **gRPC**, **Connect** (HTTP/2 framed), and **gRPC-Web** from one `.proto`.
+- HTTP/JSON variant lets us `curl` any internal RPC for debug, no `grpcurl` required.
+- Bidi streaming preserved.
+- Used by E2B's `envd` and by Connect's own production users.
+
+## What MCP looks like inside
+
+MCP wire format stays **opaque to L1**. L4 receives MCP JSON-RPC → translates to typed `connect-go` calls on L3 → L3 calls L1's `Exec(cmd, env, stdin) → stream<Output>` etc.
+
+Consequence: MCP semantics live **only** in L4 gateway. We can:
+- Change internal RPCs without touching the MCP contract.
+- Add a second user-facing protocol (e.g., direct gRPC API for power users) without rewriting internals.
+- Swap L1 implementations without MCP-side test changes.
+
+## CDP and ttyd are the exception
+
+Long-lived WebSocket from user UI → L4 → sandbox Chromium. L4 must **not** decode CDP messages — it consistently hashes the session ID to a sandbox pod and shovels frames in both directions. Reasons:
+
+- CDP messages are large (screencast binary frames) — parsing adds latency and zero value.
+- Schema is upstream-owned (Chrome team) — keeping us out of it = no version-lock.
+- Same shape applies to ttyd.
+
+## Alternatives considered
+
+### Pure grpc-go (no Connect)
+- **Pro:** Most "standard" gRPC stack.
+- **Con:** No HTTP/JSON debug path; needs `grpcurl`. Browser clients require gRPC-Web sidecar (Envoy/Connect anyway).
+- **Verdict:** Rejected. connect-go is a superset.
+
+### HTTP+WS everywhere (status quo, agent-transport style for L1)
+- **Pro:** Simpler tooling; works with stdlib.
+- **Con:** No schema enforcement; breaking changes hit at runtime. Bidi streaming via WebSocket is hand-rolled framing. Type safety lost across L4↔L3↔L1.
+- **Verdict:** Rejected for internal boundaries.
+
+### REST everywhere
+- **Pro:** Maximum debuggability.
+- **Con:** Streaming exec / events / metrics over REST is awkward (SSE works but is one-direction). Schemas via OpenAPI possible but weaker than `.proto` in our experience.
+- **Verdict:** Rejected for L4↔L3↔L1. Kept for admin UI.
+
+### gRPC + gRPC-Web (no Connect)
+- **Pro:** Standard.
+- **Con:** Needs Envoy or grpc-web translator. connect-go does this in-process.
+- **Verdict:** Rejected.
+
+## Consequences
+
+**Positive:**
+- One `.proto` per boundary; CI compiles it for both sides; breaking changes caught at build time.
+- Same Go server serves gRPC, Connect, and `curl` calls — no separate debug stack.
+- L1's agent contract becomes typed → cross-tier consistency (sysbox / gVisor / kata all serve same `.proto`).
+- MCP contract isolation → internal refactors don't risk the user-facing wire.
+
+**Negative:**
+- One more tool in the toolbox (`buf` for `.proto` linting, `connect-go` codegen). Worth it.
+- L1 agent must include connect-go runtime → slightly larger binary than raw HTTP server (~1–2 MB). Acceptable per [ADR-0002](./0002-guest-agent-language-go.md) targets (~5–10 MB total).
+- Phase 7 research must include "vsock + connect-go" feasibility — vsock transport for connect/gRPC is well-trodden but not zero-config. **Update (2026-05-18):** with L1 now in Rust ([ADR-0002](./0002-guest-agent-language-go.md)), the L3↔L1 leg is effectively **connect-rust** (not connect-go) **or** a WS-frame protocol over `tokio-vsock`. Phase 7 research must explicitly compare these two and pick one. The L4↔L3 leg stays connect-go (L4 is Go per [ADR-0001](./0001-control-plane-language-go.md)).
+
+**Neutral:**
+- Phase 6 research now picks connect-go as primary candidate; the framework choice section in `roadmap.md` narrows.
+- Existing Python `computer-use-server` keeps speaking HTTP/MCP unchanged — transition is at Phase 6 cutover.
+
+## Migration notes
+
+- **Phases 1–5 (Python orchestrator):** stay on Python HTTP; provider interface is in-process Protocol; HTTP transport between orchestrator and pool-manager sidecar.
+- **Phase 6 (Go control plane):** introduces `.proto` files for L4↔L3 boundary. Python orchestrator keeps working in parallel; new Go service serves both MCP gateway (external) and connect RPCs (internal).
+- **Phase 7 (Rust agent per [ADR-0002](./0002-guest-agent-language-go.md)):** L1 serves either connect-rust or a WS-frame protocol on vsock/TCP, decided by the Phase 7 research gate. L3 client compiled from the same `.proto` (connect path) or a hand-rolled WS client (WS-frame path).
+- **Phase 8 (egress proxy):** connect for L4↔proxy stats/control; egress traffic itself stays HTTP CONNECT (proxy is a TCP proxy, not RPC).
+- **Phase 9 (Kata):** vsock + connect-go validated.
+- **Phase 10 (HA / multi-region):** mTLS on all internal RPCs; cert rotation via cert-manager or equivalent.
+
+## Verification
+
+- Each phase's PR must include the `.proto` schema diff if any internal RPC changed.
+- `tests/integration/test_mcp_*.py` continue to call MCP and **do not** speak connect — proving the user-facing surface is unchanged.
+- Phase 6 acceptance: `curl -H "Content-Type: application/json" -X POST http://l4/api.v1.SandboxProvider/Spawn -d '{...}'` returns the same result as the typed gRPC call.