Skip to content
Mikrom Docs

Architecture overview

Mikrom separates the control plane (deciding what should run) from the traffic plane (serving user requests). They share no request path.

Request flow

Section titled “Request flow”
You / CLI / Dashboard
        │
        ▼
   mikrom-api ──► mikrom-builder ──► OCI image ──► registry
        │
        └──► mikrom-scheduler ──► mikrom-agent ──► microVMs


External traffic ──► mikrom-router ──► app microVMs
  • mikrom-app (dashboard) and mikrom-cli call mikrom-api.
  • mikrom-api owns auth, projects, apps, deployments, secrets, PATs, GitHub integration, billing, audit logs, and database provisioning. It builds through mikrom-builder and hands placement to mikrom-scheduler.
  • mikrom-scheduler tracks workers and picks placement; mikrom-agent runs on each worker and manages microVM lifecycle, logs, and metrics.
  • mikrom-router (Pingora-based) owns ingress: routing, health checks, and TLS/ACME state. External traffic goes here and nowhere near mikrom-api.

Services

Section titled “Services”
Service Responsibility
mikrom-api Control-plane API and business logic
mikrom-app Operator/user dashboard (SvelteKit)
mikrom-cli Terminal client (mikrom)
mikrom-builder Source-to-image builds (Docker or Railpack) over BuildKit
mikrom-scheduler Worker registry and placement engine
mikrom-agent Worker daemon: microVM lifecycle, metrics, logs, host coordination
mikrom-router Ingress, TLS/ACME, health checks, traffic routing
mikrom-network WireGuard mesh and host identity
mikrom-dns Internal name resolution; DNS64 answers
mikrom-init Zig boot binary that starts the workload inside each microVM
mikrom-proto Shared protobuf contracts for internal messaging
mikrom-agent-ebpf eBPF payload the agent loads for host-side networking/metrics

Coordination

Section titled “Coordination”
  • Control-plane state originates in mikrom-api (PostgreSQL) and is fanned out over NATS to the builder, scheduler, router, network, DNS, and agents.
  • The scheduler makes placement decisions only — not routing or DNS.
  • The router owns all ingress and persisted traffic-plane routing data.
  • Network and DNS are independent of the scheduler so host identity and name resolution can evolve separately from workload placement.

For per-service detail, see Control plane and Data plane.