levelrail

module

v0.6.0 Latest Latest Go to latest Published: Oct 17, 2026 License: Apache-2.0

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/GLINCKER/levelrail

Links

Open Source Insights

README ¶

Levelrail

Push to git, get a running app with TLS, logs, metrics, and rollback, on your own Linux boxes.

Docs · Quickstart · Features · Compare · Roadmap · Discord

Levelrail is open source (Apache 2.0) and ships as one Go binary that uses Docker as the runtime. It turns Linux servers you already own into a private cloud, without Kubernetes.

Why Levelrail

Push to deploy. Webhooks from GitHub, GitLab, Bitbucket or Gitea start a build, and the app is served over HTTPS with automatic certificates.
Safe rollback. Deploys wait for a readiness probe, and prior images are pinned, so one click rolls back and garbage collection cannot remove the target.
Logs, metrics and traces built in. Each node keeps its own metrics (15 second resolution) and searchable logs, with deploy markers. Traces are opt-in per app. No Grafana stack to install.
Previews per pull request. Stable on GitHub, beta on GitLab and Bitbucket.
Add servers without opening ports. Agents dial out over mTLS. Multi-node is beta.

Status: early. Single node is the most tested path, and multi-node is beta. Each feature is labelled stable or beta, with the evidence, on the feature status page.

Quick start

You need a Linux server (amd64 or arm64) with systemd, root access, and ports 80 and 443 open. Docker is installed for you if it is missing.

Install on the server.
```
curl -fsSL https://levelrail.com/install.sh | sudo sh
```
The installer prints a dashboard URL with a one-time setup token.
Finish setup in the browser. Open the URL, choose a password, and follow the setup wizard for a domain, a git provider and your first app.
Deploy a repository from the CLI.
```
levelrail-cli import https://github.com/your-org/your-app --deploy
```
Without --deploy it prints the deployment plan and stops.

Next: Getting started for the full walkthrough, then Deploying apps and Observability. Prefer containers, a pinned version or a source build? See Installing and Docker.

_{Install, then deploy}

_{Gated deploy, one-step rollback}

Why not Coolify or Dokploy?

Coolify manages servers over SSH, and Dokploy builds on Docker Swarm. Levelrail makes different architecture choices:

Agents dial out over mTLS. Each node runs an agent that talks to Docker's Engine API directly. There is no SSH, no inbound port, and no shelling out to the docker CLI.
Observability is part of the core. Metrics, logs and alerting ship in the same binary, so there is no separate stack to install.
Metrics and logs stay on each node. The control plane queries them on demand instead of collecting them into a central store.

What you get

Area	What it does	Docs
Deploys	Rolling, recreate, or blue-green, gated on real readiness probes. Import a repo URL, an image, a `docker run` command, or a compose file.	Deploying apps, Importing apps
Domains and TLS	Embedded Caddy ingress with automatic certificates and routing.	Domains and ingress
Databases	Postgres, Redis, MySQL, MongoDB, MariaDB, KeyDB, Dragonfly, and ClickHouse, with scheduled backups, restore, and an automatic re-download and checksum after every backup.	Managing databases, Backups
Observability	Node-local metrics and full-text log search with deploy markers, per-app log pipelines (multiline, redact, drop, parse), a Loki-compatible read API for Grafana, Prometheus remote write, OTLP traces with a waterfall, Sentry-compatible error tracking, and log exports to New Relic, Datadog, Axiom and Better Stack.	Observability, Loki API, Tracing, Error tracking
Safety	Prior images are pinned, so rollback is always one click and garbage collection cannot remove the target. Deploy approvals and freezes.	Deploy safety
Access	Allow and Deny IAM policies scoped to a single app or database, with an audit log and CSV export, in the free Apache 2.0 core.	Access control
Automation	One HTTP API behind the dashboard, a CLI, and an MCP server. AI never sits in the reconciliation path.	CLI reference, AI control

More features

