Skip to main content

📚 Coditect Sandbox Platform — Full Technical Architecture (L1 → L7)

🧭 Level 1 — Problem Statement & Context​

Coditect addresses the need for secure, autosaving, multi-runtime sandbox environments that support AI agents, ephemeral developer environments, and dynamic runtime workloads in a zero-trust cloud-native architecture.

Context:

  • Demand for ephemeral compute across AI and software engineering
  • Multi-tenant environments need strong isolation
  • Git-centric workflows require automatic snapshotting and history
  • Runtime targets include: containers (gVisor/Kata), microVMs, and WASM

🧠 Level 2 — High-Level Architecture​

🔹 Key Components:​

  • ui/: React — sandbox explorer and live logs
  • api/: FastAPI — secure JWT-authenticated backend
  • controller/: Go — CRD lifecycle and reconciliation
  • agent/: Python — container execution inside GCP Workstations
  • infra/: OpenTofu — GCP, IAM, WIF, GKE, Workstations
  • monitoring/: Prometheus + Grafana

🔁 System Flow:​

🔐 Level 3 — Security Architecture​

  • OAuth2 or Firebase-based OIDC login
  • JWT Access Tokens (5m), Refresh Tokens (7d)
  • mTLS between API and agent
  • Agent identity via GCP WIF with workload identity federation
  • GitHub tokens scoped and stored in GCP Secret Manager

🧩 Level 4 — Sandbox CRD & Controller​

CRD:​

apiVersion: coditect.io/v1alpha1
kind: Sandbox
metadata:
  name: sbx-abc123
spec:
  tenantID: tenant-a
  userID: user-x
  runtime: gvisor
  image: python:3.11
  limits:
    cpu: 1
    memoryMiB: 512
  timeoutSeconds: 600
  networkPolicy:
    blockNetwork: true
status:
  phase: Running
  logsURL: https://...
  autosaveURL: https://github.com/org/repo/tree/autosave/...

Controller Logic:​

  • Adds finalizers
  • Applies RuntimeClass
  • Cleans up autosave snapshot on deletion

⚙️ Level 5 — Runtime & Quota Enforcement​

RuntimeIsolation Layer
gvisorsyscall filter
kata-fcmicroVM (KVM)
wasmtimeWasm runtime sandbox
  • Quota set in JWT (sandbox_quota)
  • TTL set on CRD and enforced by agent/controller
  • Redis backend for active usage metering

🔁 Level 6 — Git Autosave Snapshot Engine​

  • Worktree used per sandbox branch
  • Daemon auto-commits every 30s
  • Pushes to autosave/<ticket>/<user>/<date>
  • Snapshots persisted on timeout, failure, destroy
git add . && git commit -m "autosave" && git push origin autosave/user-abc
  • Token TTL managed via Secret Manager and GitHub App

🔍 Level 7 — Observability & Threat Modeling​

Metrics:​

  • sandbox_active_total
  • container_cpu_usage_seconds_total
  • quota_utilization_ratio

Logs:​

  • API + Agent + Controller log sandbox_id, trace_id, user_id
  • Cloud Logging to GCS bucket coditect-audit-logs

Threats & Mitigations:​

ThreatMitigation
JWT ForgeryRS256 signed via KMS, short TTL
Sandbox breakoutgVisor/Kata + seccomp
Workstation impersonationmTLS + pinned CA + WIF
Quota exhaustion abuseAPI-side token gating + alerting

✅ This version includes complete system coverage, corrected syntax, and exportable structure.