# tastyeffectco/sandboxd architecture

> Architecture diagram of the GitHub repository tastyeffectco/sandboxd, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/tastyeffectco/sandboxd
- Repository: https://github.com/tastyeffectco/sandboxd

## Overview

sandboxd is a self-hosted AI app-building engine with an optional browser console and a headless `/v1` API. A user creates an app from a prompt, starter, curated catalog entry, or public Git repository; the control plane provisions an isolated Docker sandbox, where an in-sandbox supervisor runs the app and coding agent. The app is exposed at a preview URL, and the console supports continued editing and Git push. README statements establish the main workflow and integrations; unsampled implementation details are represented only at documented subsystem level.

Main entry points: [`console/src/App.tsx`](https://github.com/tastyeffectco/sandboxd/blob/main/console/src/App.tsx) (Console shell), [`console/src/api.ts`](https://github.com/tastyeffectco/sandboxd/blob/main/console/src/api.ts) (API client), [`control-plane/cmd/sandboxd/main.go`](https://github.com/tastyeffectco/sandboxd/blob/main/control-plane/cmd/sandboxd/main.go) (Sandbox lifecycle), [`console/src/AppView.tsx`](https://github.com/tastyeffectco/sandboxd/blob/main/console/src/AppView.tsx) (App workspace)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_console["Web console"]
  node_console_app["Console shell<br/>[App.tsx]"]
  node_app_workspace["App workspace<br/>[AppView.tsx]"]
  node_catalog_view["App catalog<br/>[StoreView.tsx]"]
  node_catalog_data["Catalog data<br/>[catalog.ts]"]
  node_starter_data["Starter templates<br/>[starters.ts]"]
  node_brain_view["App overview<br/>[BrainGraph.tsx]"]
  node_brain_data["App structure<br/>[brain.ts]"]
  node_settings["Settings<br/>[SettingsView.tsx]"]
  node_deploy["Deploy controls<br/>[DeployModal.tsx]"]
  node_release_status["Release status<br/>[VersionPill.tsx]"]
  node_console_api["API client<br/>[api.ts]"]
end

subgraph group_control["Control plane"]
  node_engine_api["HTTP API<br/>[handlers.go]"]
  node_task_api["Agent tasks<br/>[v1_tasks.go]"]
  node_preview_auth["Preview access<br/>[preview_auth.go]"]
  node_sandbox_manager["Sandbox lifecycle<br/>[main.go]"]
  node_wake["Sleep and wake<br/>[handler.go]"]
end

subgraph group_sandbox["Sandbox runtime"]
  node_agent_runner["Coding agent<br/>[task.go]"]
  node_app_supervisor["App supervisor<br/>[main.go]"]
end

subgraph group_infra["State and routing"]
  node_docker["Docker containers<br/>[docker.go]"]
  node_state_store[("SQLite state<br/>[store.go]")]
  node_preview_router["Preview routing<br/>[traefik.go]"]
end

node_user(("User"))
node_preview(("Running app"))
node_git_service(("Git repository"))
node_api_consumer(("API consumer"))

node_user -->|"uses"| node_console_app
node_console_app -->|"opens"| node_app_workspace
node_console_app -->|"opens"| node_catalog_view
node_console_app -->|"opens"| node_settings
node_console_app -->|"opens"| node_brain_view
node_catalog_view -->|"lists"| node_catalog_data
node_app_workspace -->|"requests"| node_console_api
node_catalog_view -->|"installs via"| node_console_api
node_settings -->|"configures via"| node_console_api
node_console_app -->|"requests"| node_console_api
node_console_api -->|"calls &#96;/v1&#96;"| node_engine_api
node_api_consumer -->|"calls &#96;/v1&#96;"| node_engine_api
node_engine_api -->|"provisions"| node_sandbox_manager
node_sandbox_manager -->|"runs containers"| node_docker
node_sandbox_manager -->|"persists state"| node_state_store
node_sandbox_manager -->|"configures URLs"| node_preview_router
node_sandbox_manager -->|"starts in sandbox"| node_app_supervisor
node_task_api -->|"submits tasks"| node_agent_runner
node_agent_runner -->|"builds app"| node_app_workspace
node_app_supervisor -->|"serves app"| node_preview
node_preview_router -->|"routes URL"| node_preview
node_user -->|"views"| node_preview
node_git_service -.->|"imports repo"| node_console_api
node_app_workspace -->|"pushes changes"| node_git_service
node_wake -->|"starts sandbox"| node_docker
node_wake -->|"loads sandbox"| node_state_store
node_preview_auth -->|"authorizes access"| node_preview
node_console_app -->|"opens"| node_deploy
node_console_app -->|"shows upgrade"| node_release_status
node_brain_view -->|"renders"| node_brain_data
node_app_workspace -.->|"selects starter"| node_starter_data

click node_console_app "https://github.com/tastyeffectco/sandboxd/blob/main/console/src/App.tsx"
click node_app_workspace "https://github.com/tastyeffectco/sandboxd/blob/main/console/src/AppView.tsx"
click node_catalog_view "https://github.com/tastyeffectco/sandboxd/blob/main/console/src/StoreView.tsx"
click node_catalog_data "https://github.com/tastyeffectco/sandboxd/blob/main/console/src/catalog.ts"
click node_starter_data "https://github.com/tastyeffectco/sandboxd/blob/main/console/src/design/starters.ts"
click node_brain_view "https://github.com/tastyeffectco/sandboxd/blob/main/console/src/BrainGraph.tsx"
click node_brain_data "https://github.com/tastyeffectco/sandboxd/blob/main/console/src/brain.ts"
click node_settings "https://github.com/tastyeffectco/sandboxd/blob/main/console/src/SettingsView.tsx"
click node_deploy "https://github.com/tastyeffectco/sandboxd/blob/main/console/src/DeployModal.tsx"
click node_release_status "https://github.com/tastyeffectco/sandboxd/blob/main/console/src/VersionPill.tsx"
click node_console_api "https://github.com/tastyeffectco/sandboxd/blob/main/console/src/api.ts"
click node_engine_api "https://github.com/tastyeffectco/sandboxd/blob/main/control-plane/internal/api/handlers.go"
click node_task_api "https://github.com/tastyeffectco/sandboxd/blob/main/control-plane/internal/api/v1_tasks.go"
click node_preview_auth "https://github.com/tastyeffectco/sandboxd/blob/main/control-plane/internal/api/preview_auth.go"
click node_sandbox_manager "https://github.com/tastyeffectco/sandboxd/blob/main/control-plane/cmd/sandboxd/main.go"
click node_wake "https://github.com/tastyeffectco/sandboxd/blob/main/control-plane/internal/wake/handler.go"
click node_agent_runner "https://github.com/tastyeffectco/sandboxd/blob/main/control-plane/cmd/runtimed/task.go"
click node_app_supervisor "https://github.com/tastyeffectco/sandboxd/blob/main/control-plane/cmd/runtimed/main.go"
click node_docker "https://github.com/tastyeffectco/sandboxd/blob/main/control-plane/internal/docker/docker.go"
click node_state_store "https://github.com/tastyeffectco/sandboxd/blob/main/control-plane/internal/store/store.go"
click node_preview_router "https://github.com/tastyeffectco/sandboxd/blob/main/control-plane/internal/traefik/traefik.go"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_console_app,node_app_workspace,node_catalog_view,node_catalog_data,node_starter_data,node_brain_view,node_brain_data,node_settings,node_deploy,node_release_status,node_console_api,node_user toneBlue
class node_engine_api,node_task_api,node_preview_auth,node_sandbox_manager,node_wake toneAmber
class node_agent_runner,node_app_supervisor,node_api_consumer toneMint
class node_docker,node_state_store,node_preview_router toneRose
class node_preview,node_git_service toneIndigo
```

## Components

### Web console

- [Console shell](https://github.com/tastyeffectco/sandboxd/blob/main/console/src/App.tsx): `console/src/App.tsx`
- [App workspace](https://github.com/tastyeffectco/sandboxd/blob/main/console/src/AppView.tsx): `console/src/AppView.tsx`
- [App catalog](https://github.com/tastyeffectco/sandboxd/blob/main/console/src/StoreView.tsx): `console/src/StoreView.tsx`
- [Catalog data](https://github.com/tastyeffectco/sandboxd/blob/main/console/src/catalog.ts): `console/src/catalog.ts`
- [Starter templates](https://github.com/tastyeffectco/sandboxd/blob/main/console/src/design/starters.ts): `console/src/design/starters.ts`
- [App overview](https://github.com/tastyeffectco/sandboxd/blob/main/console/src/BrainGraph.tsx): `console/src/BrainGraph.tsx`
- [App structure](https://github.com/tastyeffectco/sandboxd/blob/main/console/src/brain.ts): `console/src/brain.ts`
- [Settings](https://github.com/tastyeffectco/sandboxd/blob/main/console/src/SettingsView.tsx): `console/src/SettingsView.tsx`
- [Deploy controls](https://github.com/tastyeffectco/sandboxd/blob/main/console/src/DeployModal.tsx): `console/src/DeployModal.tsx`
- [Release status](https://github.com/tastyeffectco/sandboxd/blob/main/console/src/VersionPill.tsx): `console/src/VersionPill.tsx`
- [API client](https://github.com/tastyeffectco/sandboxd/blob/main/console/src/api.ts): `console/src/api.ts`

### Control plane

- [HTTP API](https://github.com/tastyeffectco/sandboxd/blob/main/control-plane/internal/api/handlers.go): `control-plane/internal/api/handlers.go`
- [Agent tasks](https://github.com/tastyeffectco/sandboxd/blob/main/control-plane/internal/api/v1_tasks.go): `control-plane/internal/api/v1_tasks.go`
- [Preview access](https://github.com/tastyeffectco/sandboxd/blob/main/control-plane/internal/api/preview_auth.go): `control-plane/internal/api/preview_auth.go`
- [Sandbox lifecycle](https://github.com/tastyeffectco/sandboxd/blob/main/control-plane/cmd/sandboxd/main.go): `control-plane/cmd/sandboxd/main.go`
- [Sleep and wake](https://github.com/tastyeffectco/sandboxd/blob/main/control-plane/internal/wake/handler.go): `control-plane/internal/wake/handler.go`

### Sandbox runtime

- [Coding agent](https://github.com/tastyeffectco/sandboxd/blob/main/control-plane/cmd/runtimed/task.go): `control-plane/cmd/runtimed/task.go`
- [App supervisor](https://github.com/tastyeffectco/sandboxd/blob/main/control-plane/cmd/runtimed/main.go): `control-plane/cmd/runtimed/main.go`

### State and routing

- [Docker containers](https://github.com/tastyeffectco/sandboxd/blob/main/control-plane/internal/docker/docker.go): `control-plane/internal/docker/docker.go`
- [SQLite state](https://github.com/tastyeffectco/sandboxd/blob/main/control-plane/internal/store/store.go): `control-plane/internal/store/store.go`
- [Preview routing](https://github.com/tastyeffectco/sandboxd/blob/main/control-plane/internal/traefik/traefik.go): `control-plane/internal/traefik/traefik.go`

### Other components

- **User**
- **Running app**
- **Git repository**
- **API consumer**

## Connections

- User → Console shell: uses (evidence: `README.md`)
- Console shell → App workspace: opens (evidence: `console/src/App.tsx`)
- Console shell → App catalog: opens (evidence: `console/src/App.tsx`)
- Console shell → Settings: opens (evidence: `console/src/App.tsx`)
- Console shell → App overview: opens (evidence: `console/src/App.tsx`)
- App catalog → Catalog data: lists (evidence: `console/src/StoreView.tsx`)
- App workspace → API client: requests (evidence: `console/src/AppView.tsx`)
- App catalog → API client: installs via (evidence: `console/src/StoreView.tsx`)
- Settings → API client: configures via (evidence: `console/src/SettingsView.tsx`)
- Console shell → API client: requests (evidence: `console/src/App.tsx`)
- API client → HTTP API: calls `/v1` (evidence: `console/src/api.ts`)
- API consumer → HTTP API: calls `/v1` (evidence: `README.md`)
- HTTP API → Sandbox lifecycle: provisions (evidence: `control-plane/internal/api/handlers.go`)
- Sandbox lifecycle → Docker containers: runs containers
- Sandbox lifecycle → SQLite state: persists state
- Sandbox lifecycle → Preview routing: configures URLs (evidence: `README.md`)
- Sandbox lifecycle → App supervisor: starts in sandbox (evidence: `README.md`)
- Agent tasks → Coding agent: submits tasks (evidence: `control-plane/internal/api/v1_tasks.go`)
- Coding agent → App workspace: builds app (evidence: `README.md`)
- App supervisor → Running app: serves app (evidence: `README.md`)
- Preview routing → Running app: routes URL (evidence: `README.md`)
- User → Running app: views (evidence: `README.md`)
- Git repository → API client: imports repo (evidence: `README.md`)
- App workspace → Git repository: pushes changes (evidence: `README.md`)
- Sleep and wake → Docker containers: starts sandbox (evidence: `control-plane/internal/wake/handler.go`)
- Sleep and wake → SQLite state: loads sandbox (evidence: `control-plane/internal/wake/handler.go`)
- Preview access → Running app: authorizes access (evidence: `control-plane/internal/api/preview_auth.go`)
- Console shell → Deploy controls: opens
- Console shell → Release status: shows upgrade (evidence: `console/src/App.tsx`)
- App overview → App structure: renders (evidence: `console/src/BrainGraph.tsx`)
- App workspace → Starter templates: selects starter (evidence: `README.md`)
