I turned my whole server into a YAML file, and every change gets a diff first
Last month I added a domain to an app at midnight, clicked through three dashboard pages, and could not tell the next morning which of my changes had caused a restart. The server worked. I just had no record of why it looked the way it did.
I tried the other way: write down what the server should look like, ask the control plane what would change, and only then apply it. Levelrail calls this platform as code. Here is what I ran, with the real output, on a throwaway local instance.
TL;DR
| Step | Command | What you get |
|---|---|---|
| Preview | levelrail-cli apply -f infra/ --dry-run --exit-code |
A field level plan, exit code 2 if anything would change |
| Apply | levelrail-cli apply -f infra/ --source infra-repo --yes |
Resources created in dependency order |
| Check drift | levelrail-cli diff -f infra/ --source infra-repo |
Exit code 2 when live state differs from the files |
| Capture | levelrail-cli export --project shop -o infra/ |
Existing projects and apps written as YAML |
One caveat up front. The docs label this feature experimental, and it ships off. You turn it on with APP_EXPERIMENTAL=iac on the control plane and in the shell where you run the CLI. I used that flag for everything below.
The files
A file holds one or more YAML documents separated by ---. Each has version: 1, a kind (Project, Environment, Tag, Database, App, Domain, LoadBalancer, Pipeline or AlertRule), a name and a spec. This is the whole file I used, a project with an environment, a Postgres database and one app:
version: 1
kind: Project
metadata: { name: w2f-shop }
---
version: 1
kind: Environment
metadata: { name: production }
spec:
project: w2f-shop
---
version: 1
kind: Database
metadata: { name: w2f-main-db }
spec:
engine: postgres
version: "16"
project: w2f-shop
---
version: 1
kind: App
metadata: { name: w2f-web }
spec:
project: w2f-shop
environment: production
service:
build: { type: image, image: "traefik/whoami:v1.10.3" }
port: 80
domains: [w2f-web.localhost]
env:
LOG_LEVEL: info
DATABASE_URL: { from: { database: w2f-main-db, field: url } }
Two details are worth knowing. The DATABASE_URL line is a reference, not a value. The docs say apply never reads the connection string, so the file, the plan and the stored revisions only ever hold w2f-main-db.url. And documents never contain secret values: the CLI rejects a literal on a key that looks like a password or token, and you point at a secret by name with secretRef.
Apply manages apps that run a prebuilt image. For git builds, use a git source instead of these files.
1. The dry run
levelrail-cli apply -f infra/ --source infra-repo --dry-run --exit-code
This is the real output from my run:
Plan: 4 to create, 0 to update, 0 to delete, 0 unchanged
+ Project/w2f-shop (infra/shop.yaml:1)
+ Environment/w2f-shop/production (infra/shop.yaml:5)
+ Database/w2f-main-db (infra/shop.yaml:11)
+ engine: postgres
+ project: w2f-shop
+ version: 16
+ App/w2f-web (infra/shop.yaml:19)
+ bindAddress: private
+ connections.DATABASE_URL: w2f-main-db.url
+ domains[w2f-web.localhost]: w2f-web.localhost
+ env.LOG_LEVEL: (hidden)
+ image: traefik/whoami:v1.10.3
+ port: 80
...
The exit code was 2, which the docs define as "changes are pending". Zero means nothing to do, and 1 means an error such as invalid files or an unreachable server. That is the whole contract a CI job needs.
The CLI validates everything before it plans anything. If one document has an issue, it plans and applies nothing. Errors carry a file and line. The plan lists the database because the app references it, and databases always go in before apps.
2. Apply
levelrail-cli apply -f infra/ --source infra-repo --yes
applied Project/w2f-shop
applied Environment/w2f-shop/production
applied Database/w2f-main-db
applied App/w2f-web
4 applied, 0 failed, 0 skipped
I then curled the app through the local ingress with its Host header and got the whoami container's reply. A second diff printed 0 to create, 0 to update, 0 to delete, 4 unchanged and exited 0. The --source flag matters later: it tags what the files created (managed-by:infra-repo) so that pruning can find only those apps.
3. A change, and the diff before it lands
I edited the file: a second domain, a memory and CPU limit, and a different LOG_LEVEL. Then I asked what that would do:
levelrail-cli diff -f infra/ --source infra-repo
Plan: 0 to create, 0 to update, 0 to delete, 3 unchanged
~ App/w2f-web (infra/shop.yaml:19)
+ domains[shop.localhost]: shop.localhost
~ env.LOG_LEVEL: (hidden) -> (hidden)
+ resources.cpu: 0.25
+ resources.memory: 128Mi
Exit 2 again. Env values print as (hidden) on purpose, so you see that a variable changed but never its value. In a pull request review that is a fair tradeoff, and you read the file for the actual value.
This is the moment I wanted at midnight. One app, four fields, nothing else touched. I applied it, and the next diff was clean.
4. Drift
Then I did the thing I used to do by accident. I scaled the app by hand:
levelrail-cli apps scale w2f-web --replicas 2
levelrail-cli diff -f infra/ --source infra-repo
~ App/w2f-web (infra/shop.yaml:19)
~ replicas: 2 -> 1
The plan says live is 2 and the files say 1, exit code 2. The docs suggest running diff on a schedule to catch hand edits. That gives you a cron job that fails when someone has clicked something.
One thing to keep in mind from the docs. Lists and maps on an app (domains, tags, env, labels) are additive, so the plan keeps entries the files do not mention and shows them as keep. Everything else on a declared resource is authoritative.
5. From CI
The docs describe a Git workflow with no sync engine to run. The files live in a repository, the pull request shows the plan, and the merge applies it. I did not run this in GitHub Actions, so treat it as the documented shape and not something I tested. The plan job only needs a read token:
- name: Plan
env:
APP_API_URL: ${{ secrets.LEVELRAIL_API_URL }}
APP_API_TOKEN: ${{ secrets.LEVELRAIL_READ_TOKEN }}
run: levelrail-cli apply -f infra/ --source infra-repo --dry-run --exit-code || [ $? -eq 2 ]
The apply job on push to main uses a separate write token and --yes. The || [ $? -eq 2 ] is there because exit code 2 means "changes pending", which on a pull request is normal, not a failure.
The plan also carries a hash. The CLI, dashboard and MCP pass it back so an apply only proceeds if live state still matches the plan you reviewed. That makes "reviewed plan, then apply" mean something.
How it compares to the other ways I managed this
| Approach | Record of changes | Preview before change | Catches hand edits |
|---|---|---|---|
| Dashboard clicks | Whatever the audit trail shows | No | No |
| Shell script of CLI calls | The script, if you keep it | Only if you write one | No |
apply on YAML files |
Git history | Yes, a field level plan | Yes, with diff
|
The honest limits, taken from the docs: backup schedules, egress policies, node placement, registry credentials and vault env references have no YAML form yet. A live app that uses them keeps them when you apply, and the plan warns. Databases get extra care: apply refuses to change engine or version, because databases hold data.
FAQ
Do I need Kubernetes or a separate GitOps controller for this?
No. It goes through the ordinary REST API with your own token, and the CLI computes and runs the plan. No operator runs in a cluster.
Can I start from an existing server instead of writing YAML?
The docs describe levelrail-cli export --project shop -o infra/, which writes projects and apps as documents and is stable enough that export, apply, export gives identical files. I did not run export on my throwaway instance, so I am relaying the docs here, not my own test.
Will --prune delete things I made by hand?
Per the docs, prune requires --source NAME and only deletes apps carrying that source's tag. Projects, environments, databases, pipelines and alert rules are never pruned.
Is there an API beyond the CLI?
Yes. The docs describe a server-side apply route for apps and databases (PATCH /api/v2/apps/{name} with a field manager and a dry run option) so more than one tool can own different fields. I only read that page.
The bottom line
The feature is small: write YAML, get a plan, get an exit code. What it changed for me is that every change to the server has a diff in front of it, and drift has a command that fails. The next thing I want to measure is how long a pull request plan takes against a server with 30 apps.
If this saved you time, a star on the repo helps others find it.
glincker
/
levelrail
Self-hosted alternative to Vercel and Coolify. Git push, HTTPS, logs, rollback. No Kubernetes.
Levelrail
Your own Vercel, on your own servers.
Push to deploy with HTTPS, logs, metrics and one-step rollback. One Go binary, no Kubernetes. Apache 2.0.
Website · Docs · Install · Compare · FAQ · Roadmap · Discussions
English · 简体中文 · Español · Português (BR) · Deutsch · Français · 日本語
Turn any Linux server into a private cloud: Git deploys, HTTPS, databases with verified backups, metrics, logs and alerts, without Kubernetes and without a monitoring stack to bolt on. Pre-1.0: single-server is production ready, multi-node is beta (Feature status).
idle RAM, 1.5% of one CPU Go control plane, Docker runtime one-click service templates MCP tools for coding agents
200 MB
measured, method included
1 binary
no Kubernetes
360
smoke-tested
240+
scoped, read-only by default
Install
curl -fsSL https://levelrail.com/install.sh | sudo sh
Needs Linux (amd64 or arm64) with systemd and root; the installer adds Docker. Open ports…
Sources checked
Levelrail docs and code, read at the v1.0.1 release branch: docs/platform-as-code.md, docs/server-side-apply.md, docs/local-development.md, docs/cli-reference.md. All command output above is from a local instance I started with levelrail-cli dev, built from that branch.


Top comments (1)
The drift diff is the part I'd live in, catching stuff you clicked in by hand months ago and forgot about. Question on the YAML files though, where do env vars and secrets go? Inline in a git-tracked file feels wrong for anything sensitive, so I'm guessing references, curious how that looks in practice