🧠 Coditect Sandbox Platform — Deep Technical Architecture (L5 Detail)

---

1. System Purpose and Core Philosophy

Coditect provides fine-grained, auditable, autosaved, resource-constrained sandbox environments across trusted and untrusted workloads. Designed for:

• AI agent toolchains
• Secure-by-default development workspaces
• LLM-autonomous code generation

It uses:

• Kubernetes RuntimeClasses (gvisor, kata-fc, wasmtime) for syscall-level isolation
• GCP Workstations for persistent, per-user compute
• CRDs + Git autosave for state management and history

---

2. Core Components Overview (L2)

Component	Language	Description
api/	Python	FastAPI service with JWT, autosave, quota, and token refresh
controller/	Go	CRD controller for Kubernetes sandbox orchestration
ui/	React	Web dashboard with log streaming, sandbox management
infra/	Tofu	Infrastructure as code (Workstations, secrets, cluster, WIF, scaling)
tests/	Python	Integration and lifecycle validation tests using envtest/pytest

---

3. Sandbox CRD (L5 Spec)

apiVersion: coditect.io/v1alpha1
kind: Sandbox
metadata:
  name: sbx-12345
spec:
  tenantID: tenant-a
  projectID: proj-x
  userID: user-xyz
  workstationID: ws-789
  runtime: gvisor  # or kata-fc, wasm
  image: python:3.11
  command: ["python3", "main.py"]
  env:
    TOKEN: $API_TOKEN
  limits:
    cpu: 1.0
    memoryMiB: 1024
  timeoutSeconds: 600
  idleTimeoutSeconds: 90
  networkPolicy:
    blockNetwork: true
    cidrAllowlist: ["10.0.0.0/8"]
status:
  phase: Running
  startedAt: 2024-01-15T10:00:00Z
  autosaveURL: https://github.com/org/repo/tree/autosave/...
  logsURL: https://.../logs/sandbox-xyz

Key Rules:

• Must be tenant- and project-bound
• Network is blocked by default unless allowlist is supplied
• Controlled via Coditect Agent or Go Controller

---

4. Token Strategy (L5 Detail)

Token Flow

• ID token (via Firebase/Auth0) → used to get refresh/access token pair
• Access token (short-lived) → used to access /sandboxes, /logs, /exec
• Refresh token → stored in browser (httpOnly secure cookie), triggers refresh before expiry

Token Lifecycle:

[ login ]
    ↓
[ ID token ] ———
               ↓
           [ Access token (5m) ]
               ↓        ↑
     /rebind, /create, etc.
               ↓        ↑
       [ Refresh token (7d) ]

JWT Claims:

{
  "sub": "user:uid-123",
  "aud": "sandbox-api",
  "tenant_id": "tenant-abc",
  "roles": ["sandboxer"],
  "sandbox_quota": 1800,
  "sandbox_id": "sbx-123",
  "workstation_id": "ws-456"
}

---

5. GCP Workstations (L5 Detail)

Structure

• 1 Workstation per user (sandbox-alice, sandbox-bob)
• Configurable via Tofu:
  • boot_disk_size_gb
  • machine_type (e.g., n2-standard-4)
  • runtime_environment: Docker, runsc, kata, wasmtime
• Deployed in clusters: sandbox-pool-us-central1

Agent Capabilities:

• gRPC API:
  • CreateSandbox(request: SandboxRequest)
  • StreamLogs(SandboxID)
  • SnapshotAndPush(GitTarget)
• Validates JWT and sends resource metrics upstream

---

6. Autosave Mechanism (L5 Spec)

Path structure:

/workspaces/<tenant>/<user>/<project>/

Snapshot Logic:

• Uses Git worktree to isolate sandbox commits
• Autosave daemon commits every 15–30s:

  git add . && git commit -m 'autosave' && git push origin autosave/<ticket>/<user>

• On destroy or timeout, commits final snapshot + push
• Supports branching:
  • autosave branches: autosave/<date>/<user>/<project>
  • snapshots reference: autosaveURL in CRD

---

7. Quota & Runtime Enforcement

Scope	Enforcement	Mechanism
User	Token claim	JWT sandbox_quota
Runtime	Pod runtime	RuntimeClass + node pool taint
CPU/Memory	Cgroup limits	Pod resources.limits
TTL	Agent/Controller	Idle reaper, kube TTL policy

Quota validation occurs:

• At API creation time (access token checked)
• In Coditect Agent pre-flight container launch
• In controller when applying CRD

---

8. Monitoring (L5 Grafana Metrics)

Collected Metrics:

• sandbox_active_total{runtime=...}
• container_cpu_usage_seconds_total{pod=...}
• container_memory_usage_bytes{pod=...}
• quota_used_percent{tenant=...}

Grafana Dashboards:

• Heatmap: CPU/mem per runtime
• Table: sandbox count per tenant/user
• Gauge: Quota used %

---

9. Deployment + CI/CD (L5 Detail)

Makefile:

make apply        # terraform init + apply
make deploy       # cloud build submit
make logs         # stream API logs
make port-forward # expose 8000, 3000 locally
make snapshot     # call snapshot endpoint

Cloud Build:

• Builds: api/, controller/, ui/
• Pushes to: gcr.io/<project>/sandbox-*
• Applies manifests under infra/gke/manifests/*.yaml

---

10. Security Posture Summary

• 🟢 JWT Zero-trust boundary enforcement
• 🟢 No pod creation via browser (agent/controller only)
• 🟢 GitHub access via scoped PAT + Secret Manager
• 🟢 Workstation agents are identity-bound via WIF
• 🟢 API and agents validate JWTs on all inbound requests

---