How wrennhq/wrenn works
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: api HTTP API · scripts Build pipeline · sandbox Sandbox core · main.go Host agent
Components 20
Frontend
SvelteKit client and browser-side state
- Web app · Browser UI with typed API clients and live state helpers
frontend - Live updates · 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 · Control plane executable
cmd/control-plane/main.go - HTTP API · Auth, admin, sandbox, metrics, SSE, and browser-facing endpoints
internal/api - Services · Business logic for users, teams, capsules, templates, builds, and stats
pkg/service - Auth · Passwords, OAuth, JWT, API keys, certs, sessions, and CSRF
pkg/auth - Scheduling · Host selection and capsule lifecycle coordination
pkg/scheduler - Sandbox core · Boot, pause, restore, snapshots, process handling, and networking
internal/sandbox - Network setup · Allocation, NAT, and sandbox network wiring
internal/network - Snapshots · Local and remote snapshot storage and restore flows
internal/snapshot - Events · Durable lifecycle events, SSE relay, and external notifications
pkg/channels - Ops · Metrics collection, audit logging, usage rollup, and transactional email
pkg/audit
Runtime
Host agent, microVM lifecycle, and guest runtime
- VM host · MicroVM management and host-side process control
internal/vm - Host agent · Linux host daemon for registration, callbacks, proxying, and VM supervision
cmd/host-agent/main.go - Host duties · Registration, heartbeats, certs/tokens, proxying, and control-plane callbacks
internal/hostagent - Guest runtime · In-VM runtime for file, process, PTY, activity, memory, and snapshot services
envd-rs/src/main.rs - Guest RPC · Filesystem and process service contracts inside the sandbox
proto/envd - Host RPC · Contracts between control plane and host agent
proto/hostagent
Support
Contracts, database artifacts, image builds, and deployment
- Postgres layer · Generated accessors over schema migrations and query files
pkg/db - Build pipeline · Rootfs recipes, image scripts, and release builds for Go and Rust binaries
scripts
Connections 25
- 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