Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .claude-plugin/plugin.json
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
{
"name": "urbex",
"version": "0.1.4",
"version": "0.2.0",
"description": "Set up Urbex on a Proxmox node, write and change urbex.yaml, and run every urbex command: bootstrap, apply, release, deploy, promote, secrets, status.",
"author": {
"name": "urbforge",
Expand Down
20 changes: 12 additions & 8 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -16,13 +16,16 @@ Write the app; Urbex gives it everything else - repositories, builds, deploys, l

Every environment, from a homelab to the cloud, should give applications the same fundamental services, the same way. Urbex is that platform.

> **Status: working prototype, not released yet.** The whole flow - from an
> **Status: preview release ([v0.1.0](https://github.com/urbforge/urbex-cli/releases/tag/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. The CLI is open source
> ([Apache-2.0](LICENSE)) and public:
> [`urbforge/urbex-cli`](https://github.com/urbforge/urbex-cli). You build
> it from its repository - see [Get Urbex](docs/getting-started/with-the-cli.md#1-get-urbex).
> We are looking for testers: see
> and has been validated on a real server. Download `urbex`, or `urbex-op`
> and its image, from the release - see
> [Get Urbex](docs/getting-started/with-the-cli.md#1-get-urbex). A preview:
> no backups yet, Proxmox only, one operator - see the
> [known limitations](docs/known-limitations.md). The CLI is open source
> ([Apache-2.0](LICENSE)):
> [`urbforge/urbex-cli`](https://github.com/urbforge/urbex-cli). We are
> looking for testers: see
> [Try it early, tell us what's missing](#try-it-early-tell-us-whats-missing).

## Who it's for - today
Expand Down Expand Up @@ -221,8 +224,8 @@ trimmed once its base services are settled):

**How to tell us**: open an
[issue](https://github.com/urbforge/urbex/issues) - what you deployed,
where it stopped, what you expected, and the output of the command that
failed. A problem with the CLI itself can also go to
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](https://github.com/urbforge/urbex-cli/issues). If
you help people take their apps to production and see what's missing,
tell us too: it shapes the roadmap.
Expand All @@ -244,6 +247,7 @@ Start here:
[CLI](docs/getting-started/with-the-cli.md), [any AI
agent](docs/getting-started/with-an-ai-agent.md) or [Claude
Code](docs/getting-started/with-claude-code.md).
- [**Upgrading**](docs/upgrading.md) — moving to a new release.
- [**Cookbook**](docs/cookbook.md) — recipes: releasing, rolling back,
pinning staging, secrets, adding services, troubleshooting, driving
Urbex from an LLM agent (the Claude Code plugin included).
Expand Down
23 changes: 14 additions & 9 deletions docs/cookbook.md
Original file line number Diff line number Diff line change
Expand Up @@ -1047,20 +1047,25 @@ its resource metrics are still collected.
## Run urbex from a container

Rather than installing `terraform`, `ansible-playbook`, `sops` and the
rest, run `urbex` with `tools/operator/urbex-op` from `urbforge/urbex-cli`
(podman or docker). It works on a **workspace**: one folder with the
rest, run `urbex` with `urbex-op` (podman or docker): one script, from
each [release](https://github.com/urbforge/urbex-cli/releases), that runs
the release's image `ghcr.io/urbforge/urbex-op:<version>` and pulls it
the first time. It works on a **workspace**: one folder with the
credentials, the SSH and age keys, the GitOps repo and your projects.

```sh
cd urbex-cli
tools/operator/urbex-op build # the image, with urbex built from the checkout
tools/operator/urbex-op -w ~/urbex-work init # SSH key, age key, folders
tools/operator/urbex-op -w ~/urbex-work set proxmoxToken # stored in the workspace (or export URBEX_PROXMOX_TOKEN)
tools/operator/urbex-op -w ~/urbex-work 'urbex bootstrap'
tools/operator/urbex-op -w ~/urbex-work 'cd /work/projects/acme-app && urbex apply staging'
tools/operator/urbex-op -w ~/urbex-work shell # an interactive shell
curl -fsSLo ~/bin/urbex-op https://github.com/urbforge/urbex-cli/releases/download/v0.1.0/urbex-op
chmod +x ~/bin/urbex-op
urbex-op -w ~/urbex-work init # SSH key, age key, folders
urbex-op -w ~/urbex-work set proxmoxToken # stored in the workspace (or export URBEX_PROXMOX_TOKEN)
urbex-op -w ~/urbex-work 'urbex bootstrap'
urbex-op -w ~/urbex-work 'cd /work/projects/acme-app && urbex apply staging'
urbex-op -w ~/urbex-work shell # an interactive shell
```

From a checkout of `urbforge/urbex-cli`, `tools/operator/urbex-op build`
builds the image from the checkout instead, and that script runs it.

The workspace is `/work` in the container (`$HOME` is `/work/home`, the
GitOps repo `/work/gitops`). Details in `tools/operator/README.md`.

Expand Down
10 changes: 6 additions & 4 deletions docs/getting-started.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,8 +6,10 @@ prerequisites. Then pick a guide: Claude Code with the Urbex plugin,
any other AI agent, or the commands typed by you. Allow an hour the
first time, most of it spent waiting for downloads.

> ⚠️ Urbex is early-stage. Everything here has been run end to end on a
> real Proxmox VE 9.2 node - see [`status.md`](status.md) and
> ⚠️ Urbex is a preview release
> ([v0.1.0](https://github.com/urbforge/urbex-cli/releases/tag/v0.1.0)).
> Everything here has been run end to end on a real Proxmox VE 9.2 node -
> see [`status.md`](status.md) and
> [`known-limitations.md`](known-limitations.md).
>
> The CLI is open source (Apache-2.0), in
Expand Down Expand Up @@ -119,8 +121,8 @@ Linux or macOS, `git`, and one of the following:

| | Install | Notes |
|---|---|---|
| **Container** (recommended) | `podman` or `docker` | Nothing else: the image has `urbex`, Terraform, Ansible, sops and age at the versions the CLI is tested with. Go isn't needed. |
| **Native** | [mise](https://mise.jdx.dev), then `mise install` in the `urbex-cli` checkout | Installs the pinned versions of Go (only to build `urbex`), Terraform, Ansible, sops and age, listed in `urbex-cli`'s `mise.toml`. Without mise, install them yourself: Go 1.26, Terraform 1.13 (or OpenTofu), `ansible-core`, `sops`, `age`, plus `ssh`. |
| **Container** (recommended) | `podman` or `docker` | Nothing else: `urbex-op`, from the release, runs the release's image, which has `urbex`, Terraform, Ansible, sops and age at the versions the CLI is tested with. |
| **Native** | `urbex` from the release, plus Terraform, Ansible, sops and age | The versions `urbex-cli`'s `mise.toml` pins: with [mise](https://mise.jdx.dev), `mise use -g` each of them; without, install them yourself: Terraform 1.13 (or OpenTofu), `ansible-core`, `sops`, `age`, plus `ssh`. |

Every guide below uses the container. With the native tools, run the
same `urbex ...` commands directly, after the extra setup in
Expand Down
6 changes: 3 additions & 3 deletions docs/getting-started/with-an-ai-agent.md
Original file line number Diff line number Diff line change
Expand Up @@ -18,10 +18,10 @@ your app:
```text
Set up Urbex for me and deploy my app with it.

1. Clone https://github.com/urbforge/urbex and https://github.com/urbforge/urbex-cli
side by side, then read urbex/docs/getting-started.md and
1. Clone https://github.com/urbforge/urbex, read
urbex/docs/getting-started.md and
urbex/docs/getting-started/with-the-cli.md, and follow the latter
with the container (urbex-op).
with the container: urbex-op, downloaded from the urbex-cli release.
2. Find every value yourself, don't ask me for what you can discover:
from this machine the LAN's CIDR, gateway and DNS, the Proxmox node
(port 8006 on the LAN) and a free block of addresses; once my tokens
Expand Down
10 changes: 7 additions & 3 deletions docs/getting-started/with-claude-code.md
Original file line number Diff line number Diff line change
Expand Up @@ -23,8 +23,11 @@ From the `/plugin` menu instead, choose *Add Marketplace* and enter only
`urbforge/urbex`; then install `urbex` from the marketplace's list.

It also needs `python3`, 3.8 or later, on your machine, for the scripts
that find your settings. `urbex` itself is built from
[`urbforge/urbex-cli`](https://github.com/urbforge/urbex-cli).
that find your settings. `urbex` itself comes from the releases of
[`urbforge/urbex-cli`](https://github.com/urbforge/urbex-cli/releases):
the plugin downloads it. The plugin has its own version; it works with
any `urbex` of the same major version and says when yours is older than
it needs - see [Plugin and CLI versions](../upgrading.md#plugin-and-cli-versions).

## 2. Set up Urbex

Expand All @@ -42,7 +45,8 @@ Or ask in plain words: "set up Urbex on my Proxmox node". What happens:
pings each address of the LAN once.
2. **It asks one question**: whether you use Cloudflare. The choices are
none, a Quick Tunnel, or your own zone.
3. **It builds `urbex-op`** and creates the workspace in `~/urbex-work`.
3. **It downloads `urbex-op`** from the newest release of urbex-cli, and
creates the workspace in `~/urbex-work` (which pulls the image).
4. **You prepare Proxmox**, choosing between two ways: a script, which
it recommends, or the commands by hand. The script runs in your own
terminal, not in the chat. It asks for the password of `root@pam` without showing it,
Expand Down
36 changes: 25 additions & 11 deletions docs/getting-started/with-the-cli.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,13 +7,17 @@ docker.

## 1. Get Urbex

Download `urbex-op` from the [release](https://github.com/urbforge/urbex-cli/releases/tag/v0.1.0):
one script, which runs that release's image,
`ghcr.io/urbforge/urbex-op:0.1.0`, and pulls it the first time.

```sh
git clone https://github.com/urbforge/urbex-cli.git ~/src/urbex-cli
cd ~/src/urbex-cli
tools/operator/urbex-op build # builds the image, with urbex compiled from this checkout
ln -s "$PWD/tools/operator/urbex-op" ~/bin/urbex-op
mkdir -p ~/bin
curl -fsSLo ~/bin/urbex-op https://github.com/urbforge/urbex-cli/releases/download/v0.1.0/urbex-op
chmod +x ~/bin/urbex-op # ~/bin must be on your PATH
export URBEX_WORKSPACE=~/urbex-work # put this in your shell's profile
urbex-op init
urbex-op init # pulls the image the first time
urbex-op 'urbex version' # urbex 0.1.0 (commit ..., built ..., linux/amd64)
```

`init` creates the **workspace**: one folder with the SSH key Urbex
Expand Down Expand Up @@ -136,12 +140,17 @@ That's it. For configuration and secrets see

## Native tools

Without the container, build `urbex` and set up what the container does
for you:
Without the container, download `urbex` from the
[release](https://github.com/urbforge/urbex-cli/releases/tag/v0.1.0) - the
archive for your system (Linux or macOS, amd64 or arm64), checked against
`checksums.txt` - and set up what the container does for you:

```sh
cd ~/src/urbex-cli
mise install && mise run build && mv urbex ~/bin/ # or: go build -o ~/bin/urbex ./cmd/urbex
v=0.1.0 os=linux arch=amd64 # or darwin, arm64
curl -fsSLO https://github.com/urbforge/urbex-cli/releases/download/v$v/urbex_${v}_${os}_${arch}.tar.gz
curl -fsSL https://github.com/urbforge/urbex-cli/releases/download/v$v/checksums.txt | grep "_${os}_${arch}.tar.gz" | sha256sum -c # macOS: shasum -a 256 -c
tar xzf urbex_${v}_${os}_${arch}.tar.gz urbex && mv urbex ~/bin/
urbex version
ssh-keygen -t ed25519 -f ~/.ssh/urbex -C urbex && ssh-add ~/.ssh/urbex
age-keygen -o ~/urbex.key # back it up
export URBEX_PROXMOX_TOKEN='urbex@pve!cli=<value>'
Expand All @@ -152,8 +161,13 @@ urbex bootstrap

Then run the commands of steps 3 to 6 without `urbex-op '...'`, from
your app's folder, wherever it is. Terraform, Ansible and sops must be
on the `PATH` there: with mise, that is `mise use -g` for each tool, or a
`mise.toml` in that folder.
on the `PATH` there, at the versions urbex-cli's
[`mise.toml`](https://github.com/urbforge/urbex-cli/blob/v0.1.0/mise.toml)
pins: with mise, that is `mise use -g` for each tool, or a `mise.toml` in
that folder. `urbex doctor` checks them.

To build `urbex` from source instead (to work on it), see *Build & test*
in [urbex-cli's README](https://github.com/urbforge/urbex-cli#build--test).

## Configuration and secrets

Expand Down
7 changes: 7 additions & 0 deletions docs/known-limitations.md
Original file line number Diff line number Diff line change
Expand Up @@ -16,6 +16,13 @@ validation on a real Proxmox VE 9.2 node and Cloudflare account, and of
Cloudflare Quick Tunnel
([ADR-0025](decisions/0025-cloudflare-quick-tunnel.md)) on the same node.

**v0.1.0 is a preview release.** In short: no backups of the platform
yet ([below](#operations-and-security), planned in M3); Proxmox only
(VPS support is planned in M3, E3-bis); a single operator, from one
workspace; and while Urbex is 0.x, a
minor release may change how something works (see
[Upgrading](upgrading.md)).

- [Platform](#platform)
- [Projects and deploys](#projects-and-deploys)
- [Public endpoints (Cloudflare)](#public-endpoints-cloudflare)
Expand Down
45 changes: 41 additions & 4 deletions docs/reference/cli.md
Original file line number Diff line number Diff line change
Expand Up @@ -19,6 +19,7 @@ the [cookbook](../cookbook.md).
- [`urbex destroy`](#urbex-destroy)
- [`urbex teardown`](#urbex-teardown)
- [`urbex users`](#urbex-users)
- [`urbex version`](#urbex-version)
- [Environment variables](#environment-variables)
- [Exit status and output](#exit-status-and-output)

Expand Down Expand Up @@ -85,10 +86,13 @@ fails for no clear reason.
- **cloudflare**, with an account in the config: the token is active and
sees the zone of `domain`.

Each check is `ok`, `warn`, `fail` or `skip`; a check that isn't `ok`
has its fix under it. On the lab:
It starts with urbex's own version, as [`urbex version`](#urbex-version)
prints it. Each check is `ok`, `warn`, `fail` or `skip`; a check that
isn't `ok` has its fix under it. On the lab:

```
urbex 0.1.0 (commit 1a2b3c4, built 2026-11-20T10:00:00Z, linux/amd64)

tools:
ok git git version 2.47.3
ok terraform Terraform v1.13.3
Expand Down Expand Up @@ -126,8 +130,8 @@ proxmox:
```

It exits non-zero when a check failed. `--output json` prints the report
as one JSON document, `{"checks": [{"group", "name", "status", "detail",
"fix"}], "ok": true}`, for the setup UI and the plugin
as one JSON document, `{"version", "checks": [{"group", "name", "status",
"detail", "fix"}], "ok": true}`, for the setup UI and the plugin
([ADR-0032](../decisions/0032-web-ui-console-ai-assistant.md)).

## `urbex discover`
Expand Down Expand Up @@ -945,6 +949,39 @@ command is for:
}
```

## `urbex version`

```
urbex version [--output text|json]
urbex --version
```

Prints which build this is: say it in a bug report. A release says its
version; a build from source says `dev`, the commit and its date, and
`-dirty` if the tree had uncommitted changes:

```
$ urbex version
urbex 0.1.0 (commit 1a2b3c4, built 2026-11-20T10:00:00Z, linux/amd64)
$ urbex version # built from a checkout
urbex dev (commit 9df118e-dirty, committed 2026-11-16T17:38:34Z, linux/amd64)
```

`urbex --version` prints the same line. `--output json`:

```json
{
"version": "0.1.0",
"commit": "1a2b3c4d5e6f...",
"date": "2026-11-20T10:00:00Z",
"go": "go1.26.5",
"platform": "linux/amd64"
}
```

`date` is the build's, set by a release; a build from source has
`commit_date` instead, and `modified` when the tree had changes.

## Progress events

`urbex bootstrap`, `apply`, `destroy` and `teardown --yes` record their
Expand Down
1 change: 1 addition & 0 deletions docs/status.md
Original file line number Diff line number Diff line change
Expand Up @@ -22,6 +22,7 @@ Proxmox VE 9.2 node, see [What has been validated](#what-has-been-validated).

| Area | State |
|---|---|
| Distribution | Releases of `urbex-cli` ([v0.1.0](https://github.com/urbforge/urbex-cli/releases/tag/v0.1.0), a preview): `urbex` for Linux and macOS (amd64, arm64) with checksums and provenance, `urbex-op` and its image `ghcr.io/urbforge/urbex-op`; `urbex version`. Moving to a new release: [Upgrading](upgrading.md) |
| App manifest (`urbex.yaml`) | Formal JSON Schema, typed Go decoding, `urbex init` scaffolds and validates |
| Platform config (`urbex.platform.yaml`) | Scaffolded and validated by `urbex bootstrap` |
| Credentials | Env vars, falling back to `~/.urbex/credentials.yaml`; never written to the GitOps repo |
Expand Down
71 changes: 71 additions & 0 deletions docs/upgrading.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,71 @@
# Upgrading

Urbex is released from [`urbforge/urbex-cli`](https://github.com/urbforge/urbex-cli/releases):
the `urbex` binaries, `urbex-op`, and its image
`ghcr.io/urbforge/urbex-op:<version>`. Moving to a new release changes
the tools on your machine. The workspace, the GitOps repo, the platform
and your projects stay as they are.

While Urbex is 0.x (a preview), a minor release may still change how
something works. **Read the release's notes first**: they say when a
command is needed after upgrading.

## With urbex-op

Download the new release's `urbex-op` over the old one. Its next command
pulls the new image:

```sh
curl -fsSLo ~/bin/urbex-op https://github.com/urbforge/urbex-cli/releases/download/v0.2.0/urbex-op
urbex-op version # urbex-op 0.2.0, image ghcr.io/urbforge/urbex-op:0.2.0
urbex-op 'urbex version' # pulls the image the first time
urbex-op 'urbex doctor'
```

Put the version you are moving to in the URL (`v0.2.0` above is an
example). The old image stays on your machine until you remove it, e.g.
`podman rmi ghcr.io/urbforge/urbex-op:0.1.0`. To go back, download the
old release's `urbex-op`.

### From a checkout of urbex-cli

If you ran Urbex before the first release, `urbex-op` is a link to a
checkout of `urbex-cli`, and its image is the one `urbex-op build` made.
Download the release's `urbex-op` in its place, as above. Unset
`URBEX_OPERATOR_IMAGE` if you set it: a release's `urbex-op` runs its own
image. The workspace stays the same.

To keep working from the checkout instead (to work on urbex), pull it
and run `tools/operator/urbex-op build` again.

## Native

Download the new archive and replace `urbex`, as in
[Native tools](getting-started/with-the-cli.md#native-tools). Also check
that Terraform, Ansible, sops and age are at the versions the release's
`mise.toml` pins: `urbex doctor` lists them.

## The Claude Code plugin

The plugin has its own version. It works with any `urbex` of the same
major version (0 today). While both are 0.x it also needs a minimum,
which its `cli` skill states: urbex 0.1.0 for plugin 0.2.0.

### Plugin and CLI versions

| Plugin | urbex |
|---|---|
| 0.2.0 | 0.1.0 or later, major 0 |

The plugin checks `urbex version` once per session. When `urbex` is
older than it needs, it says so and points here. When the major versions
differ, update the plugin or use an `urbex` of the plugin's major.

To update the plugin, refresh its marketplace in Claude Code:

```text
/plugin marketplace update urbex
```

Then update `urbex` from the `/plugin` menu if it didn't update by
itself, and restart Claude Code.
Loading