Sleep when idle. An app with no requests for a time you choose stops and uses no memory or CPU, then starts on the next request. See Sleep when idle.
Many servers, no open ports. Add nodes with a one-time token. Agents dial out over mTLS, with WireGuard mesh networking, internal DNS, cordon, and drain. See Multi-node.
Git-native. GitHub, GitLab, Bitbucket, and Gitea webhooks and preview environments per pull request.
A large catalog of one-click templates for self-hosted services, each a compose file the platform deploys and manages. See Template catalog.
Alerting. Threshold, crashloop, and certificate expiry rules delivered over many notification channels, including Slack, Discord, email, Telegram, PagerDuty, ntfy, and a generic webhook.
Pipelines. CI/CD runs on your own nodes, defined in a YAML file. See Pipelines.

A tour of the dashboard

Every image is captured from a real, running control plane by scripts/screenshots/capture.sh. Click one to open the guide for that screen.

1. Install and sign in _{The setup wizard checks the server and walks you to a first app.}	2. Connect a repo _{Pick a provider, let auto-detect choose the build.}	3. Watch it ship _{Every deploy is listed live, and rolling back is one click.}
Live logs _{Full-text search and live tail, stored on the node.}	Databases _{TLS, host-port exposure, and backups in one place.}	Domains and TLS _{Primary domain, ACME certificates, and HSTS.}

More screenshots

Apps	Deploy history and rollback
Deploy strategy	Right-sizing and cost
Environment and secrets	Backups
Nodes	Network topology
Pipelines	Template catalog
Load balancer	Public status page

How it works

flowchart LR
  Git["Git push<br/>or import"] --> API
  subgraph CP["Control plane (one Go binary)"]
    API["HTTP API<br/>+ dashboard"] --> DB[("SQLite")]
    API --> REC["Level-triggered<br/>reconciler"]
    API --> ING["Caddy ingress<br/>(automatic TLS)"]
    API --> BLD["BuildKit"]
  end
  REC <-->|"gRPC, mTLS<br/>(agent dials out)"| AG1["Node agent"]
  REC <-->|"in-process on<br/>a single node"| AG0["Local agent"]
  AG1 --> D1["Docker Engine API"]
  AG0 --> D0["Docker Engine API"]
  CLI["levelrail-cli<br/>and MCP server"] --> API

Control plane (cmd/levelrail): one Go binary with the dashboard embedded. It reconciles declarative desired state against observed Docker state, the Kubernetes controller pattern without the rest of Kubernetes.
Node agent (cmd/levelrail-agent): dials out to the control plane and streams Docker events up. In single-node mode it runs in-process, so one node and ten nodes share one code path.
Ingress: Caddy embedded as a library. Builds: BuildKit as a library, with Railpack detection for apps without a Dockerfile. State: SQLite in WAL mode, pure Go.
CLI and MCP: levelrail-cli and levelrail-mcp are thin clients over the same HTTP API under /api/v1.

Details: Architecture.

How it compares

Most self-hosted platforms in this category manage servers by SSHing in and shelling out to the docker CLI, then parsing text, which tends to force polling loops. Levelrail uses a reverse-dialed agent and a level-triggered reconciler instead.

	Levelrail	Coolify	Dokploy	CapRover	Dokku	Kamal
Node control	Reverse-dialed agent	SSH + CLI	SSH + Engine API	Swarm API	Local bash	SSH, one-shot
Orchestration	Level-triggered reconciler	Compose	Swarm	Swarm	Bash scheduler	None
Built-in metrics and logs	Yes	Opt-in add-on	Separate binary	No	No	No
Rollback	Pinned images, readiness-gated	Health check off by default	Swarm rollback	Manual	Default scheduler: none	Proxy health gate
Backup verification	Automatic, all 8 engines	Non-empty check	None	None	No backups	No backups

This is positioning, not a ranking, and all of them are worth using. The one area where Levelrail trails is breadth of templates: a smaller curated catalog than Coolify's, an intentional bet on curation (see ADR 015). The full, sourced comparison is in Comparison.

