The name is the architecture.

A level is a line you can hold things to. Levelrail keeps a desired state, looks at what is actually running, and pulls the difference back to zero. On every pass, not only when something happens to tell it to.

Pre-release. Single node is the best tested path, multi-node is beta.

A push builds an image and starts the new container beside the running one. The ingress keeps sending traffic to the old container until the new one passes its readiness check, then cuts over. The old one stays around for a rollback.
reconcile condition
levelrail-cli apps status webReady    False   ReadinessFailedGET http://127.0.0.1:32768/healthz timed out after 2sold release keeps serving. next pass checks again.

diagram desired is the dashed line. Every pass compares, so every drift ends back on it.

Level, not edge.

An edge-triggered system acts when it is told something changed. A level-triggered one looks at the world and compares. The first is only as reliable as its messages. The second repairs itself from whatever is true now.

Levelrail reads Docker's event stream and also resyncs on a schedule, so a missed event costs time, not correctness. Reconcilers are idempotent and safe to interrupt. See the architecture docs.

Edge-triggered

Acts when an event arrives. Lose one and nothing looks again.

matches desired

Level-triggered

Compares running with wanted on every pass, so a lost event is only a delay.

on level
desired level is the dashed line

Agents dial out. Nothing dials in.

No inbound ports on the machines you manage. That one rule shapes everything about how nodes join.

Each agent dials out to the control plane over one mutual TLS connection and streams events up. Nothing listens on the nodes for the control plane to reach, so a home server behind NAT works the same as a cloud VM.
  1. 01

    One outbound connection, held open

    Every managed node runs an agent. The agent opens a single gRPC connection to the control plane over mutual TLS and keeps it. Nothing connects to the node, so there is no inbound port to open, forward or firewall. A home server behind residential NAT enrolls the same way a VPS does.

  2. 02

    The private key never leaves the node

    The control plane mints a one-time join token. The agent generates its own key, sends only a certificate signing request with that token, and keeps the signed certificate. Pin the control plane CA fingerprint and the agent refuses to hand the token to anything else.

  3. 03

    Events up, one code path

    Docker events stream up over the same link, and the agent talks to its local Docker socket through the Engine API, never by shelling out. On a single machine the agent runs inside the control plane process over an in-memory transport, so the code path is the same from one node to ten.

Multi-node is beta and the WireGuard mesh is not battle tested. Details and limits in the multi-node guide and the security overview.

One binary, boring state.

The control plane is a single static Go binary with the dashboard embedded. There is no Node runtime, no database server and no proxy to run beside it.

  • Caddy is a library Ingress runs inside the control plane process and is driven through its admin API. No proxy container, no config file to drift from desired state.
  • State is one SQLite file WAL mode through a pure Go driver, forward-only migrations. Certificates live in the same database, so nodes share them.
  • Docker is the only runtime The Engine API, never the CLI. A second machine is optional and joins by running an agent.
One Linux box is enough: a single control plane binary with embedded Caddy and SQLite, Docker for the containers, then your apps and your database. A second machine is optional and joins by running an agent.

The whole contract for an app is one file in your repo. Every field is validated against an embedded JSON Schema, and an unknown key is an error.

app.yaml
version: 1
services:
  web:
    build:
      type: dockerfile
      path: ./Dockerfile
    domains:
      - app.acme.dev
    port: 3000
    health:
      readiness: { path: /healthz, interval: 5s, timeout: 2s }
    replicas: 2
    strategy: rolling
databases:
  main:
    engine: postgres
    version: "16"
    backup: { schedule: "0 3 * * *", retain: 7 }

Four decisions that cannot be unmade cheaply

Each one is a written record with the alternatives it turned down. Hover or focus a row to see what lost.

  1. ADR 002 A reconciler over the Docker Engine API Desired state lives in the database. A level-triggered loop per resource type compares it with what Docker reports and converges. Docker events drive it, with a periodic resync as the safety net.

    turned down

    • Docker Swarm in maintenance mode, and coupling to its update semantics becomes a liability.
    • Nomad BSL license.
    • K3s or Kubernetes brings back the whole surface area this project exists to avoid.
    • SSH plus shelled docker commands forces polling loops or leaves real gaps.
  2. ADR 003 Agents that dial out over mutual TLS One outbound gRPC connection per node. A one-time join token buys a client certificate. Docker events stream up, so the control plane never polls down.

    turned down

    • SSH as the main transport one of the most commented issues in Kamal is a pure SSH disconnect failure that has nothing to do with deploy logic.
    • Nodes that must reach each other the Swarm cluster pattern, which needs inbound reachability.
  3. ADR 007 SQLite in WAL mode for state One embedded database through a pure Go driver, forward-only migrations, nothing to install or keep running next to the binary.

    turned down

    • Postgres or MySQL as the default one more always-on service with its own upgrades and failure modes.
    • Never adding Postgres at all a driver can come later if a highly available control plane is actually asked for.
  4. ADR 008 Telemetry stays on the node Each agent keeps its own metrics and log store. The control plane fans a query out and merges the answers. Pull, not push, so an idle install does almost no work.

    turned down

    • Shipping everything to a central store cost that grows with node count whether or not anyone is looking.
    • Polling nodes over SSH a fresh exec for every state read, forever.
    • A bolted-on optional metrics agent observability as an add-on instead of a primitive.

Every decision is visible in the dashboard.

Nothing above is hidden machinery. The nodes your agents dial in from, and the rollout the reconciler runs, are pages you can open.

Nodes page: a table of nodes with address, usage, resources, agent version and last seen Nodes page: a table of nodes with address, usage, resources, agent version and last seen
ADR 003. Each agent shows up as a node with its address, usage, agent version and when it was last seen.
Deploy page with the roll out timeline: build, health check, cutover and cleanup, each with its duration Deploy page with the roll out timeline: build, health check, cutover and cleanup, each with its duration
ADR 002. The roll out timeline is the reconciler's work: health check, cutover, cleanup, each with how long it took.

Nothing here asks you to trust a slogan.

The decisions are written down, the limits are published, and the source is Apache 2.0.