levelrail

module

v0.2.0-beta.16 Latest Latest Go to latest Published: Oct 5, 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 · Install · Features · Screenshots · Compare · Discord

Table of contents

What is Levelrail?
Install
What you get
A tour of the dashboard
Status: pre-release
Why not Coolify or Dokploy?
How it is built
Build from source
Docs and community
Founding partners
Meet the founder
License

What is Levelrail?

Levelrail is a self-hosted, open-source deployment platform: an alternative to Heroku, Vercel, and Railway that runs on your own Linux servers. Push to a git repo and get a running app with HTTPS, logs, metrics, and one-click rollback.

It is built for people running 3 to 50 services on 1 to 10 machines who do not want to learn Kubernetes. Each server runs a small agent that talks to Docker's Engine API directly, so there is no SSH and no shelling out to the docker CLI. Metrics and logs are part of the core, not a Grafana you install afterwards.

Install

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.

curl -fsSL https://levelrail.com/install.sh | sudo sh

The installer checks the host, starts Levelrail as a systemd service, and prints a dashboard URL with a one-time setup token. Open it, choose a password, and the setup wizard takes you through a domain, a git provider, and your first app. About ten minutes, start to finish.

Prefer containers?

docker run -d -p 127.0.0.1:8080:8080 -v /var/run/docker.sock:/var/run/docker.sock \
  -v levelrail-data:/var/lib/levelrail-data ghcr.io/glincker/levelrail:beta

Images for linux/amd64 and linux/arm64 are published as :beta (use this until a stable release ships) and :edge. Upgrade and uninstall commands, pinning a version, the compose file, and the node agent image are in Installing and Docker. Walkthrough: Getting started.

Your first five minutes

Levelrail setup wizard running server checks on a fresh install

1. Install and sign in
_{One command, then the setup wizard checks the server and walks you to a first app.}

Levelrail Git source settings with GitHub, GitLab, Bitbucket, Gitea, and URL tabs

2. Connect a repo
_{Pick a provider, let auto-detect choose the build, deploy on every push.}

Levelrail Deployments page listing recent deploys and a rollback

3. Watch it ship
_{Every deploy is listed live, and rolling back is one click.}

What you get

Safe deploys. Rolling, recreate, or blue-green, gated on real readiness probes. Prior images are pinned, so rollback is always one click and garbage collection cannot remove the target.
Observability built in. Node-local metrics at 15 second resolution and full-text log search, with deploy markers drawn on the charts so "which deploy caused this" is visible at a glance.
Databases that verify their own backups. Postgres, Redis, MySQL, MongoDB, MariaDB, KeyDB, Dragonfly, and ClickHouse, with scheduled backups, restore, and an automatic re-download and checksum after every backup.
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.
Git-native. GitHub, GitLab, Bitbucket, and Gitea webhooks, preview environments per pull request, and an import box that accepts a repo URL, an image, a docker run command, or a compose file.
311 one-click templates for self-hosted services, each a compose file the platform deploys and manages.
Access control and audit. Allow and Deny IAM policies scoped to a single app or database, with a full audit log and CSV export, in the free Apache 2.0 core.
Alerting. Threshold, crashloop, and certificate expiry rules delivered over 18 notification kinds, including Slack, Discord, email, Telegram, PagerDuty, ntfy, and a generic webhook.
AI-ready. The HTTP API the dashboard uses also backs an MCP server with 156 tools, so an AI assistant can list apps, read logs, and diagnose a crashloop. AI never sits in the reconciliation path.

A tour of the dashboard

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

Deploy and observe

Apps _{Every service, its status, and where it runs.}	Deploy history and rollback _{Each release is pinned, so rollback is never a rebuild.}
Deploy strategy _{Blue-green, rolling, or recreate, plus pre and post deploy hooks.}	App overview _{Health, replicas, and recent activity for one app.}
Live logs _{Full-text search and live tail, stored on the node.}	Right-sizing and cost _{Limits suggested from real usage, with a what-it-costs-elsewhere estimate.}

