OS
Linux, systemd
Linux, amd64 or arm64, with systemd. Tested in CI on Ubuntu 24.04 and Debian 12. Other distros should work but are untested. Windows and other non-Linux systems are not supported.
Install
For a Linux server you own. The installer always picks the newest stable release, and sets up Docker if it is missing.
A single node is the well-tested path and multi-node is in beta. Pre-releases are only installed if you choose the beta channel.
curl -fsSL https://levelrail.com/install.sh | sudo sh# Checks the host and installs Docker if it is missing# Installs the control plane and starts it as a systemd service# Prints the dashboard URL and a one-time setup token
Run it as root on the server. Then open the setup link it prints. Prefer to read it first? install.sh at v1.4.0
The path
Four steps, about five minutes. These are real screens from a fresh install.
Step 1
One command as root. It checks the host and installs Docker if needed.
$ curl -fsSL https://levelrail.com/install.sh | sudo sh Step 2
The summary prints the dashboard URL and a one-time token. Valid for 15 minutes, print a new one any time.
$ sudo APP_DATA_DIR=/var/lib/levelrail-data levelrail setup-token Step 3
Open the setup link, paste the token and pick a username and password.
Step 4
The sample app goes healthy with an automatic address. Then enable HTTPS from Domains.
Check the server first. A read-only readiness report that changes nothing and runs without root:
curl -fsSL https://levelrail.com/install.sh | sh -s -- --check
Before you start
OS
Linux, amd64 or arm64, with systemd. Tested in CI on Ubuntu 24.04 and Debian 12. Other distros should work but are untested. Windows and other non-Linux systems are not supported.
Docker
24 or newer. The installer sets it up through get.docker.com if it is missing.
Access
Root, plus curl.
Ports on the control plane node
80/tcp and 443/tcp inbound. Port 80 is needed for Let's Encrypt HTTP-01. 443/udp is optional, for HTTP/3.
Ports on agent-only nodes
None. Agents dial out to the control plane.
Starting size
1 vCPU, 1 GB RAM and 10 GB disk boots Docker and the control plane. 2 vCPU, 2 GB RAM and 20 GB disk is more comfortable once builds and apps run. No minimum has been benchmarked or published yet.
Supported hosts: any Linux server with systemd on amd64 or arm64, such as a home server, a VPS, an EC2 instance or a Google Cloud VM. The installer has no distro allowlist, it checks for Linux, systemd, curl and a usable Docker. Ubuntu 24.04 and Debian 12 are the ones tested in CI, so treat other distros as untested.
Downloads
Every file below is from the v1.4.0 release on GitHub. The one-line installer does all of this for you, including checksum and signature checks. Use these when you want the files yourself.
For a first install, use the one-line command at the top: it also writes the systemd unit and prints your setup token. These commands download the bare binary, check it and put it in place, which is the manual route.
curl -LO https://github.com/glincker/levelrail/releases/download/v1.4.0/levelrail-linux-amd64
curl -LO https://github.com/glincker/levelrail/releases/download/v1.4.0/checksums.txt
sha256sum --ignore-missing -c checksums.txt
chmod +x levelrail-linux-amd64
sudo install -m 0755 levelrail-linux-amd64 /usr/local/bin/levelrail Expected SHA-256 for v1.4.0
534cf5bbc3206a54a48f048464a7a792f32fe3358802681e94d4b2fc955f1b1e levelrail-linux-amd64 Also for linux amd64
For a first install, use the one-line command at the top: it also writes the systemd unit and prints your setup token. These commands download the bare binary, check it and put it in place, which is the manual route.
curl -LO https://github.com/glincker/levelrail/releases/download/v1.4.0/levelrail-linux-arm64
curl -LO https://github.com/glincker/levelrail/releases/download/v1.4.0/checksums.txt
sha256sum --ignore-missing -c checksums.txt
chmod +x levelrail-linux-arm64
sudo install -m 0755 levelrail-linux-arm64 /usr/local/bin/levelrail Expected SHA-256 for v1.4.0
16d2b75126403a2901f5e31712ec8d166ebc42cde4a9ad06fb3c9bb679b037f4 levelrail-linux-arm64 Also for linux arm64
Multi-arch images for linux/amd64 and linux/arm64, signed with cosign. Pin the exact tag for anything you care about staying still. The installer remains the recommended path for a real single-node server because it also provisions Docker and a systemd unit.
docker pull ghcr.io/glincker/levelrail:v1.4.0
docker pull ghcr.io/glincker/levelrail-agent:v1.4.0 docker run -d \
--name levelrail \
-p 80:80 -p 443:443 -p 127.0.0.1:8080:8080 \
-v /var/run/docker.sock:/var/run/docker.sock \
--group-add $(stat -c '%g' /var/run/docker.sock) \
-v levelrail-data:/var/lib/levelrail-data \
-e APP_DATA_DIR=/var/lib/levelrail-data \
ghcr.io/glincker/levelrail:v1.4.0 Port 8080 is bound to the loopback address. Tunnel to it for the first sign-in, then print the setup token from inside the container. The container gets access to the Docker socket, so only run it on a host you already trust with that.
ssh -L 8080:127.0.0.1:8080 user@your-server
docker exec levelrail levelrail setup-token Moving tags: :latest and :v0.8 follow stable releases, :beta follows pre-releases.
To control an existing instance from your laptop or a CI runner, install just the CLI. The server installer sets up the server, not a remote client.
curl -fsSL https://levelrail.com/install-cli.sh | shOn macOS and Linux it detects your architecture, checks the checksum and installs to ~/.local/bin, or /usr/local/bin with sudo. Or download the binary yourself:
Verify
Every release file is listed in checksums.txt, and checksums.txt itself is signed with cosign keyless signing from this repository's release workflow.
Run it in the folder with the file and checksums.txt. It skips files you did not download.
sha256sum --ignore-missing -c checksums.txt 534cf5bbc3206a54a48f048464a7a792f32fe3358802681e94d4b2fc955f1b1e levelrail-linux-amd6416d2b75126403a2901f5e31712ec8d166ebc42cde4a9ad06fb3c9bb679b037f4 levelrail-linux-arm64 Needs cosign. The identity pattern is the one the installer itself uses.
curl -LO https://github.com/glincker/levelrail/releases/download/v1.4.0/checksums.txt
curl -LO https://github.com/glincker/levelrail/releases/download/v1.4.0/checksums.txt.sigstore.json
cosign verify-blob --bundle checksums.txt.sigstore.json \
--certificate-identity-regexp 'https://github.com/glincker/levelrail/\.github/workflows/release\.yml@.*' \
--certificate-oidc-issuer https://token.actions.githubusercontent.com \
checksums.txt Checked against the v1.4.0 digest from the release notes. Images also carry an SBOM and provenance.
cosign verify ghcr.io/glincker/levelrail@sha256:328f2a1a5ad505173c1182df00d7253d93a033d160a63eed56478dcd71e9cb1f \
--certificate-identity-regexp 'https://github.com/glincker/levelrail/\.github/workflows/release\.yml@.*' \
--certificate-oidc-issuer https://token.actions.githubusercontent.com Release files: checksums.txt, checksums.txt.sigstore.json. More in the signature docs.
The installer already fails loudly if the control plane is not healthy within 60 seconds. You can re-check at any time.
Health check answers
curl -fsS http://127.0.0.1:8080/healthz Setup status is true until the first admin exists
curl -fsS http://127.0.0.1:8080/api/v1/auth/setup-status The service is active
systemctl status levelrail Back up the master key in /var/lib/levelrail-data. Every stored secret is encrypted with it.
Versions and channels
By default the installer picks the newest stable release. Set LEVELRAIL_VERSION to install an exact tag, or LEVELRAIL_CHANNEL=beta to follow pre-releases.
curl -fsSL https://levelrail.com/install.sh | sudo env LEVELRAIL_VERSION=v1.4.0 sh curl -fsSL https://levelrail.com/install.sh | sudo env LEVELRAIL_CHANNEL=beta sh Beta follows the newest pre-release. Use it for testing, not for the server your team depends on.
Stay current
Replaces the binary and restarts the service, keeping the unit file and your data. The previous binary is kept for rollback.
curl -fsSL https://levelrail.com/install.sh | sudo sh -s upgrade curl -fsSL https://levelrail.com/install.sh | sudo env LEVELRAIL_VERSION=v1.4.0 sh -s upgrade levelrail-cli upgrade
levelrail-cli upgrade --apply Runs read-only preflight checks first and rolls back automatically if the new release is not healthy within 90 seconds. The same flow is in Settings, Updates. Upgrade docs
Remove
Removes the service, unit file and binary, and keeps your data.
curl -fsSL https://levelrail.com/install.sh | sudo sh -s uninstall curl -fsSL https://levelrail.com/install.sh | sudo sh -s uninstall --purge --purge also deletes the data directory: the database, the master key and certificates. That removes all app and deploy state and the key your secrets are encrypted with.
Neither command removes Docker, the containers, images and volumes of your deployed apps, or levelrail-cli.
Network and service
| Port | Direction | Used for |
|---|---|---|
80/tcp | Inbound | HTTP, and the Let's Encrypt HTTP-01 challenge. Never moved by the installer on its own. |
443/tcp | Inbound | HTTPS for the dashboard and your apps. |
443/udp | Optional | HTTP/3. |
8080/tcp | Dashboard and API | The first-run setup link. Plain HTTP. If something else holds 8080 the installer picks the next free port and prints it. |
None | Agent-only nodes | Agents dial out to the control plane, so they need no inbound ports. |
sudo ufw allow 80/tcp && sudo ufw allow 443/tcp Or use your cloud provider's security group. Set LEVELRAIL_CONFIGURE_UFW=1 on the installer to have it add the rules.
sudo systemctl status levelrail
sudo systemctl restart levelrail
sudo journalctl -u levelrail -n 50 The installer writes the unit plus a drop-in at /etc/systemd/system/levelrail.service.d/10-install.conf holding your ports. Upgrades read it back and do not rewrite it.
You are piping a script into a root shell, so here is exactly what it does. The script is open source and you can read it first.
The host is missing something the installer needs: Docker 24 or newer, free ports 80 and 443, 1 GB RAM or 10 GB free disk. Run the read-only check (no root needed) to see which one failed, fix it and run the installer again. Pass --force to continue past a failed check, or set LEVELRAIL_COEXIST=1 if the ports are taken.
curl -fsSL https://levelrail.com/install.sh | sh -s -- --check Another process may hold the port, or the service failed to bind. Read the unit status and the last journal lines, and check which process owns 8080 or the port you set with LEVELRAIL_DASHBOARD_PORT. Restart the service once it is fixed.
sudo systemctl status levelrail
sudo journalctl -u levelrail -n 50 Docker may not be running or its socket is not at /var/run/docker.sock. Confirm Docker itself works, then see the full error from levelrail-cli. Start Docker with systemctl, or set DOCKER_HOST for a non-standard socket.
sudo docker ps
levelrail-cli status --json The setup token is single-use and valid for 15 minutes, and the dashboard port may differ from the default. Print a new token on the server, then open the login page with it.
sudo APP_DATA_DIR=/var/lib/levelrail-data levelrail setup-token More cases are in the troubleshooting docs.
Run curl -fsSL https://levelrail.com/install.sh | sudo sh on a Linux server with systemd. It checks the host, installs Docker if needed, installs the control plane and prints a one-time setup link for the first admin.
A Linux server (amd64 or arm64) with systemd, root access, curl and ports 80 and 443 open. 1 vCPU, 1 GB RAM and 10 GB disk is a starting point. Ubuntu 24.04 and Debian 12 are tested in CI.
No. Nodes must be Linux. You can still control a server from any machine with the CLI or the dashboard.
Run the installer with the uninstall argument. It removes the service, unit file and binary and keeps your data unless you add --purge. It does not remove Docker or the containers and volumes of your deployed apps.
One command installs the control plane. Then deploy your first app.
curl -fsSL https://levelrail.com/install.sh | sudo sh