@mndrk/agx 2.0.48 → 2.0.49

package/cloud-runtime/standalone/vault/agx/issues/ESO-327/design-doc.md

@@ -0,0 +1,202 @@
+# ESO-327: Sandbox, Onboarding & Auth for app.runagx.com
+
+**Status:** Draft v2 — revised after feedback  
+**Date:** 2026-04-08  
+**Author:** Jane
+
+---
+
+## Core Premise
+
+app.runagx.com is a **hosted runtime** — it runs agents server-side in sandboxed containers. This is not just a dashboard. The architecture follows agx-game's proven three-tier container model.
+
+---
+
+## Architecture: Three-Tier Container Model
+
+Directly adapted from agx-game's production setup:
+
+```
+┌─────────────────────────────────────────────────┐
+│  Relay (public API / app.runagx.com)            │
+│  - Auth (Clerk JWT)                             │
+│  - Company registry & membership                │
+│  - Container lifecycle management               │
+│  - WebSocket/WebRTC proxy                       │
+└────────────┬───────────────┬────────────────────┘
+             │               │
+    ┌────────▼────┐   ┌──────▼──────┐
+    │  Runtime    │   │  Runtime    │   (one per tenant)
+    │  Container  │   │  Container  │
+    │  - SQLite   │   │  - SQLite   │
+    │  - Engine   │   │  - Engine   │
+    │  - Tick     │   │  - Tick     │
+    └────────┬────┘   └──────┬──────┘
+             │               │
+    ┌────────▼────┐   ┌──────▼──────┐
+    │  Sandbox    │   │  Sandbox    │   (one per tenant)
+    │  Container  │   │  Container  │
+    │  - Agent    │   │  - Agent    │
+    │    tools    │   │    tools    │
+    │  - CLI exec │   │  - CLI exec │
+    └─────────────┘   └─────────────┘
+```
+
+### Relay (Public Tier)
+- Serves app.runagx.com (Next.js on Vercel or standalone)
+- Handles auth, company CRUD, membership/invites
+- Manages container lifecycle (create, start, stop, health check)
+- Proxies terminal sessions and browser streams to runtime containers
+- Communicates with Docker host via Tailscale (prod) or localhost (dev)
+
+### Runtime Container (Per-Tenant)
+- Runs the simulation engine: tick loop, task scheduling, run orchestration
+- Owns the SQLite database (single writer)
+- Launches agent runs via `docker exec` into the paired sandbox
+- Replicates DB as read-only to sandbox for agent context
+- Handles health checks, dead PID detection, state repair
+
+### Sandbox Container (Per-Tenant)
+- Long-lived execution environment for agents
+- Pre-installed tools: claude-code, codex, gemini-cli, gh, git, node, python
+- Runs as non-root `player` user (UID 1000)
+- Read-only access to company data (SQLite replica at mode 0o444)
+- Shared `/home/player` volume with runtime for file exchange
+
+---
+
+## Security Model
+
+### Isolation Boundaries
+| Layer | Mechanism |
+|-------|-----------|
+| Tenant isolation | Separate Docker containers per company (PID, network, filesystem namespaces) |
+| User privilege | Non-root `player` user in both containers |
+| Data protection | SQLite DB read-only in sandbox, writes only from runtime |
+| Network | Bridge network per tenant, no cross-tenant communication |
+| Resource caps | CPU: 2 cores (configurable), Memory: 4GB (configurable) |
+| Session limits | Max 2 terminal sessions, max 5 concurrent runs, 15min timeout per run |
+
+### Inter-Container Auth
+- Runtime ↔ Sandbox: HMAC-SHA256 shared secret per company
+- Token generation: `buildCompanyRuntimeToken(companyId, secret)`
+- Terminal sessions: Time-limited JWTs with ticket system
+
+### Known Limitations (inherited from agx-game)
+- Sandbox has passwordless sudo — suitable for semi-trusted agent execution
+- No seccomp/AppArmor profiles (standard Docker defaults)
+- Credentials stored in environment, not encrypted at rest
+- Shared volume between runtime and sandbox is trust-based
+
+**Decision needed:** Do we tighten these for app.runagx.com? Options:
+1. Ship with agx-game's current security posture (fast, proven)
+2. Remove sudo from sandbox, add seccomp profiles (slower, more secure for untrusted users)
+
+---
+
+## Auth & Onboarding
+
+### User Auth Flow
+1. User signs up / logs in at app.runagx.com via **Clerk**
+2. Clerk JWT validated by relay backend (JWKS with 5min TTL cache)
+3. User creates or joins a **company** (tenant unit)
+4. Company containers provisioned on first access via `ensureReady()`
+
+### CLI Connection (`agx auth login`)
+1. CLI opens browser to `app.runagx.com/auth/cli`
+2. User authenticates via Clerk
+3. Server generates a scoped API token tied to the user + company
+4. Token returned to CLI via localhost callback
+5. CLI stores token at `~/.agx/credentials.json`
+6. Subsequent CLI commands authenticate via `Authorization: Bearer <token>`
+
+### Dev Mode Bypass
+- `AUTH_DISABLED=1` + loopback host check for local development
+- Matches agx-game's existing pattern
+
+---
+
+## Execution Lifecycle
+
+```
+User creates task (dashboard or CLI)
+  → Relay forwards to Runtime container
+    → SimulationService.step() ticks
+      → tickWorld() evaluates conditions, dequeues runnable tasks
+        → launchRun(RunRequest) builds execution plan
+          → docker exec -i -u player -w {workdir} {sandbox} {command}
+            → Agent runs (claude, codex, gemini, ollama)
+              → stdout/stderr streamed, exit code captured
+                → parseRunResult() extracts status, artifacts
+                  → applyRunResultToWorld() updates state
+                    → Results visible in dashboard
+```
+
+### Run Configuration
+```typescript
+interface RunRequest {
+  id: RunId;
+  threadId: ThreadId;
+  actorId: ActorId;
+  provider: "claude" | "codex" | "gemini" | "ollama" | "z.ai";
+  model?: string;
+  prompt: string;
+  cwd?: string;
+  metadata?: Record<string, unknown>;
+}
+```
+
+---
+
+## Infrastructure
+
+### Container Images
+- **Sandbox:** Ubuntu 24.04, Node 22, Python 3, git, gh, claude-code, codex, gemini-cli, tmux, ripgrep, etc.
+- **Runtime:** Ubuntu 24.04, Node 22, Docker CLI, Go (browser-streamer), Playwright/Chromium, FFmpeg
+
+### Deployment Topology
+- **Relay:** Vercel (or standalone Node) — public internet
+- **Docker Host:** Private server behind Tailscale — runs runtime + sandbox containers
+- **Communication:** Relay → Docker host via Tailscale; browser sessions via WebRTC (fallback: WebSocket)
+
+### Per-Tenant Resources
+- Volumes: `agx-home-{companyId}` (shared), `agx-state-{companyId}` (runtime only)
+- Containers: `agx-company-runtime-{companyId}`, `agx-company-sandbox-{companyId}`
+- Database: One SQLite file per tenant (WAL mode, single writer in runtime)
+
+---
+
+## Rollout Phases
+
+### Phase 1: Foundation
+- Fork agx-game's container infrastructure (Dockerfiles, compose configs, container service)
+- Adapt relay for app.runagx.com (strip game-specific simulation, keep container lifecycle)
+- Clerk auth integration
+- Basic dashboard: company creation, task list, run status
+
+### Phase 2: Agent Execution
+- Wire up run lifecycle (create task → execute in sandbox → stream results)
+- Terminal session proxy (WebSocket to sandbox)
+- CLI auth flow (`agx auth login`)
+- Provider configuration (user brings their own API keys)
+
+### Phase 3: Multi-Tenancy Hardening
+- Container health monitoring and auto-recovery
+- Resource limit tuning per plan tier
+- Usage metering (run count, compute time, storage)
+- Invite system and role-based access
+
+### Phase 4: Scale & Polish
+- Multi-host container scheduling (when single Docker host is insufficient)
+- Browser streaming (WebRTC, carried over from agx-game)
+- Billing integration
+- Cloud-native option evaluation (Fly.io Machines, etc.)
+
+---
+
+## Open Decisions
+
+1. **Security posture:** Ship with agx-game defaults or tighten for public SaaS?
+2. **Docker host provider:** Self-managed (Hetzner/OVH) vs. managed (Fly.io Machines)?
+3. **Billing model:** Per-run, per-compute-minute, or flat tier?
+4. **API key management:** Users provide their own LLM keys, or we proxy through a shared key with metering?