Footprint. Measured on an Apple M4 Max with a dev build and a loopback client, the idle control plane used 67.7 MB RSS and 0.03% CPU with 0 apps, and 90.8 MB RSS and 1.60% CPU with 500 suspended apps. No containers were running in that benchmark, so real apps add load it does not measure. Method and caveats: Performance.

Status

Releases are listed on the releases page, and every feature is labelled stable or beta, with the evidence behind it, on Feature status. Single node is the best-tested path. Anything marked beta works but has less real-world mileage, and a few areas stay off by default behind APP_EXPERIMENTAL. The roadmap lists what is done and what is next.

Guides

Step by step walkthroughs, each tested against a real install:

Guide	What you learn
What is Levelrail and who is it for	The overview, with an FAQ
Deploy a Next.js app with Postgres	Repo to HTTPS in about ten minutes
Deploy a Django app with Postgres	Plus the four errors everyone hits
Push to deploy with GitHub	Webhooks, previews and the delivery log
How deploys stay safe	Health gates, blue-green cutover, rollback
Logs, traces and errors without a stack	Observability and Grafana
Scale to zero on a small VPS	Run many projects on one box
Levelrail Pages	Static sites from git
Levelrail vs Coolify, Dokploy, CapRover, Dokku and Kamal	Where each one fits

For AI agents and crawlers

Agent skill: skills/levelrail/SKILL.md teaches a coding agent to deploy, wait, diagnose and roll back safely.
MCP server: levelrail-mcp exposes the same API and permission model. Start in read-only mode. See MCP and AI control.
Repo guide: AGENTS.md for working in this codebase, and llms.txt as the index.
Docs for LLMs: llms.txt and llms-full.txt.

Documentation

docs.levelrail.com: the hosted docs, with getting started, architecture, app spec reference, and the full index.
docs.levelrail.com/llms.txt: the docs index in a plain format for LLMs and AI assistants.
docs/: the same content as Markdown, for browsing on GitHub.
Start here: Getting started, Installing, App spec reference, CLI reference.

Community and support

GitHub Discussions: questions, ideas, show and tell.
GitHub Issues: bug reports and feature requests.
GLINR Discord: live chat with maintainers and other users, with a dedicated #levelrail forum channel.
support@levelrail.com: direct email support.
Security policy: report a vulnerability privately.
Contributing: dev loop, tests, and commit conventions.

Build from source

Needs Go 1.26 or newer and Docker.

go build ./cmd/levelrail
go build ./cmd/levelrail-agent
go build ./cmd/levelrail-cli

The frontend is a Vite project in web/ that is embedded into the control plane at build time. See Installing. Generic, stdlib-only Go packages (SSRF-safe HTTP client, cron parsing, health probes, and more) live in a separate module, kit/, usable without the platform.

Contributors

Star the repo

If Levelrail saves you a weekend, a star on GitHub helps other self-hosters find it. Bug reports and honest feedback help more.

License

Apache 2.0, see LICENSE.

Founding partners

Founding partner sites and libraries, from the same studio:


theSVG	A searchable library of brand SVG icons for developers and designers.
theauth	Open-source auth for AI agents and humans, with MCP OAuth 2.1 and audit.
AskVerdict AI	Structured multi-agent decisions for teams, with verdicts and action items.

Levelrail is built by Gagan Deep Singh, founder of GLINR STUDIOS and theSVG. Say hello at thegdsks.com.

_{Powered by GLINR STUDIOS · icon from theSVG}

Directories ¶

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL

