Urbex - a self-hosted app platform: everything your apps need, on infrastructure you own.
With the CLI:
Or asking Claude Code, with Urbex's plugin:
Write the app; Urbex gives it everything else - repositories, builds, deploys, login, networking, logs, backups. On your server, not someone else's cloud.
Every environment, from a homelab to the cloud, should give applications the same fundamental services, the same way. Urbex is that platform.
Status: preview release (v0.1.0). The whole flow - from an empty Proxmox node to an app in staging and production - runs end to end and has been validated on a real server. Download
urbex, orurbex-opand its image, from the release - see Get Urbex. A preview: no backups yet, Proxmox only, one operator - see the known limitations. The CLI is open source (Apache-2.0):urbforge/urbex-cli. We are looking for testers: see Try it early, tell us what's missing.
You have a Proxmox node - a homelab, a server at home or in a rack - and you want your apps on it the way a company would run them: staging and production, builds on every push, releases you promote, login, logs and metrics, secrets that are never in plain text, admin tools that aren't open to the internet. Without wiring all of it by hand, and with an AI agent able to drive it: "deploy to staging", "promote to production".
You don't need a Cloudflare account: cloudflare.quickTunnel: true gives
every public service a *.trycloudflare.com address
(ADR-0025); it is for
trying Urbex, not for production. domain in urbex.platform.yaml is
still required (the Forgejo admin's e-mail, the default of dns.zone). A
domain on Cloudflare gives you stable public names and Access in front of
the admin tools.
Not yet for you if you don't want to own a server: if "deploy" should just work, on a cloud you don't manage, wait for cloud VM support - it's on the roadmap, and it's what opens Urbex to anyone who builds apps, vibe coders included.
urbex bootstrap # once: the platform's services on your Proxmox node
urbex init # in your app's repo: describe it in urbex.yaml
urbex apply staging # its staging environment; every push to main lands there
urbex apply prod # once: its production environment
urbex release # tag what staging runs
urbex promote # production runs the very images staging ranEach of these is a single command an agent like Claude Code or Codex can
run for you. With Claude Code, the urbex plugin in this repository
sets Urbex up and runs it for you - see
Getting started with Claude Code.
Getting started shows every command and what
it prints. And this is what you see in Grafana - the logs of every
service, the platform's and your apps':
Every serious application needs the same things: a repository, a CI
pipeline that builds its images, a CD pipeline that takes them to
staging and production, an identity provider, an address people can
reach, logs and monitoring, storage and backups, disaster recovery, high
availability. Today whoever writes the app wires each of them by hand,
and differently in every environment. Urbex is one standard ecosystem
you install once - on your homelab or your cloud - and from then on each
application declares what it needs in urbex.yaml, and gets it.
Think of it as an operating system for applications: what an OS gives a program, Urbex gives an application.
| An OS gives a program | Urbex gives an application | Today |
|---|---|---|
exec |
build and deploy: CI builds the image, CD takes it to staging and production | available |
| processes | an isolated environment per service (LXC), staging and production | available |
| users and permissions | an identity provider (Keycloak): login, roles, a client per frontend | available |
| network and DNS | internal DNS, a public tunnel, protected access (Cloudflare) | available |
| filesystem | named volumes, node shares, a PostgreSQL your apps link to (provides/uses); backups are the roadmap |
available, backups roadmap |
| system logs and monitor | logs and resources in Grafana, every container in Komodo | available |
| package manager | the platform's standard services, the same in every environment | available |
| system restore | disaster recovery and high availability | roadmap |
In short: like Heroku or Vercel, but on your server and with everything included; like Coolify or Dokploy, with identity, observability - and, next, backups and disaster recovery - built in. And built to be driven by an AI agent as well as by a person: its interface is a CLI an agent like Claude Code or Codex can use (ADR-0001).
Urbex runs on a server you already have - a Proxmox node today - and
installs the platform's services there: Forgejo for the repositories,
Komodo for builds and deploys, Technitium for internal DNS, Keycloak for
identity, Prometheus, Loki and Grafana for monitoring, and Cloudflare for
public access. A project - web frontends deployed to Cloudflare Workers,
mobile apps registered with Keycloak, services in Java, Python, Go or any
Docker image - describes itself in urbex.yaml, and the urbex CLI
creates and keeps what it needs in every environment.
The urbex CLI implements it: bootstrap
sets up Forgejo and Komodo; projects are developed trunk-based, and every
push to main is built by Komodo and deployed to staging; releases are
tags, promoted to production; and each environment runs what its folder
in the GitOps repo says - version, configuration, SOPS-encrypted
secrets - deployed by Komodo on every change. With Cloudflare, public
APIs go out through a Cloudflare Tunnel, web frontends are deployed to
Cloudflare Workers, Keycloak is public, and Forgejo and Komodo sit behind
Cloudflare Access; every service also gets an internal DNS name in
Technitium, independently of Cloudflare. Without a Cloudflare account,
cloudflare.quickTunnel: true exposes every public service on a
*.trycloudflare.com hostname. Beyond services built from a repository:
- applications from published images, pinned to a digest and updated on demand;
- volumes (mount points of the LXC, in Proxmox's backups) and shares of the node;
- linked applications - a PostgreSQL that
providesa database and applications thatuseit - started in order, and brought back by a reconciler after a failure or a reboot; urbex status --progress, which followsbootstrapandapplyphase by phase, andurbex usersfor the test users of staging;urbex-op, the CLI and its tools in a container, on Linux and on macOS with docker or colima.
Validated on a real Proxmox VE 9.2 node and Cloudflare account - see
docs/known-limitations.md for what's
still missing.
See docs/status.md for the full
supported/not-supported breakdown and implementation priorities, and
docs/ more generally for architecture, decisions, and roadmap.
- Infrastructure target: an already-running Proxmox server.
- Every project service runs in a dedicated LXC (Debian 13), as a container Komodo builds from the project's Git repo and rolls out.
- Platform services (created on-demand if missing):
- Forgejo — self-hosted Git server (app repos + GitOps repo).
- Komodo — build/update pipeline and LXC management.
- Technitium DNS — internal name resolution between services.
- Keycloak — identity provider (SSO for admin tools and OIDC for apps).
- Prometheus + Grafana + Loki — metrics, logs, and observability.
- All infrastructure is declared and versioned in a GitOps repo, which also says, per environment, what each project runs: version, configuration, secrets.
- Main interface: a CLI (
urbex), designed to be driven by an LLM in a terminal, but also usable by a human. - The public domain is configurable, not hardcoded: Urbex must be usable by anyone with their own Proxmox and their own domain.
- Optional transactional email via a managed provider (Brevo in v1, more planned) — no self-hosted mail server.
- Cloud providers beyond Proxmox: Azure, GCP, AWS.
- Git servers beyond Forgejo: GitHub, GitLab.
- Secrets management: optional HashiCorp Vault support alongside SOPS+age.
This repository is also a Claude Code plugin. In Claude Code, run these two commands one at a time:
/plugin marketplace add urbforge/urbex
/plugin install urbex@urbex
Then ask in plain words, or call its skills directly:
| Skill | What it does |
|---|---|
/urbex:setup |
From an empty Proxmox node to your app in staging: the prerequisites, the Proxmox and Cloudflare tokens (you create and enter them yourself, never in the chat), the workspace, urbex.platform.yaml, urbex bootstrap. |
/urbex:manifest |
Writes urbex.yaml from your app's code, changes it (a database, a volume, a public service, more memory) and validates it. |
/urbex:cli |
Every urbex command, through urbex-op or natively: "deploy to staging", "release and promote", "set a secret", "roll back prod". It asks before touching production or deleting anything. |
The skills follow this repository's documentation, which ships with the
plugin; urbex itself is built from
urbforge/urbex-cli. The whole
walkthrough:
Getting started with Claude Code.
Urbex is free and open source, for everyone - it isn't a product we sell. What we need most now are the people it's for: if you run a homelab, try it on yours.
What to try, on a Proxmox VE 9 node with about 6 GiB of free memory and 30 GiB of free disk (see the prerequisites; a quick tunnel needs no Cloudflare account; the platform's resources will be trimmed once its base services are settled):
- Set up the platform: Getting started, with the CLI or with an AI agent such as Claude Code.
- Deploy an app of yours to staging, then promote it to production.
- Break something: a secret, a rollback, a reboot of the node.
How to tell us: open an
issue - what you deployed,
where it stopped, what you expected, the output of the command that
failed, and urbex version (or urbex-op 'urbex version'). A problem with the CLI itself can also go to
urbex-cli's issues. If
you help people take their apps to production and see what's missing,
tell us too: it shapes the roadmap.
urbforge/urbex(this repo) — architecture, ADRs, manifest spec/schema, roadmap.urbforge/urbex-cli— theurbexCLI implementation (Go), andurbex-op, the CLI in a container. See ADR-0016.
Start here:
- Getting started — how Urbex works and the prerequisites, then one guide per way of setting up: the CLI, any AI agent or Claude Code.
- Upgrading — moving to a new release; what
changed in each:
CHANGELOG.md(docs and plugin) and urbex-cli'sCHANGELOG.md. - Cookbook — recipes: releasing, rolling back, pinning staging, secrets, adding services, troubleshooting, driving Urbex from an LLM agent (the Claude Code plugin included).
Reference (index):
- CLI — every command and flag.
- Manifest —
urbex.yaml, field by field; formal schema inschemas/urbex.schema.json. - Platform config —
urbex.platform.yaml. - GitOps repo — layout, version, configuration and secrets files, how a commit is deployed.
- Credentials — every credential and how to get it.
- Platform resources — what Urbex creates on Proxmox, Forgejo, and Komodo.
Design and planning:
docs/architecture.md— components and flows.docs/decisions/— Architecture Decision Records.docs/status.md— what's supported today vs. not yet, and priorities.docs/known-limitations.md— every known limitation, with what to do meanwhile.docs/roadmap.md— v1 vs v2+ scope.
Urbex is licensed under the Apache License 2.0, and so is urbex-cli.


