levelrail

module

v0.8.0 Latest Latest Go to latest Published: Oct 21, 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

The lightweight, self-hosted alternative to Vercel, Netlify, Heroku, Railway, Coolify and Dokku.
Deploy on git push, with logs, metrics, HTTPS and one-click rollback, on your own servers. HTTPS is self-signed until you enable Let's Encrypt.
One Go binary · Docker runtime · agents instead of SSH · observability built in · no Kubernetes

Website · Docs · Install · Production ready · Compare · Guides · Roadmap · Changelog · Discussions · Discord

Levelrail is an open source (Apache 2.0) self-hosted PaaS: a Vercel and Heroku alternative that runs on any Linux server you own, from a small VPS to a rack (the one measured host is a 2 vCPU, 8 GB box). It turns plain servers into a private cloud with Git deploys (forge webhooks), HTTPS (self-signed by default, Let's Encrypt when enabled), databases with verified backups, metrics, logs and alerts, without Kubernetes and without the monitoring stack you would otherwise bolt on.

Quickstart

You need a Linux server (amd64 or arm64) with systemd and root. The installer adds Docker if it is missing.

1. Install the server

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

The last lines of output include the dashboard address and a one-time setup link:

Levelrail vX.Y.Z installed and running.

Open the dashboard:
  http://203.0.113.10:8080/login?setup=<token>

2. Create the admin account

Open the setup link and choose a password. The first sign-in opens one screen that turns on a free certificate for <dashed-ip>.sslip.io with one click (no DNS needed) and deploys your first app.

3. Deploy an app

On the server, the installer already put levelrail-cli in /usr/local/bin. Sign in once, then import a repository (levelrail-cli apps create --interactive asks for everything step by step):

levelrail-cli login --api-url http://<server-ip>:8080 --code ABCD-EF23
levelrail-cli import https://github.com/your-org/your-app --deploy

Prefer containers, a pinned version or a source build? See Installing. Want it as light as Dokku, or everything on? install.sh --profile minimal|standard|suite, see Server profiles. Coming from another platform? See Migrate to Levelrail: Coolify, Dokploy, CapRover, Dokku and compose files each get a dry run first, and the old server keeps serving.

After setup, the dashboard home shows a Connect your CLI card. Press Show my command, paste the line into your terminal, and the CLI signs in with a single-use code that expires in minutes (no password, no approval step):

logged in as "you@example.com"
token tk_9fQ2x saved to ~/.config/levelrail-cli/credentials under profile "default", expires 2027-01-18

Signing in with your password from a new device needs approval: the CLI prints the dashboard page to approve it on and the number to type. login --device also still works.

Without --deploy, import only prints the deployment plan. To see the app's address, run levelrail-cli open your-app. It prints the custom domain first, then the automatic URL.

If something fails

Step	Error you see	Fix
Install	`control plane did not become healthy within 60s`	`systemctl status levelrail` and `journalctl -u levelrail -n 100 --no-pager`. A port already in use is a common cause.
Install	`could not list releases from GitHub. Set LEVELRAIL_VERSION=vX.Y.Z to pin one.`	The server cannot reach GitHub. Check outbound HTTPS, or pin a release.
Install	`checksum mismatch for ...`	Do not continue. Run the installer again. Do not set `LEVELRAIL_SKIP_CHECKSUM=1` to get past it.
Login	`start device login: ... connection refused`	The CLI points at the wrong address. Run `export APP_API_URL=http://127.0.0.1:<dashboard port>` and try again.
Import	`plan import: ... connection refused`	The control plane is not running. Start it with `systemctl start levelrail`.

More fixes: Troubleshooting. Full install options (Docker image, pinned version, source build): Installing. Deploy from a local project with levelrail-cli up: One command quickstart. Server profiles (install.sh --profile minimal|standard|suite): Server profiles. Migrating from another platform? levelrail-cli import platform coolify|dokploy|caprover --dry-run shows what would be created first, and the old server keeps serving. Full guide: Migrate to Levelrail.

_{Install, then deploy}

_{Gated deploy, one-step rollback}

Why people pick Levelrail

Lightweight. About 200 MB of RAM and roughly 1.5% of one CPU idle, measured on a 2 vCPU, 8 GB Linux test box with no apps under load and the default feature set (one run, 2026-10-19). Numbers and method.
Agents, not SSH. Each node runs a small agent that dials out over mTLS and talks to Docker's Engine API directly. No inbound ports, no shelling out to the docker CLI, no polling loops.
Observability included. Per-node metrics at 15 second resolution, searchable logs, deploy markers, traces, SLO burn, alert inbox and an idle-footprint health page. No Grafana stack to install.
Deploys that protect you. Readiness-gated rollouts, pinned images for rollback, canary releases that roll back on errors, deploy diffs, approvals and freezes.
Secure by default. Hash-chained audit log you can verify, SSRF-guarded outbound calls, envelope-encrypted secrets with key rotation, scoped tokens, passkeys and TOTP 2FA, OAuth and OIDC sign-in, IAM policies, signed releases. SAML single sign-on and SCIM provisioning are available as a beta feature, off by default.
Built for AI agents. An MCP server with over 240 tools in on-demand toolsets (small default list, about 2.4k tokens; see tool surface), a scoped-token permission model and an agent skill.

Production ready, with receipts

Single-server deployments are production ready today. Multi-node and a handful of newer features are labelled beta, and every label links to its evidence.

Claim	Evidence
Every feature is labelled stable or beta	Feature status: the tests, live e2e runs and docs behind each label
Survives failures	Resilience: disk full, agent link loss, database damage with guided restore, safe-mode boot, reconcile storm protection
Safe upgrades and rollback	Tested upgrade matrix, downgrade refusal, one-click rollback and clean shutdown
Measured, not promised	Benchmarks: idle footprint, ingress throughput, limits, with the method next to every number
Verified backups	Every backup is re-downloaded and checksummed, with scheduled restore drills
Tamper-evident security	Verifiable audit chain, security policy, signed releases and SBOM scanning

Levelrail vs Coolify, Dokploy, CapRover and Dokku

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
Node control	Reverse-dialed agent	SSH + CLI	SSH + Engine API	Swarm API	Local bash
Orchestration	Level-triggered reconciler	Compose	Swarm	Swarm	Bash scheduler
Built-in metrics and logs	Yes	Opt-in add-on	Separate binary	No	No
Rollback	Pinned images, readiness-gated	Health check off by default	Swarm rollback	Manual	Default scheduler: none
Backup verification	Automatic, all 8 engines	Non-empty check	None	None	No backups
SSO and provisioning	OAuth (20 providers) and generic OIDC; SAML and SCIM (beta, off by default)	See their docs	See their docs	See their docs	See their docs
Audit log	Hash-chained, verifiable, CSV export, forwarding to syslog, webhook or bucket	See their docs	See their docs	See their docs	See their docs
IAM	Allow and Deny policies per app or database, scoped tokens	See their docs	See their docs	See their docs	See their docs

This is positioning, not a ranking, and every project here is worth using. Where Levelrail trails: it is the youngest project here, with fewer users and less production mileage, and its SAML single sign-on and SCIM provisioning are beta (details). Its template catalog (about 360 entries) is in the same range as Coolify's, but only a sample is deployed end to end (ADR 015). The full, sourced comparison is in Comparison.

What you get

Deploys: Push to your git host (GitHub, GitLab, Bitbucket, Gitea webhooks), deploys start from a forge webhook (a native git push remote is beta and off by default), preview environments per pull request (stable on GitHub, beta on GitLab and Bitbucket), framework presets (Next.js, Go, React, Spring Boot and more), Dockerfile, Compose or image deploys, canary and blue-green rollouts. Readiness-gated cutover is live-tested with zero failed requests on a single node; multi-node is beta. Deploying apps
Domains and TLS: Embedded Caddy ingress. The default certificate is internal (self-signed). Public Let's Encrypt is one toggle and was verified in one live run; renewal and DNS-01 wildcards are unverified. Custom certificates can be uploaded. Per-app abuse protection. Domains
Databases: Postgres, MySQL, MariaDB, MongoDB, Redis, KeyDB, Dragonfly and ClickHouse with scheduled backups, Postgres point-in-time recovery, restore, and password rotation. Databases
One search for everything: Cmd+K across apps, databases, nodes, templates and actions, filtered by what you may do. Search
Servers: Add nodes with a one-time token, WireGuard mesh, zones and failure-domain spreading, placement what-if. Multi-node
Templates: about 360 one-click services, with a smoke test that brings up the top 50 (48 pass today, status). Catalog
Identity and access: Password, passkeys, TOTP, OAuth with 20 providers plus generic OIDC, IAM policies, teams, a hash-chained audit log with CSV export. SAML single sign-on and SCIM provisioning are beta and off by default. Identity and access, SAML and SCIM
Plugins: A signed plugin marketplace with one-click install, dashboard panels and first-party alert channels. Plugins
Automation: One HTTP API behind the dashboard, a CLI and an MCP server. AI never sits in the reconciliation path. CLI, AI control
Pipelines, previews, cost budgets, sleep when idle, status pages and more. See Product tour.

_{Live deploys}

_{One search for everything}

_{Health and footprint}

_{Verified backups}

_{Plugin marketplace}

_{Security center}

More screenshots (50 screens, shown in your GitHub theme, dark or light)

_{See every sign-in and change made to your account.}

_{Export your data or delete your account safely.}

_{Add, test and remove passkeys, synced or device-bound.}

_{Deploy strategy, health checks, and rollout behavior.}

_{Environment variables, with secrets masked.}

_{Per-app metrics, with deploy markers on every chart.}

_{Each app's overview in one place.}

_{Resource limits per app.}

_{Where an app's code comes from.}

_{Every app, its health, and its last deploy.}

_{Archive logs to a bucket on a schedule.}

_{Backups with a history you can restore from.}

_{Opt in to beta features one at a time.}

_{Build cache: rebuilds reuse unchanged layers.}

_{Build speed: how long builds take and what they cost.}

_{Report deploys back to GitHub Actions.}

_{Sign in the CLI from your own machine, with tokens you can revoke.}

_{Jump to any app or action with Cmd+K.}

_{One search across apps, databases, nodes and actions.}

_{Live health of the control plane itself.}

_{The control plane at a glance.}

_{Connection details and password rotation for a database.}

_{Database backups and placement, on the database's own page.}

_{One database, its connection details, and its state.}

_{Managed Postgres and friends, next to your apps.}

_{Deploy history, with promote and logs for each release.}

_{Watch a deploy roll out, step by step, as it happens.}

_{Deployments across the whole control plane.}

_{Domains, certificates, and where each one routes.}

_{Master and per-app encryption key status and rotation.}

_{Pick a framework preset and the build settings fill in for you.}

_{A guided checklist from install to your first deploy.}

_{Automatic cleanup of old images, containers, and logs.}

_{Load balance an app across replicas with health checks.}

_{Search and tail container logs without installing anything.}

_{Private networks decide which apps can reach each other.}

_{Add a server from a cloud provider.}

_{Nodes the control plane places apps and databases on.}

_{A pipeline run with its stages, jobs, and live log.}

_{Pipelines: CI-style jobs that run on the control plane.}

_{Manage the plugins you have installed and their permissions.}

_{Install signed plugins in one click.}

_{A security score with the checks that need attention.}

_{Your account, your password, your sessions.}

_{Instance name, dashboard URL and defaults.}

_{Spot misconfigured settings and fix them with one click.}

_{First-run setup, step by step.}

_{A public status page for your apps.}

_{Connect an S3-compatible bucket for backups and archives.}

_{Install a known service from the template catalog.}

All captured from a real running control plane. Walk through them in the Product tour.

Guides

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

Guide	What you learn
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 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.

Community and support

GitHub Discussions for questions, ideas and show and tell, and Issues for bugs.
GLINR Discord: live chat with the maintainers, in the #levelrail forum channel.
support@levelrail.com for direct help, and the Security policy to report a vulnerability privately.
Contributing: dev loop, tests and commit conventions. Build from source needs Go 1.26 or newer and Docker: see Installing.

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 even more.

License

Apache 2.0, see LICENSE.

Built by

Levelrail is built by Gagan Deep Singh, founder of GLINR STUDIOS and theSVG. Sister projects: theSVG (brand icon library), theauth (open-source auth for AI agents and humans) and AskVerdict AI. 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.
archive Package archive moves cold rows out of the live database into zstd compressed NDJSON bundles in a local directory, and can list, browse, restore and verify them.	Package archive moves cold rows out of the live database into zstd compressed NDJSON bundles in a local directory, and can list, browse, restore and verify them.
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.
bitbucketserver Package bitbucketserver is a small client for Bitbucket Server and Data Center (REST /rest/api/1.0), authenticated with a personal access token.	Package bitbucketserver is a small client for Bitbucket Server and Data Center (REST /rest/api/1.0), authenticated with a personal access token.
branchdeploy Package branchdeploy holds the pure rules for branch deploys: which branches qualify and what stable name a branch gets.	Package branchdeploy holds the pure rules for branch deploys: which branches qualify and what stable name a branch gets.
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.
canary Package canary decides when a staged canary release advances, promotes or rolls back, and runs the level-triggered reconciler that applies it.	Package canary decides when a staged canary release advances, promotes or rolls back, and runs the level-triggered reconciler that applies it.
canarypolicy Package canarypolicy holds the stage schedule, thresholds and env defaults of staged canary releases.	Package canarypolicy holds the stage schedule, thresholds and env defaults of staged canary releases.
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).
certflow Package certflow decides whether a domain is ready for a public certificate, tells operators the truth about the certificate it has, and retries stuck renewals with backoff.	Package certflow decides whether a domain is ready for a public certificate, tells operators the truth about the certificate it has, and retries stuck renewals with backoff.
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.
chaos Package chaos describes the failure scenarios the platform is measured against and the result record they produce.	Package chaos describes the failure scenarios the platform is measured against and the result record they produce.
chaos/live Package live runs the chaos scenarios against real local Docker containers that carry a unique name prefix and are always removed afterwards.	Package live runs the chaos scenarios against real local Docker containers that carry a unique name prefix and are always removed afterwards.
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.