Data and edge

Managed databases _{Postgres, Redis, MySQL, and more, one registry.}	Database overview _{TLS, host-port exposure, and backups in one place.}
Load balancer _{Per-upstream health once the ingress reconciler observes it.}	Domains and TLS _{Primary domain, ACME certificates, and HSTS.}
Environment and secrets _{Secrets are write-only and show their age.}	Backups _{Connect an S3-compatible target, then schedule from any database.}

Nodes, networking, and CI

Nodes _{Node health and placement across machines.}	Network topology _{How apps and nodes connect.}
Cloud node providers _{Create servers at Hetzner, DigitalOcean, AWS, or Azure from the Nodes page.}	Pipelines _{CI/CD runs on your own nodes, defined in a YAML file.}

Getting started and operations

Template catalog _{One-click services from a searchable catalog.}	CLI access _{Install the CLI and log in with a device code, no SSH key.}
Dashboard home _{Stats, recent activity, and a Needs attention list from the server checks.}	Public status page _{A read-only page with component status, off until you publish it.}

Status: pre-release

Levelrail is in active development and has no stable release yet. APIs, the app spec format, and the on-disk layout can change between betas, so do not run production workloads on it yet.

Maturity is uneven, and we label it feature by feature in Feature status. Single node is the well-tested path. Deploy approvals, database backups with point-in-time recovery, and GitHub previews are marked stable, each with a live end-to-end test. Multi-node enrollment, drain, and placement have run against two real Docker daemons, but the WireGuard mesh across hosts is still unverified. Most other areas are beta, and a few (in-app AI chat, GPU models, the load balancer, platform as code, Cloudflare tunnel) are off by default behind APP_EXPERIMENTAL. The roadmap has the current list of what is done and what is next.

Why not Coolify or Dokploy?

Most self-hosted platforms in this category manage servers by SSHing in and shelling out to the docker CLI, then parsing text. That is a common source of flakiness, and it forces polling loops. Levelrail does it differently:

Agent-based. A small agent on each node uses the Docker Engine API directly and streams container events up. The control plane never polls.
Observability in the core. Metrics and logs ship with the platform.
Small footprint. One static Go binary for the control plane and one for the agent, with embedded SQLite, an embedded Caddy ingress, and an embedded dashboard. Measured numbers and conditions are in Performance.

	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. All of them are worth using. The one area where Levelrail trails is breadth of templates: 311 curated entries against Coolify's roughly 370, an intentional bet on curation (see ADR 015). The full, sourced comparison is in Comparison.

How it is built

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. In single-node mode it runs in-process, so one node and ten nodes share one code path.
Ingress: Caddy embedded as a library, for automatic TLS and routing.
Builds: BuildKit as a library, with Railpack detection for apps without a Dockerfile.
State: SQLite in WAL mode via modernc.org/sqlite, pure Go.
CLI and MCP: levelrail-cli and levelrail-mcp are thin clients over the same HTTP API under /api/v1.

Details: Architecture.

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 and CONTRIBUTING.md for the dev loop, tests, and commit conventions.

Docs and community

levelrail.com -- the hosted docs site: getting started, architecture, app spec reference, roadmap, full index
docs/ -- the same content as plain Markdown, for browsing directly on GitHub
GitHub Discussions -- questions, ideas, show and tell
GLINR Discord -- live chat with maintainers and other users, with a dedicated #levelrail forum channel for questions and support
support@levelrail.com -- direct email support

Star history

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.

