Skip to content
Mikrom Docs

Control plane

The control plane decides what should run. It never sits in the path of application traffic — see Data plane for that.

mikrom-api

Section titled “mikrom-api”

The control-plane API and business logic. Written in Rust (Axum, SQLx, Tokio).

  • Owns: authentication and profiles, projects, apps, deployments, secrets, personal access tokens, GitHub App integration, billing (Polar), audit logs, and Neon-backed database provisioning.
  • State: PostgreSQL.
  • Publishes: deployment/app intent onto NATS for the builder, scheduler, router, and agents to consume.
  • ACME worker: watches app hostnames and managed platform domains and triggers certificate issuance/renewal; on a first successful deploy it kicks off immediate certification for the new hostname.
  • Surface: REST at /v1, Bearer auth (session JWT or PAT). OpenAPI at /v1/api-docs/openapi.json, explorer at /v1/docs.

mikrom-builder

Section titled “mikrom-builder”

Turns a Git repository into an OCI image.

  • Clones the repo for a deployment.
  • If a Dockerfile is present at the root, builds with Docker.
  • Otherwise builds with Railpack over BuildKit (BUILDKIT_HOST).
  • Detects the service port: respects EXPOSE in a Dockerfile, and inspects the built image otherwise.
  • Pushes the resulting image to the platform registry and reports build state over NATS.

mikrom-scheduler

Section titled “mikrom-scheduler”

The placement engine and worker registry.

  • Tracks registered workers and their resource state via agent metrics over NATS.
  • Chooses which worker runs a deployment; handles app scaling decisions and router-restore flows.
  • Does not do routing or DNS — it only decides placement, then coordinates with mikrom-agent.

Coordination model

Section titled “Coordination model”
mikrom-api ──(PostgreSQL: source of truth)
    │
    └──(NATS)──► mikrom-builder     (build state)
              ─► mikrom-scheduler   (placement)
              ─► mikrom-agent(s)    (run / stop / snapshot)
              ─► mikrom-router      (routes, health, TLS state)

Control-plane state starts in mikrom-api and is fanned out over NATS. Internal service-to-service contracts are defined in mikrom-proto.

Supporting pieces

Section titled “Supporting pieces”
  • mikrom-app — the SvelteKit dashboard; a client of mikrom-api.
  • mikrom-cli — the mikrom terminal client; also just a client of mikrom-api.
  • ci/ — a Dagger-backed local CI runner used to validate the platform itself.