# wrennhq/wrenn architecture

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

- Interactive diagram: https://gitdiagram.com/wrennhq/wrenn
- Repository: https://github.com/wrennhq/wrenn

## Overview

1. **Three runtime binaries define the system**
   - `wrenn-cp` is the control plane API/UI backend.
   - `wrenn-agent` runs on each Linux compute host and owns microVM lifecycle.
   - `envd` runs inside each sandbox VM as the guest-side runtime.
   This is the core architectural boundary: control plane orchestrates, host agent executes on hardware, guest agent handles in-VM operations.

2. **Control plane is the central coordination layer**
   - The Go server under `cmd/control-plane`, `internal/api`, and `pkg/service` exposes the HTTP API, auth flows, admin surfaces, metrics, SSE, and business logic for capsules, templates, hosts, teams, keys, usage, and audit.
   - `pkg/cpserver` and `pkg/cpextension` indicate the control plane is designed as an embeddable server with extension hooks.

3. **Data persistence is PostgreSQL-first**
   - Schema migrations live in `db/migrations`.
   - SQL queries are organized in `db/queries`, with generated Go accessors in `pkg/db`.
   - Most domain state—users, teams, sandboxes/capsules, templates, sessions, OAuth records, API keys, channels, hosts, metrics, audit logs—is stored in Postgres and accessed through this generated layer.

4. **The frontend is a separate SvelteKit app**
   - `frontend/` is a Bun-based SvelteKit client.
   - It talks to the control plane through typed API wrappers in `frontend/src/lib/api`.
   - It also consumes live updates through SSE helpers and a build-console WebSocket path, so the UI is not just CRUD; it reflects real-time sandbox and build state.

5. **Sandbox lifecycle is a first-class subsystem**
   - `internal/sandbox`, `internal/vm`, `internal/network`, `internal/snapshot`, and `internal/layout` implement the runtime mechanics of capsules: boot, pause/resume, restore, snapshots, process handling, and network setup.
   - `pkg/lifecycle`, `pkg/scheduler`, and `pkg/service/sandbox.go` form the orchestration path that decides where a capsule runs and how it progresses through state transitions.
   - The system is explicitly microVM-based and stateful across sessions.

6. **Host agent owns compute-host responsibilities**
   - `internal/hostagent` and `cmd/host-agent` handle host registration, heartbeats, certificates/tokens, proxying, and callbacks back to the control plane.
   - The host agent manages local resources under `/var/lib/wrenn` such as kernels, base images, sandbox CoW storage, and snapshots.
   - It is the component that actually launches and supervises Cloud Hypervisor VMs on Linux/KVM hosts.

7. **Guest runtime (`envd`) provides in-VM services**
   - The Rust workspace under `envd-rs/` builds the guest agent.
   - It exposes RPC/HTTP services for file access, process execution, PTY/terminal interaction, activity tracking, memory/snapshot support, and auth/middleware inside the sandbox.
   - This is what lets agents and the control plane interact with the workspace as if it were a remote development machine.

8. **Connectivity between control plane, host agent, and guest is RPC-heavy**
   - `proto/hostagent` and `proto/envd` define the service contracts.
   - The Go side includes client helpers in `internal/envdclient` and server handlers in `internal/api`.
   - This architecture keeps the control plane decoupled from host-specific VM mechanics and guest-side operations.

9. **Events, SSE, and notifications are a separate delivery plane**
   - `internal/api/sse_broker.go`, `sse_relay.go`, and `handlers_sse.go` support live browser updates.
   - Durable lifecycle events are published to a stream and consumed by `pkg/channels` for external notifications like webhook, Slack, Discord, Teams, etc.
   - The README’s event model shows a deliberate split between transient UI-only events and durable auditable events.

10. **Auth and identity are integrated across multiple surfaces**
   - `pkg/auth` covers passwords, OAuth/GitHub, JWTs, API keys, and certificates.
   - `pkg/auth/session` and related middleware support browser sessions and CSRF protection.
   - The control plane also has dedicated middleware for admin access, host tokens, and session enforcement, so auth is not centralized in a single endpoint layer.

11. **Operational subsystems include metrics, audit, email, and usage**
   - `internal/metrics` and `pkg/service/stats.go` support system and product metrics.
   - `pkg/audit` records administrative and lifecycle actions.
   - `internal/email` and `pkg/email` provide transactional email templates.
   - `internal/api/usage_rollup.go` plus the usage-related services indicate quota/limits are derived from persisted activity, not just in-memory state.

