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.
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.
Level-triggered
Compares running with wanted on every pass, so a lost event is only a delay.
Agents dial out. Nothing dials in.
No inbound ports on the machines you manage. That one rule shapes everything about how nodes join.
- 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.
- 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.
- 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.
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.
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.
- 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.
- 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.
- 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.
- 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.
Nothing here asks you to trust a slogan.
The decisions are written down, the limits are published, and the source is Apache 2.0.