How pandastack-io/pandastack-ai works
PandaStack is a self-hosted control plane for disposable Firecracker sandboxes and managed PostgreSQL running in dedicated microVMs. The principal workflow is a client request entering the API, capacity selection by the scheduler, and VM creation or restoration by a host agent. The agent exposes sandbox operations and manages lifecycle, snapshots, and streaming restores. Separate branches cover managed database provisioning and recovery, template builds, dashboard operations, and database connection routing. Some internals are represented at subsystem level because their source was not excerpted; documented architecture supplies the control-plane flow.
Main entry points: manager.go Sandbox lifecycle · main.go REST API · scheduler.go Capacity scheduler · client.tsx Database dashboard
Components 23
Control plane
- REST API
api/cmd/api/main.go - Capacity scheduler
api/internal/scheduler/scheduler.go - Template builds
api/cmd/api/templates_build_handler.go - Template snapshots
agent/internal/seed/seed.go - Audit and telemetry
api/cmd/api/main.go
Host runtime
- Host agent
agent/cmd/agent/main.go - Agent HTTP API
agent/internal/api/router.go - Sandbox lifecycle
agent/internal/sandbox/manager.go - Firecracker driver
agent/internal/firecracker/driver.go - Snapshot store
agent/internal/snapstore/snapstore.go - Memory streaming
agent/internal/uffd/handler_linux.go - Rootfs streaming
agent/internal/nbdstream/server_linux.go - Agent metadata
agent/internal/store/store.go - Guest daemon
agent/cmd/pandastack-daemon/main.go
Managed databases
- Database operations
api/cmd/api/databases.go - Database failover
api/cmd/api/databases_failover.go - WAL archiving
agent/internal/sandbox/wal_relay.go - Database proxy
db-proxy/main.go
User surfaces
- Dashboard
dashboard/src/app/(app)/sandboxes/[id]/client.tsx - Database dashboard
dashboard/src/app/(app)/databases/[id]/client.tsx - Database metrics
dashboard/src/app/(app)/databases/[id]/db-metrics-charts.tsx - Database logs
dashboard/src/app/(app)/databases/[id]/logs/client.tsx
Other components
- API client
Connections 27
- API client → REST API: requests
README.md - REST API → Capacity scheduler: selects capacity
README.md - Capacity scheduler → Host agent: dispatches work
README.md - Host agent → Agent HTTP API: serves routes
agent/cmd/agent/main.go - Agent HTTP API → Sandbox lifecycle: handles lifecycle
agent/internal/api/router.go - Sandbox lifecycle → Firecracker driver: manages VMs
README.md - Sandbox lifecycle → Snapshot store: persists snapshots
README.md - Sandbox lifecycle → Agent metadata: persists state
agent/internal/sandbox/manager.go - Sandbox lifecycle → Memory streaming: restores memory
- Sandbox lifecycle → Rootfs streaming: streams rootfs
- Firecracker driver → Guest daemon: runs guest
- REST API → Database operations: routes database requests
api/cmd/api/main.go - Database operations → Capacity scheduler: selects host
- Database failover → Capacity scheduler: chooses target
api/cmd/api/databases_failover.go - Database failover → Database operations: restores database
- Database operations → WAL archiving: coordinates archiving
- API client → Database proxy: connects by hostname
- Template builds → Capacity scheduler: finds agents
api/cmd/api/templates_build_handler.go - Template snapshots → Sandbox lifecycle: supplies snapshots
- REST API → Audit and telemetry: records telemetry
api/cmd/api/main.go - API client → Dashboard: uses
- Dashboard → REST API: calls API
- API client → Database dashboard: manages databases
- Database dashboard → Database metrics: renders metrics
dashboard/src/app/(app)/databases/[id]/client.tsx - Database dashboard → Database logs: opens logs
- Database dashboard → REST API: calls database API
- Database logs → REST API: fetches logs