12. **Infrastructure and packaging are intentionally repo-local**
   - `deploy/` contains local/dev composition, reverse proxy config, and log rotation.
   - `images/` and `scripts/` build the system base rootfs images used by hosts.
   - `recipes/` defines sandbox image recipes, while `.woodpecker/` and the build scripts show CI/CD builds all three binaries and publishes release artifacts.

13. **The main external dependencies are meaningful to architecture**
   - PostgreSQL is the primary database.
   - Redis is used for the durable event stream and channel delivery semantics.
   - Cloud Hypervisor and KVM are the core runtime for sandboxes.
   - Docker is used for development infra and building rootfs images.
   - The frontend is built with Bun/SvelteKit, while the backend is Go and the guest agent is Rust.

14. **A useful mental model for the architecture diagram**
   - Left side: user/browser traffic into the control plane UI/API.
   - Center: control plane services over Postgres, Redis, auth, scheduling, and notification pipelines.
   - Right side: host agents on Linux machines controlling microVMs and talking to guest `envd` instances.
   - Bottom/supporting layer: generated DB access, proto contracts, image/rootfs build pipeline, and host provisioning artifacts.

Main entry points: [`internal/api`](https://github.com/wrennhq/wrenn/tree/main/internal/api) (HTTP API), [`scripts`](https://github.com/wrennhq/wrenn/tree/main/scripts) (Build pipeline), [`internal/sandbox`](https://github.com/wrennhq/wrenn/tree/main/internal/sandbox) (Sandbox core), [`cmd/host-agent/main.go`](https://github.com/wrennhq/wrenn/blob/main/cmd/host-agent/main.go) (Host agent)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_frontend["Frontend"]
  node_frontend_app["Web app<br/>SvelteKit UI"]
  node_frontend_live["Live updates<br/>SSE/WebSocket<br/>[sse.svelte.ts]"]
end

subgraph group_group_control_plane["Control plane"]
  node_cp_main["CP binary<br/>Go entrypoint<br/>[main.go]"]
  node_api_layer["HTTP API<br/>handlers"]
  node_services["Services<br/>domain logic"]
  node_auth_layer["Auth<br/>identity"]
  node_sched_lifecycle["Scheduling<br/>orchestration"]
  node_sandbox_core["Sandbox core<br/>microVM runtime"]
  node_networking["Network setup<br/>host networking"]
  node_snapshots["Snapshots<br/>state persistence"]
  node_events_notify["Events<br/>delivery plane"]
  node_ops_obs["Ops<br/>metrics/audit/email"]
end

subgraph group_group_runtime["Runtime"]
  node_vm_hosting["VM host<br/>Cloud Hypervisor"]
  node_host_agent["Host agent<br/>Go agent<br/>[main.go]"]
  node_hostagent_core["Host duties<br/>host ops"]
  node_envd_runtime["Guest runtime<br/>Rust agent<br/>[main.rs]"]
  node_envd_rpc["Guest RPC<br/>connect RPC"]
  node_hostagent_rpc["Host RPC<br/>connect RPC"]
end

subgraph group_group_support["Support"]
  node_persistence[("Postgres layer<br/>SQLC/Postgres")]
  node_build_pipeline["Build pipeline<br/>CI/images"]
end

node_frontend_app -->|"calls"| node_api_layer
node_frontend_app -->|"subscribes"| node_frontend_live
node_cp_main -->|"serves"| node_api_layer
node_api_layer -->|"delegates"| node_services
node_api_layer -->|"enforces"| node_auth_layer
node_services -->|"reads/writes"| node_persistence
node_services -->|"orchestrates"| node_sched_lifecycle
node_sched_lifecycle -->|"manages"| node_sandbox_core
node_sandbox_core -->|"launches"| node_vm_hosting
node_sandbox_core -->|"configures"| node_networking
node_sandbox_core -->|"restores"| node_snapshots
node_host_agent -->|"contains"| node_hostagent_core
node_hostagent_core -->|"implements"| node_hostagent_rpc
node_host_agent -->|"supervises"| node_vm_hosting
node_host_agent -->|"connects"| node_envd_runtime
node_envd_runtime -->|"implements"| node_envd_rpc
node_api_layer -->|"clients"| node_envd_rpc
node_api_layer -->|"clients"| node_hostagent_rpc
node_api_layer -->|"publishes"| node_events_notify
node_events_notify -->|"delivers"| node_frontend_live
node_ops_obs -->|"records"| node_persistence
node_build_pipeline -->|"builds"| node_host_agent
node_build_pipeline -->|"builds"| node_cp_main
node_build_pipeline -->|"builds"| node_envd_runtime
node_build_pipeline -.->|"migrates"| node_persistence

click node_frontend_app "https://github.com/wrennhq/wrenn/tree/main/frontend"
click node_frontend_live "https://github.com/wrennhq/wrenn/blob/main/frontend/src/lib/sse.svelte.ts"
click node_cp_main "https://github.com/wrennhq/wrenn/blob/main/cmd/control-plane/main.go"
click node_api_layer "https://github.com/wrennhq/wrenn/tree/main/internal/api"
click node_services "https://github.com/wrennhq/wrenn/tree/main/pkg/service"
click node_auth_layer "https://github.com/wrennhq/wrenn/tree/main/pkg/auth"
click node_sched_lifecycle "https://github.com/wrennhq/wrenn/tree/main/pkg/scheduler"
click node_sandbox_core "https://github.com/wrennhq/wrenn/tree/main/internal/sandbox"
click node_vm_hosting "https://github.com/wrennhq/wrenn/tree/main/internal/vm"
click node_networking "https://github.com/wrennhq/wrenn/tree/main/internal/network"
click node_snapshots "https://github.com/wrennhq/wrenn/tree/main/internal/snapshot"
click node_host_agent "https://github.com/wrennhq/wrenn/blob/main/cmd/host-agent/main.go"
click node_hostagent_core "https://github.com/wrennhq/wrenn/tree/main/internal/hostagent"
click node_envd_runtime "https://github.com/wrennhq/wrenn/blob/main/envd-rs/src/main.rs"
click node_envd_rpc "https://github.com/wrennhq/wrenn/tree/main/proto/envd"
click node_hostagent_rpc "https://github.com/wrennhq/wrenn/tree/main/proto/hostagent"
click node_persistence "https://github.com/wrennhq/wrenn/tree/main/pkg/db"
click node_events_notify "https://github.com/wrennhq/wrenn/tree/main/pkg/channels"
click node_ops_obs "https://github.com/wrennhq/wrenn/tree/main/pkg/audit"
click node_build_pipeline "https://github.com/wrennhq/wrenn/tree/main/scripts"

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_frontend_app,node_frontend_live toneBlue
class node_cp_main,node_api_layer,node_services,node_auth_layer,node_sched_lifecycle,node_sandbox_core,node_networking,node_snapshots,node_events_notify,node_ops_obs toneAmber
class node_vm_hosting,node_host_agent,node_hostagent_core,node_envd_runtime,node_envd_rpc,node_hostagent_rpc toneMint
class node_persistence,node_build_pipeline toneRose
```

## Components

### Frontend

SvelteKit client and browser-side state

- [Web app](https://github.com/wrennhq/wrenn/tree/main/frontend): SvelteKit UI · Browser UI with typed API clients and live state helpers · `frontend`
- [Live updates](https://github.com/wrennhq/wrenn/blob/main/frontend/src/lib/sse.svelte.ts): SSE/WebSocket · Browser event stream and build-console updates · `frontend/src/lib/sse.svelte.ts`

### Control plane

Go API, domain services, auth, persistence, and event delivery

- [CP binary](https://github.com/wrennhq/wrenn/blob/main/cmd/control-plane/main.go): Go entrypoint · Control plane executable · `cmd/control-plane/main.go`
- [HTTP API](https://github.com/wrennhq/wrenn/tree/main/internal/api): handlers · Auth, admin, sandbox, metrics, SSE, and browser-facing endpoints · `internal/api`
- [Services](https://github.com/wrennhq/wrenn/tree/main/pkg/service): domain logic · Business logic for users, teams, capsules, templates, builds, and stats · `pkg/service`
- [Auth](https://github.com/wrennhq/wrenn/tree/main/pkg/auth): identity · Passwords, OAuth, JWT, API keys, certs, sessions, and CSRF · `pkg/auth`
- [Scheduling](https://github.com/wrennhq/wrenn/tree/main/pkg/scheduler): orchestration · Host selection and capsule lifecycle coordination · `pkg/scheduler`
- [Sandbox core](https://github.com/wrennhq/wrenn/tree/main/internal/sandbox): microVM runtime · Boot, pause, restore, snapshots, process handling, and networking · `internal/sandbox`
- [Network setup](https://github.com/wrennhq/wrenn/tree/main/internal/network): host networking · Allocation, NAT, and sandbox network wiring · `internal/network`
- [Snapshots](https://github.com/wrennhq/wrenn/tree/main/internal/snapshot): state persistence · Local and remote snapshot storage and restore flows · `internal/snapshot`
- [Events](https://github.com/wrennhq/wrenn/tree/main/pkg/channels): delivery plane · Durable lifecycle events, SSE relay, and external notifications · `pkg/channels`
- [Ops](https://github.com/wrennhq/wrenn/tree/main/pkg/audit): metrics/audit/email · Metrics collection, audit logging, usage rollup, and transactional email · `pkg/audit`

### Runtime

Host agent, microVM lifecycle, and guest runtime

- [VM host](https://github.com/wrennhq/wrenn/tree/main/internal/vm): Cloud Hypervisor · MicroVM management and host-side process control · `internal/vm`
- [Host agent](https://github.com/wrennhq/wrenn/blob/main/cmd/host-agent/main.go): Go agent · Linux host daemon for registration, callbacks, proxying, and VM supervision · `cmd/host-agent/main.go`
- [Host duties](https://github.com/wrennhq/wrenn/tree/main/internal/hostagent): host ops · Registration, heartbeats, certs/tokens, proxying, and control-plane callbacks · `internal/hostagent`
- [Guest runtime](https://github.com/wrennhq/wrenn/blob/main/envd-rs/src/main.rs): Rust agent · In-VM runtime for file, process, PTY, activity, memory, and snapshot services · `envd-rs/src/main.rs`
- [Guest RPC](https://github.com/wrennhq/wrenn/tree/main/proto/envd): connect RPC · Filesystem and process service contracts inside the sandbox · `proto/envd`
- [Host RPC](https://github.com/wrennhq/wrenn/tree/main/proto/hostagent): connect RPC · Contracts between control plane and host agent · `proto/hostagent`

### Support

Contracts, database artifacts, image builds, and deployment

- [Postgres layer](https://github.com/wrennhq/wrenn/tree/main/pkg/db): SQLC/Postgres · Generated accessors over schema migrations and query files · `pkg/db`
- [Build pipeline](https://github.com/wrennhq/wrenn/tree/main/scripts): CI/images · Rootfs recipes, image scripts, and release builds for Go and Rust binaries · `scripts`

## Connections

- Web app → HTTP API: calls · UI uses typed API wrappers to talk to the backend
- Web app → Live updates: subscribes · Browser reflects live sandbox and build state
- CP binary → HTTP API: serves · Control plane binary hosts the HTTP/API surface
- HTTP API → Services: delegates · Handlers forward business actions to service layer
- HTTP API → Auth: enforces · Middleware and handlers apply auth/session/CSRF rules
- Services → Postgres layer: reads/writes · Domain state is stored in Postgres via generated queries
- Services → Scheduling: orchestrates · Services drive capsule placement and state transitions
- Scheduling → Sandbox core: manages · Lifecycle manager controls sandbox progression
- Sandbox core → VM host: launches · Sandbox runtime depends on VM management primitives
- Sandbox core → Network setup: configures · Sandbox setup wires networking and NAT
- Sandbox core → Snapshots: restores · Paused and launched sandboxes use snapshot flows
- Host agent → Host duties: contains · Host binary runs the host-agent subsystem
- Host duties → Host RPC: implements · Host agent speaks the host-agent RPC contract
- Host agent → VM host: supervises · Host daemon launches and monitors microVMs
- Host agent → Guest runtime: connects · Host side reaches the guest runtime through in-VM services
- Guest runtime → Guest RPC: implements · Guest runtime exposes filesystem/process RPC services
- HTTP API → Guest RPC: clients · Control plane uses envd client helpers for guest interaction
- HTTP API → Host RPC: clients · Control plane talks to host agents through generated contracts
- HTTP API → Events: publishes · API emits lifecycle events for SSE and notifications
- Events → Live updates: delivers · SSE relays carry live updates to the browser
- Ops → Postgres layer: records · Metrics, audit, and usage data are persisted in Postgres
- Build pipeline → Host agent: builds · CI produces the host-agent binary and release artifacts
- Build pipeline → CP binary: builds · CI produces the control-plane binary
- Build pipeline → Guest runtime: builds · Rust workspace builds the guest runtime
- Build pipeline → Postgres layer: migrates · Repo-local migrations and SQL generation define schema shape