Skip to content
urbforgePublic

About

A self-hosted app platform: everything your apps need, on infrastructure you own.

Resources

Stars

3 stars

Watchers

0 watching

Forks

Repository files navigation

Urbex

Urbex - a self-hosted app platform: everything your apps need, on infrastructure you own.

With the CLI:

urbex apply staging, the app's URL, urbex release, urbex promote, urbex status

Or asking Claude Code, with Urbex's plugin:

Claude Code asked to deploy the app to staging, to release and promote it after asking first, and what runs where, as a table

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, or urbex-op and 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.

Who it's for - today

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.

What it looks like

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 ran

Each 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':

Logs of an app's services in Grafana

Why

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.

An operating system for your apps

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).

How it works

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.

What works today

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 provides a database and applications that use it - started in order, and brought back by a reconciler after a failure or a reboot;
  • urbex status --progress, which follows bootstrap and apply phase by phase, and urbex users for 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.

v1 — goal

  • 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.

Future evolutions (v2+)

  • Cloud providers beyond Proxmox: Azure, GCP, AWS.
  • Git servers beyond Forgejo: GitHub, GitLab.
  • Secrets management: optional HashiCorp Vault support alongside SOPS+age.

Use Urbex from Claude Code

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.

Try it early, tell us what's missing

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):

  1. Set up the platform: Getting started, with the CLI or with an AI agent such as Claude Code.
  2. Deploy an app of yours to staging, then promote it to production.
  3. 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.

Repositories

Documentation

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's CHANGELOG.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):

Design and planning:

License

Urbex is licensed under the Apache License 2.0, and so is urbex-cli.

About

A self-hosted app platform: everything your apps need, on infrastructure you own.

Resources

Stars

3 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages