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.

This guide walks you through standing up a local Mikrom development environment, installing the CLI, and deploying your first application into a microVM. By the end you will have a running deployment, a connected database, and a clear picture of the day-to-day workflow.

​
Prerequisites

Before you begin, make sure the following tools are available on your machine:
  • Rust stable toolchain — install via rustup.rs
  • Docker and Docker Compose — the local stack runs Postgres, NATS, BuildKit, and the observability suite as containers
  • Node.js and pnpm — required to run the SvelteKit dashboard (mikrom-app)
  • Dagger CLI — needed for the make ci-* build and validation profiles; see the Dagger installation guide
Firecracker and Cloud Hypervisor are only required on production worker nodes. For local development the agent, scheduler, builder, and API all run as ordinary processes; no hypervisor is needed.

​
Local Development Setup

1

Clone the repository

git clone https://github.com/mikronita/mikrom.git
cd mikrom
2

Start the full infrastructure stack

make up-full starts PostgreSQL, NATS, the BuildKit daemon, and the Grafana/Prometheus/Loki/Tempo observability suite as Docker Compose services in the background.
make up-full
If you only need the core message broker and database without BuildKit or observability, run make up instead. You can bring up optional profiles later with make up-buildkit and make up-observability.
3

Launch the development session

make dev opens (or attaches to) a tmux session named mikrom with separate windows for the API, scheduler, builder, and SvelteKit app. Each service starts with cargo watch for live reloading.
make dev
To run a single service in isolation instead:
make run-api        # mikrom-api on port 5001
make run-scheduler  # mikrom-scheduler
make run-builder    # mikrom-builder
make run-agent      # mikrom-agent on port 5003
make run-router     # mikrom-router (Pingora)
make run-app        # SvelteKit dashboard on port 3001
When you are done, stop the tmux session and tear down the Compose stack:
make dev-stop   # close the tmux session only
make down-full  # stop and remove all containers
4

Install the CLI

The install-cli target compiles the mikrom binary in release mode and installs it to ~/.cargo/bin.
make install-cli
Verify the installation:
mikrom --help

​
Your First Deployment

1

Log in

Authenticate against the local API. The JWT is stored in the CLI configuration file.
mikrom auth login --email user@example.com --password secret
To check who you are logged in as at any time:
mikrom auth whoami
2

Create an application

Register a new application by giving it a unique name and pointing it at a Git repository. The builder will clone this URL when a deployment is triggered.
mikrom app create \
  --name my-app \
  --git-url https://github.com/user/my-app.git
List all registered applications:
mikrom app list
3

Deploy the application

Trigger a deployment. Mikrom clones the repository, builds an OCI image, schedules placement, and boots a microVM.
mikrom app deploy \
  --name my-app \
  --cpu 2 \
  --memory 1G
Resource presets — the --cpu and --memory flags accept fixed values only:
ResourceAllowed valuesDefault
CPU cores1, 2, 3, 41
Memory512M, 1G, 2G, 4G512M
Omitting both flags deploys with the defaults of 1 vCPU and 512 MB RAM. You can also pass --hypervisor firecracker or --hypervisor cloud-hypervisor to select the VMM explicitly; the platform chooses a sensible default when the flag is omitted.
4

Check deployment status

List all active deployments across every application:
mikrom deployment list
For granular status of a specific running instance, supply the app name and job ID printed by the previous command:
mikrom deployment status --app my-app --job-id <job-id>
5

Manage scaling

All applications scale to zero automatically after inactivity. You can also configure autoscaling thresholds or pin a fixed replica count:
# Enable autoscaling with CPU and memory thresholds
mikrom app scale \
  --name my-app \
  --auto true \
  --min 0 \
  --max 3 \
  --cpu 70 \
  --mem 80

# Pin to exactly 2 replicas (disables autoscaling)
mikrom app scale --name my-app --replicas 2

​
Working with Databases

Mikrom provisions managed PostgreSQL databases through Neon. Databases run in Cloud Hypervisor-backed microVMs on the platform and default to PostgreSQL 16.
1

Create a database

mikrom db create orders
You can customise the engine, version, and resources:
mikrom db create orders \
  --engine neon \
  --version 16 \
  --vcpus 1 \
  --memory 1G \
  --disk 2048
List all databases in the current project:
mikrom db list
2

Retrieve connection details

mikrom db connection <database-id>
This command returns:
  • The SSH tunnel command to reach the database VM
  • The psql connection command to use through the tunnel
  • Full connection metadata in JSON when you pass --output json
mikrom --output json db connection <database-id>

​
Rollbacks and Lifecycle Operations

1

Activate a previous deployment

Roll back to any earlier deployment by its ID:
mikrom app activate \
  --app my-app \
  --deployment-id <deployment-id>
Show the full deployment history for an application:
mikrom app deployments --name my-app
2

Stop, pause, and resume instances

mikrom deployment stop   --app my-app --job-id <job-id>
mikrom deployment pause  --app my-app --job-id <job-id>
mikrom deployment resume --app my-app --job-id <job-id>

​
Running the Test Suite

make test              # Unit tests only — no database required
make test-integration  # Integration tests — starts PostgreSQL and NATS via Docker
make test-all          # Full suite (unit + integration)
For the Dagger-backed CI profiles, ordered from fastest to most comprehensive: 
make ci-smoke   # fmt + clippy + frontend validation
make ci-fast    # smoke + workspace tests with ephemeral Postgres and NATS
make ci-full    # fast + release build + eBPF validation
Use make ci-smoke during daily development for the fastest feedback loop. Run make ci-fast before pushing changes that touch shared Rust code or service contracts.

​
Next Steps

Architecture

Understand how the control plane, traffic plane, and platform services fit together.

CLI Overview

Explore every command group: auth, app, deployment, db, volume, project, and PAT.

Deployment Scaling

Configure autoscaling thresholds, replica counts, and scale-to-zero behaviour.

Local Dev Setup

Deep-dive into tmux sessions, individual service targets, and environment configuration.

Build docs developers (and LLMs) love

Get started for freeTalk to us