Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/mikronita/mikrom/llms.txt

Use this file to discover all available pages before exploring further.

mikrom-scheduler is the placement engine for the Mikrom platform. It maintains a live registry of available worker nodes, tracks their CPU and RAM capacity as reported by agent heartbeats, and makes binding placement decisions when mikrom-api submits a deployment request. Once a worker is selected, the scheduler instructs the mikrom-agent on that node to create the microVM. The scheduler is intentionally narrow in scope: it owns placement and worker state, not routing, DNS, or certificate management.

​
Responsibilities

Worker Registry

Tracks all available worker nodes and their current capacity. Workers are registered and refreshed via periodic NATS heartbeats from mikrom-agent.

Placement Decisions

Scores candidate workers based on reported CPU and RAM metrics and selects the best fit for each deployment request.

Agent Coordination

Issues VM creation and cleanup commands to mikrom-agent on the selected worker node via NATS request-reply.

Cluster State

Persists placement history and job lifecycle state in PostgreSQL. Runs background sweeps to clean up stale VMs and deployments.

​
How Placement Works

1

Deployment request arrives from mikrom-api

mikrom-api publishes a placement request to NATS. The request includes the workload’s resource requirements (CPU and RAM) and the OCI image reference produced by mikrom-builder.
2

Scheduler evaluates worker capacity

The scheduler queries its in-memory worker registry, filtering out nodes that lack sufficient free CPU or RAM. Remaining candidates are scored by available headroom.
3

Worker selected

The highest-scoring worker is selected as the placement target. The decision is persisted to PostgreSQL before the command is issued.
4

Agent instructed to create the microVM

The scheduler sends a NATS request to the mikrom-agent running on the selected worker node, providing the VM configuration. The agent boots the microVM and returns an acknowledgement.
5

Placement confirmed to mikrom-api

Once the agent acknowledges VM creation, the scheduler replies to mikrom-api’s original request with the placement result. The API updates deployment state and triggers route registration in mikrom-router.

​
Worker Registry

Workers self-register when mikrom-agent starts. The scheduler tracks each worker by its MIKROM_HOST_ID and updates capacity estimates from the metrics included in heartbeat messages. 
mikrom-agent  ──NATS heartbeat (CPU, RAM, disk)──►  mikrom-scheduler (registry)
              ──NATS heartbeat────────────────────►  (refresh, TTL extended)
              (silence / timeout)                    → worker marked unavailable
Workers that stop sending heartbeats are eventually evicted from the active registry. Only workers in the active registry are eligible for new placements.

​
Runtime Configuration

VariableDefaultDescription
DATABASE_URLrequiredPostgreSQL connection string for placement state
NATS_URLrequiredNATS server URL
AGENT_REQUEST_TIMEOUT_SECS30Timeout for scheduler-to-agent NATS requests
VM_CLEANUP_INTERVAL_SECS3600How often the VM cleanup sweep runs
VM_CLEANUP_TTL_SECS3600Minimum age before a VM is eligible for cleanup
BETA_DEPLOYMENT_CLEANUP_ENABLEDfalseEnable the beta deployment cleanup sweep (off in production)
BETA_DEPLOYMENT_CLEANUP_INTERVAL_SECS3600Interval for the beta deployment cleanup sweep
Leave BETA_DEPLOYMENT_CLEANUP_ENABLED=false in production. This sweep deletes all deployments and their VMs on the configured interval and is intended only for development and testing environments.

​
Scope Boundaries

The scheduler is responsible for placement only. The following concerns are explicitly out of scope:
ConcernOwned by
Ingress routing and TLSmikrom-router
Internal DNS resolutionmikrom-dns
WireGuard mesh configurationmikrom-network
OCI image buildingmikrom-builder
Auth and app lifecyclemikrom-api

​
Stack

  • Rust 2024 — service runtime
  • Tokio — async executor
  • async-nats — NATS request-reply for placement and agent coordination
  • SQLx + PostgreSQL — persistent placement state and worker registry snapshots

​
Dockerfile

The scheduler ships a Dockerfile for containerized production deployments: 
# mikrom-scheduler/Dockerfile
docker build -f mikrom-scheduler/Dockerfile .

​
Local Development

make run-scheduler               # Start the scheduler against local NATS and Postgres
cargo run -p mikrom-scheduler
cargo nextest run -p mikrom-scheduler
make ci-smoke
make ci-fast
make ci-full

​
Testing

  • Integration tests use an ephemeral TestDb helper. They default to postgres://mikrom:mikrom_password@localhost:5432/mikrom_scheduler_test when TEST_DATABASE_URL is not set.
  • The ignored NATS and scheduler end-to-end integration suites are exercised by make ci-external-tests.
When changing placement logic or worker scoring, validate with the full agent + networking services running rather than unit-testing the scorer in isolation. Worker capacity metrics and heartbeat timing interact in ways that only appear under realistic load.

Build docs developers (and LLMs) love

Get started for freeTalk to us