Path	Synopsis
cmd
levelrail command Command levelrail is the control plane binary.	Command levelrail is the control plane binary.
levelrail-agent command Thin main: every behavior (enrollment, Session loop, Docker dispatch) lives in internal/agent.	Thin main: every behavior (enrollment, Session loop, Docker dispatch) lives in internal/agent.
levelrail-cli command Command levelrail-cli is a scriptable HTTP client for the control plane's /api/v1 API.	Command levelrail-cli is a scriptable HTTP client for the control plane's /api/v1 API.
levelrail-mcp command Command levelrail-mcp is an MCP server that lets an AI agent manage a control plane through its /api/v1 REST API.	Command levelrail-mcp is an MCP server that lets an AI agent manage a control plane through its /api/v1 REST API.
internal
accesspolicy Package accesspolicy merges per-team session rules into one effective set and answers the questions the API middleware asks on every request.	Package accesspolicy merges per-team session rules into one effective set and answers the questions the API middleware asks on every request.
agent Package agent is the transport boundary between reconcile controllers and the node they run on.	Package agent is the transport boundary between reconcile controllers and the node they run on.
agent/agentpb
agentinit Package agentinit renders the files "init" writes into a project: app.yaml, AGENTS.md and .mcp.json.	Package agentinit renders the files "init" writes into a project: app.yaml, AGENTS.md and .mcp.json.
ai Package ai implements the BYOK assistant chat: a provider-agnostic turn engine.	Package ai implements the BYOK assistant chat: a provider-agnostic turn engine.
alerting Package alerting implements threshold rules over internal/telemetry's metrics and logs, and crashloop detection as a built-in rule kind sharing the same evaluate/notify path rather than a separate mechanism.	Package alerting implements threshold rules over internal/telemetry's metrics and logs, and crashloop detection as a built-in rule kind sharing the same evaluate/notify path rather than a separate mechanism.
api Package api implements the HTTP API the web frontend (1.10) and, later, the MCP layer both build on.	Package api implements the HTTP API the web frontend (1.10) and, later, the MCP layer both build on.
apiclient Package apiclient is the one HTTP client implementation for the control plane's versioned API (internal/api, mounted at /api/v1).	Package apiclient is the one HTTP client implementation for the control plane's versioned API (internal/api, mounted at /api/v1).
appimport Package appimport turns a source platform's application inventory into a reviewed, staged import: per-app verdicts, a hostname mapping with a visible diff, preflight checks and a secret-free receipt.	Package appimport turns a source platform's application inventory into a reviewed, staged import: per-app verdicts, a hostname mapping with a visible diff, preflight checks and a secret-free receipt.
appsleep Package appsleep stops opted-in apps that have had no requests for a while and wakes them on the next request, so idle apps cost no memory or CPU.	Package appsleep stops opted-in apps that have had no requests for a while and wakes them on the next request, so idle apps cost no memory or CPU.
appwizard Package appwizard analyses a git repository through a provider file-tree API and returns pre-filled, evidence-backed suggestions for creating an app.	Package appwizard analyses a git repository through a provider file-tree API and returns pre-filled, evidence-backed suggestions for creating an app.
attention Package attention builds the list of things an operator should look at right now, shared by the CLI and the MCP server.	Package attention builds the list of things an operator should look at right now, shared by the CLI and the MCP server.
authengine Package authengine hosts the theauth-go library behind a flag.	Package authengine hosts the theauth-go library behind a flag.
autoscale Package autoscale is the deterministic replica autoscaler: a level-triggered controller that turns observed load into a desired replica count.	Package autoscale is the deterministic replica autoscaler: a level-triggered controller that turns observed load into a desired replica count.
backup Package backup drives a database backup end to end: dump a managed database container's data, stream it straight to an S3-compatible bucket, and record the attempt in store.BackupHistory.	Package backup drives a database backup end to end: dump a managed database container's data, stream it straight to an S3-compatible bucket, and record the attempt in store.BackupHistory.
bench Package bench is an open-loop HTTP load driver with failure-window analysis.	Package bench is an open-loop HTTP load driver with failure-window analysis.
bindaddr Package bindaddr resolves the small bind-address vocabulary app services and managed databases use to choose which network interface a published port binds to.	Package bindaddr resolves the small bind-address vocabulary app services and managed databases use to choose which network interface a published port binds to.
bindmount Package bindmount validates a service's bind-mount host path, shared by internal/compose and internal/spec: internal/compose imports internal/spec (a compose service expands into a spec.Service), so neither of those two packages can hold this logic without the other importing it back and cycling.	Package bindmount validates a service's bind-mount host path, shared by internal/compose and internal/spec: internal/compose imports internal/spec (a compose service expands into a spec.Service), so neither of those two packages can hold this logic without the other importing it back and cycling.
bitbucketapp Package bitbucketapp implements OAuth2 and the small slice of Bitbucket Cloud's REST API this control plane needs once connected.	Package bitbucketapp implements OAuth2 and the small slice of Bitbucket Cloud's REST API this control plane needs once connected.
brand Package brand provides the branding indirection layer this project requires: no product name is ever hardcoded in source.	Package brand provides the branding indirection layer this project requires: no product name is ever hardcoded in source.
build Package build drives container image builds through BuildKit's Go client (github.com/moby/buildkit/client), never by shelling out to `docker build` or the `docker` CLI, matching the same "no CLI shelling" rule the node communication layer follows.	Package build drives container image builds through BuildKit's Go client (github.com/moby/buildkit/client), never by shelling out to `docker build` or the `docker` CLI, matching the same "no CLI shelling" rule the node communication layer follows.
catalog Package catalog holds Levelrail's own curated set of one-click service templates (ADR 015).	Package catalog holds Levelrail's own curated set of one-click service templates (ADR 015).
changelog Package changelog parses the repo's release-please-maintained CHANGELOG.md into the entries GET /api/v1/changelog and the dashboard's "What's new" panel serve, so release notes keep exactly one source of truth instead of a second, hand-curated copy.	Package changelog parses the repo's release-please-maintained CHANGELOG.md into the entries GET /api/v1/changelog and the dashboard's "What's new" panel serve, so release notes keep exactly one source of truth instead of a second, hand-curated copy.
changes Package changes answers "what changed on this app recently" by merging the app event log, deploy attempts and the audit log into one ordered list.	Package changes answers "what changed on this app recently" by merging the app event log, deploy attempts and the audit log into one ordered list.
cliconsole Package cliconsole turns one typed console line into a vetted argv for the platform CLI and runs it as a child process.	Package cliconsole turns one typed console line into a vetted argv for the platform CLI and runs it as a child process.
clitree Package clitree is the CLI's command tree, shared by its shell completions and the control plane's web CLI console allowlist.	Package clitree is the CLI's command tree, shared by its shell completions and the control plane's web CLI console allowlist.
compliance Package compliance builds access reviews and signed evidence packs from data the platform already records.	Package compliance builds access reviews and signed evidence packs from data the platform already records.
compose Package compose parses a Docker Compose file into Levelrail's own desired-state model, in two shapes depending on the caller.	Package compose parses a Docker Compose file into Levelrail's own desired-state model, in two shapes depending on the caller.
costestimate Package costestimate is a deterministic, pure-Go engine that turns an app's CPU/memory allocation into an ESTIMATED monthly cost under a few generic reference pricing profiles (a plain VM, a managed VM, a metered container PaaS).	Package costestimate is a deterministic, pure-Go engine that turns an app's CPU/memory allocation into an ESTIMATED monthly cost under a few generic reference pricing profiles (a plain VM, a managed VM, a metered container PaaS).
cpbackup Package cpbackup manages control plane self-backups: verified SQLite snapshots kept in a directory under the data dir.	Package cpbackup manages control plane self-backups: verified SQLite snapshots kept in a directory under the data dir.
cutover Package cutover plans and runs a guided, reversible move of one staged import app: readiness rules, a persisted state machine, DNS undo data.	Package cutover plans and runs a guided, reversible move of one staged import app: readiness rules, a persisted state machine, DNS undo data.
dataexport Package dataexport sends logs, audit events and metrics to destinations an operator already runs.	Package dataexport sends logs, audit events and metrics to destinations an operator already runs.
datamigrate Package datamigrate copies live data from a source database into a managed database here, and checks a cutover is safe.	Package datamigrate copies live data from a source database into a managed database here, and checks a cutover is safe.
dbaccess Package dbaccess manages database users, temporary credentials and network scope.	Package dbaccess manages database users, temporary credentials and network scope.