Meet the founder

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 Command levelrail-agent is the node agent binary (the repo layout names it, this is the first pass to actually build it).	Command levelrail-agent is the node agent binary (the repo layout names it, this is the first pass to actually build it).
levelrail-cli command Command levelrail-cli is a thin, scriptable HTTP client for the control plane's versioned API (internal/api, mounted at /api/v1), the first command-line surface this project has (cmd/levelrail is the control plane server, cmd/levelrail-agent is the node agent, neither is meant to be typed at by an operator).	Command levelrail-cli is a thin, scriptable HTTP client for the control plane's versioned API (internal/api, mounted at /api/v1), the first command-line surface this project has (cmd/levelrail is the control plane server, cmd/levelrail-agent is the node agent, neither is meant to be typed at by an operator).
levelrail-mcp command Command levelrail-mcp is an MCP (Model Context Protocol) server that lets an AI agent manage a control plane deployment through the same versioned REST API (internal/api, mounted at /api/v1) cmd/levelrail-cli already drives: see internal/apiclient's own doc comment, and internal/store/tokens.go's APIToken doc comment on why a bearer token was always meant to authenticate "a CLI, an MCP server, or a third-party integration" alike.	Command levelrail-mcp is an MCP (Model Context Protocol) server that lets an AI agent manage a control plane deployment through the same versioned REST API (internal/api, mounted at /api/v1) cmd/levelrail-cli already drives: see internal/apiclient's own doc comment, and internal/store/tokens.go's APIToken doc comment on why a bearer token was always meant to authenticate "a CLI, an MCP server, or a third-party integration" alike.
internal
agent Package agent is the transport boundary: the interface ADR 003 describes ("the reconciler and everything above the transport boundary never knows whether it's talking to a local in-process agent or a remote one over mTLS") but that Phase 1 never actually built, confirmed directly against this repo before writing this package: every reconcile controller (internal/reconcile/application, internal/reconcile/database) takes a bare docker.Runtime, and cmd/levelrail/main.go's dynamicSource hands every controller the same single local docker.Runtime with no node concept anywhere.	Package agent is the transport boundary: the interface ADR 003 describes ("the reconciler and everything above the transport boundary never knows whether it's talking to a local in-process agent or a remote one over mTLS") but that Phase 1 never actually built, confirmed directly against this repo before writing this package: every reconcile controller (internal/reconcile/application, internal/reconcile/database) takes a bare docker.Runtime, and cmd/levelrail/main.go's dynamicSource hands every controller the same single local docker.Runtime with no node concept anywhere.
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 AI assistant chat feature: a provider-agnostic turn engine (engine.go) that runs a conversation against an LLM (Provider below) with tool use backed by the existing MCP tool surface (toolcaller.go, internal/mcptools), pausing every mutating tool call for an explicit human confirmation click (classify.go).	Package ai implements the BYOK AI assistant chat feature: a provider-agnostic turn engine (engine.go) that runs a conversation against an LLM (Provider below) with tool use backed by the existing MCP tool surface (toolcaller.go, internal/mcptools), pausing every mutating tool call for an explicit human confirmation click (classify.go).
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).
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.
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.
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.
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.
cronexpr Package cronexpr parses and evaluates standard 5-field cron expressions ("minute hour day-of-month month day-of-week", e.g.	Package cronexpr parses and evaluates standard 5-field cron expressions ("minute hour day-of-month month day-of-week", e.g.
deploy Package deploy is the build integration: it connects internal/spec's build declaration to internal/build's BuildKit client, and a successful build's output to internal/store's desired state, closing the loop the application controller (internal/reconcile/ application) reads from on every reconcile.	Package deploy is the build integration: it connects internal/spec's build declaration to internal/build's BuildKit client, and a successful build's output to internal/store's desired state, closing the loop the application controller (internal/reconcile/ application) reads from on every reconcile.
deploylog Package deploylog is the glue between internal/build.ProgressEvent (the progress callback all three real deploy-attempt trigger paths already thread through internal/deploy.Pipeline.Deploy) and two real consumers: a persisted, replayable row in telemetry.db (internal/telemetry's deploy_logs table) and any currently-connected SSE viewer watching that same attempt live.	Package deploylog is the glue between internal/build.ProgressEvent (the progress callback all three real deploy-attempt trigger paths already thread through internal/deploy.Pipeline.Deploy) and two real consumers: a persisted, replayable row in telemetry.db (internal/telemetry's deploy_logs table) and any currently-connected SSE viewer watching that same attempt live.
diagnose Package diagnose is a deterministic, pure-Go pattern matcher over diagnostic signals the platform already collects: deploy attempt status/error, reconcile condition reason strings, crashloop alert state, and recent log lines.	Package diagnose is a deterministic, pure-Go pattern matcher over diagnostic signals the platform already collects: deploy attempt status/error, reconcile condition reason strings, crashloop alert state, and recent log lines.
diskspace Package diskspace provides a single, reusable free-disk-space check (statfs's Bavail, the same "free space an unprivileged user could actually write" number GET /api/v1/system/doctor's disk_space check and GET /api/v1/system/status already surface), so disk-heavy operations elsewhere in this codebase (BuildKit builds, backup bookkeeping) can gate on it without reimplementing the syscall.	Package diskspace provides a single, reusable free-disk-space check (statfs's Bavail, the same "free space an unprivileged user could actually write" number GET /api/v1/system/doctor's disk_space check and GET /api/v1/system/status already surface), so disk-heavy operations elsewhere in this codebase (BuildKit builds, backup bookkeeping) can gate on it without reimplementing the syscall.
dnsrecords Package dnsrecords builds a provider-agnostic DNS record manager from whichever ACME DNS-01 provider a control plane already has credentials for (Cloudflare or Route53), reusing libdns's own interfaces instead of inventing a second one: github.com/libdns/cloudflare and github.com/libdns/route53, both already a dependency via internal/ingress's Caddy DNS-01 wiring, implement them already.	Package dnsrecords builds a provider-agnostic DNS record manager from whichever ACME DNS-01 provider a control plane already has credentials for (Cloudflare or Route53), reusing libdns's own interfaces instead of inventing a second one: github.com/libdns/cloudflare and github.com/libdns/route53, both already a dependency via internal/ingress's Caddy DNS-01 wiring, implement them already.
docker Package docker wraps the Docker Engine API.	Package docker wraps the Docker Engine API.
dockerhub Package dockerhub implements a minimal client for Docker Hub's public, unauthenticated Hub API: repository search and tag listing, used to let an operator discover a well-known public image from the app-creation "docker image" step (RegistryImagePicker.tsx) instead of typing a reference blind.	Package dockerhub implements a minimal client for Docker Hub's public, unauthenticated Hub API: repository search and tag listing, used to let an operator discover a well-known public image from the app-creation "docker image" step (RegistryImagePicker.tsx) instead of typing a reference blind.
dockertest Package dockertest holds test helpers shared by every package whose _live_test.go files need a real Docker daemon (or other real, network-dependent infra) to run.	Package dockertest holds test helpers shared by every package whose _live_test.go files need a real Docker daemon (or other real, network-dependent infra) to run.
email Package email is the platform's one email-sending capability: a narrow Sender interface plus SMTP, SES, and Resend implementations, shared by internal/alerting and internal/api so neither imports the other.	Package email is the platform's one email-sending capability: a narrow Sender interface plus SMTP, SES, and Resend implementations, shared by internal/alerting and internal/api so neither imports the other.
experimental Package experimental is the single platform gate for features hidden at launch.	Package experimental is the single platform gate for features hidden at launch.
failure Package failure classifies a failed, held or unhealthy deploy into one structured object shared by the API, CLI and MCP surfaces.	Package failure classifies a failed, held or unhealthy deploy into one structured object shared by the API, CLI and MCP surfaces.
firewall Package firewall manages host ufw rules as declarative allow/deny records.	Package firewall manages host ufw rules as declarative allow/deny records.
forecast Package forecast projects a resource's usage trend forward with a plain ordinary-least-squares line fit over recent (timestamp, bytes used) samples: deterministic, pure-Go, no external model, the same read-and-suggest shape internal/rightsizing already establishes.	Package forecast projects a resource's usage trend forward with a plain ordinary-least-squares line fit over recent (timestamp, bytes used) samples: deterministic, pure-Go, no external model, the same read-and-suggest shape internal/rightsizing already establishes.