Every value urbex reads from an environment variable, from
~/.urbex/credentials.yaml, or from urbex.platform.yaml - what it's
for, whether any command actually checks it yet, and exactly how to get
it. See ADR-0012
for the design (non-sensitive config in urbex.platform.yaml, secrets
never in the GitOps repo).
These are enforced - urbex bootstrap/plan/apply/destroy refuse
to run without them (credentials.MissingForProvisioning() in
urbex-cli). urbex release, deploy, promote, and secret don't
need the Proxmox token, since they only talk to Forgejo and Komodo - but
they do need the
generated platform credentials.
- Env var / credentials file key:
URBEX_PROXMOX_TOKEN/proxmoxToken - Used by: Terraform's Proxmox provider (every command that
provisions/destroys LXCs) and
urbex status's Proxmox query. - Format:
user@realm!tokenid=secret, e.g.root@pam!urbex=1234abcd-5678-.... - How to get one - commands: as
rooton the Proxmox host. This creates the least-privilege setup Urbex was validated with: a resource pool for everything Urbex creates, a group holding the permissions (scoped to the pool), and a user in the group whose token inherits them.# Where Urbex works: a resource pool, with the storages for root disks # (local-zfs here) and templates (local) in it. pveum pool add urbex --comment "Urbex" pveum pool modify urbex --storage local-zfs,local # The permissions, on a group: change them here, never per user. pveum group add urbex --comment "Urbex operators: pool urbex only" pveum acl modify /pool/urbex --groups urbex --roles PVEVMAdmin,PVEDatastoreUser,PVEPoolUser pveum acl modify /sdn/zones/localnetwork/vmbr0 --groups urbex --roles PVESDNUser # The user Urbex runs as, and its token (privilege separation off: it # inherits the group's permissions). pveum user add urbex@pve --comment "Urbex CLI" --groups urbex pveum user token add urbex@pve cli --privsep 0 --comment "urbex" # The Debian 13 template (needs root; the exact name: pveam available --section system). pveam update && pveam download local debian-13-standard_13.6-1_amd64.tar.zst
pveum user token addprints the token'sfull-tokenid(urbex@pve!cli) andvalueonce - Proxmox never shows it again:For a person who should operate the platform too, add their user to the group (export URBEX_PROXMOX_TOKEN='urbex@pve!cli=<value>'
pveum user modify <user>@pve --groups urbex --append 1) rather than granting anything to the user. Then inurbex.platform.yaml:proxmox.pool: urbexand the bridge inproxmox.network.bridge(the ACL above namesvmbr0). - What each permission is for:
PVEVMAdminmanages the pool's LXCs,PVEDatastoreUserallocates disks and reads templates on the pool's storages,PVEPoolUserlets the token see the pool.PVESDNUseron the bridge is needed to attach an LXC's network interface - without it, Proxmox refuses withPermission check failed (/sdn/zones/localnetwork/vmbr0, SDN.Use). Nothing else on the node is needed. Avoid aroot@pamtoken for anything beyond a quick personal test. - From the web UI instead: Datacenter → Permissions: Pools, Groups, Permissions → Add (group permission, with the paths and roles above), Users, then API Tokens → Add with Privilege Separation unchecked.
- Checking it:
curl -sk -H "Authorization: PVEAPIToken=$URBEX_PROXMOX_TOKEN" \ https://<proxmox>:8006/api2/json/access/permissions | jq '.data | keys' # ["/pool/urbex", "/sdn/zones/localnetwork/vmbr0", "/storage/local", "/storage/local-zfs"]
- Pool-scoped tokens: if the token's permissions are granted on a
resource pool, set
proxmox.poolinurbex.platform.yamlso every LXC is created in it - otherwise the token can't see or manage the containers it just created. - keyctl: Docker inside an unprivileged LXC needs the
nestingfeature and, on some hosts,keyctl. Proxmox only letsroot@pamchange features other thannesting, so Urbex leaveskeyctloff (proxmox.keyctl, defaultfalse) and works with any token. Docker runs without it on Proxmox 9.2. If Docker fails with overlayfspermission deniederrors, setproxmox.keyctl: truewith aroot@pamtoken, or have an administrator enable it once per container (pct set <vmid> --features nesting=1,keyctl=1). - Self-signed certificate: set
proxmox.insecure: trueif the node still uses Proxmox's default certificate.
- Where it's set:
proxmox.sshPublicKeyinurbex.platform.yaml(the public key itself, not a credential file entry - only the matching private key needs to stay off the GitOps repo). - Used by: the Terraform LXC module (installs it as the
rootuser's authorized key at container creation) and Ansible (connects over SSH to configure every LXC - duringbootstrapandapplyonly; deploying never needs SSH). - How to get one: generate a dedicated keypair rather than reusing a
personal one:
Put the public key's contents in
ssh-keygen -t ed25519 -f ~/.ssh/urbex -C urbexurbex.platform.yaml. Load the private key into an SSH agent on whichever machine runsurbexcommands (ssh-add ~/.ssh/urbex) - neither Terraform's provider nor Ansible can prompt for a passphrase.
- Env var / credentials file key:
URBEX_AGE_KEY/ageKey - Used by: every secret in the GitOps repo. They are encrypted with
SOPS for this key (ADR-0011):
urbex bootstrapwrites its public half to.sops.yaml,urbex secretencrypts and decrypts with it, andurbex applyhands it to the Periphery agent on each project LXC, which decrypts a service's secrets when Komodo deploys it (ADR-0020).bootstraprejects a value that isn't a valid age secret key. - How to get one: install age
(
brew install age, or your distro's package), then:The file'sage-keygen -o urbex.key
AGE-SECRET-KEY-1...line isURBEX_AGE_KEY. Keep the file itself somewhere durable outside the GitOps repo: Urbex has no way to recover a lost age key, and losing it means losing every secret encrypted to it. - Editing secrets without urbex: with the key exported as
SOPS_AGE_KEY,sops environments/<env>/<project>/<service>/secrets.sops.envopens the decrypted file in your editor.
Not a credential, but the one extra tool: urbex secret set|unset call
the sops binary on the machine you
run them on. The project LXCs get their own copy from urbex apply.
You never create these by hand: urbex bootstrap generates them and
writes them to ~/.urbex/credentials.yaml (mode 0600), keeping any that
already exist when re-run. An environment variable with the same name
still takes precedence. These reach the LXCs only through Ansible's
environment, never through a file in the GitOps repo. Copy the file
(like any secret) to every machine that runs urbex commands - though
deploying needs none of it: a commit to the GitOps repo is enough.
| Credentials file key | Env var | What it is |
|---|---|---|
forgeAdminPassword |
URBEX_FORGE_ADMIN_PASSWORD |
Password of urbex-admin, the forge's (Forgejo's) admin user |
forgeToken |
URBEX_FORGE_TOKEN |
Forgejo token (repos, org, packages) used by the CLI (repos, webhooks, release tags, pushing the GitOps repo) and by Komodo (cloning, pushing and pulling images) |
komodoAdminPassword |
URBEX_KOMODO_ADMIN_PASSWORD |
Password of urbex-admin, Komodo's initial admin |
komodoApiKey / komodoApiSecret |
URBEX_KOMODO_API_KEY / URBEX_KOMODO_API_SECRET |
Komodo API key the CLI declares builds and stacks with |
komodoOnboardingKey |
URBEX_KOMODO_ONBOARDING_KEY |
Key the Periphery agent on each project LXC registers itself in Komodo with |
komodoWebhookSecret |
URBEX_KOMODO_WEBHOOK_SECRET |
Secret Forgejo signs its webhooks to Komodo with |
komodoDbPassword, komodoJwtSecret |
URBEX_KOMODO_DB_PASSWORD, URBEX_KOMODO_JWT_SECRET |
Komodo's internal database password and signing secret |
keycloakAdminPassword |
URBEX_KEYCLOAK_ADMIN_PASSWORD |
Keycloak's bootstrap admin password |
keycloakDbPassword |
URBEX_KEYCLOAK_DB_PASSWORD |
Keycloak's PostgreSQL password, also in the Keycloak Stack's encrypted secrets |
grafanaAdminPassword |
URBEX_GRAFANA_ADMIN_PASSWORD |
Grafana's admin password |
technitiumAdminPassword |
URBEX_TECHNITIUM_ADMIN_PASSWORD |
Technitium's admin password - only takes effect while Technitium has no configuration yet (its own behavior); see the note below |
technitiumToken |
URBEX_TECHNITIUM_TOKEN |
Technitium API token, minted with the admin password, used to create the zone and the services' DNS records (ADR-0026) |
urbex apply, release, deploy, promote, and secret refuse to
run without the Forgejo token, the Komodo API key, the onboarding key, and
the webhook secret (credentials.MissingForPlatform()).
Before the forge was Forgejo (ADR-0034)
the two forge keys were giteaAdminPassword and giteaToken
(URBEX_GITEA_ADMIN_PASSWORD, URBEX_GITEA_TOKEN): urbex still reads
them, the new names win, and the next time urbex writes the file it
moves them to the new keys.
Bootstrap also stores the forge's token in Komodo, as the secret variable
URBEX_GITEA_TOKEN (named for Gitea still: the Actions of existing
platforms read it): the urbex-release Action uses it to look up
images and to commit staging's new version to the GitOps repo. Komodo
never shows a secret variable's value in its UI or logs. See
platform resources.
technitiumAdminPassword is a partial exception: bootstrap always
generates a value for it, but Technitium itself only accepts
DNS_SERVER_ADMIN_PASSWORD while it has no configuration yet. On a
platform bootstrapped before internal DNS registration existed (or
whose Technitium was set up some other way), the generated password
doesn't match what's actually configured, and minting the API token
fails. Set technitiumAdminPassword in ~/.urbex/credentials.yaml to
Technitium's real admin password yourself before running urbex bootstrap again.
-
Env var / credentials file key:
URBEX_CLOUDFLARE_TOKEN/cloudflareToken. The account and zone IDs are not secret: they go inurbex.platform.yaml(cloudflare.accountId,cloudflare.zoneId). -
Required when
urbex.platform.yamlconfigures Cloudflare, bybootstrap,teardown,apply,destroy(ADR-0022). Bootstrap also stores it in Komodo, as a secret variable, for the web frontends' deploys. -
Permissions:
Scope Permission (as the API names it) For Account Cloudflare Tunnel Write the platform's tunnel and its routes Account Workers Scripts Write the web frontends' Workers Account Access: Apps and Policies Write Access in front of Forgejo and Komodo Account Access: Organizations, Identity Providers, and Groups Write only to enable the one-time PIN login if Zero Trust has none yet Zone (yours) DNS Write the public hostnames Zone (yours) Workers Routes Write the web frontends' custom domains Zone (yours) Zone Read finding the zone This is the set the API calls Urbex makes need. The token Urbex was validated with had a few more (Cloudflare Pages, zone-level ones); if a call is refused, Urbex names the missing permission. The dashboard shows them as "... Edit"/"... Read". A Zero Trust organization must exist (first visit to Zero Trust; the Free plan is enough). The account and zone IDs are on the zone's Overview page.
-
How to get it - Terraform (
cloudflare/cloudflarev5). It looks the permissions up by name, so nothing is copied by hand; it authenticates with an existing token allowed to create tokens (e.g. from the dashboard template Create Additional Tokens), inCLOUDFLARE_API_TOKEN:terraform { required_providers { cloudflare = { source = "cloudflare/cloudflare", version = "~> 5.0" } } } provider "cloudflare" {} variable "account_id" { type = string } variable "zone_id" { type = string } data "cloudflare_account_api_token_permission_groups_list" "all" { account_id = var.account_id } locals { group = { for g in data.cloudflare_account_api_token_permission_groups_list.all.result : g.name => g.id } account_permissions = [ "Cloudflare Tunnel Write", "Workers Scripts Write", "Access: Apps and Policies Write", "Access: Organizations, Identity Providers, and Groups Write", ] zone_permissions = ["DNS Write", "Workers Routes Write", "Zone Read"] } resource "cloudflare_account_token" "urbex" { account_id = var.account_id name = "urbex" policies = [ { effect = "allow" permission_groups = [for n in local.account_permissions : { id = local.group[n] }] resources = jsonencode({ "com.cloudflare.api.account.${var.account_id}" = "*" }) }, { effect = "allow" permission_groups = [for n in local.zone_permissions : { id = local.group[n] }] resources = jsonencode({ "com.cloudflare.api.account.zone.${var.zone_id}" = "*" }) }, ] } output "token" { value = cloudflare_account_token.urbex.value sensitive = true }
terraform apply -var account_id=<account id> -var zone_id=<zone id> export URBEX_CLOUDFLARE_TOKEN="$(terraform output -raw token)"
A name that doesn't match fails the plan (
Invalid index) before anything is created; the names the account offers are listed bycurl -s -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \ "https://api.cloudflare.com/client/v4/accounts/<account id>/tokens/permission_groups" | jq -r '.result[].name' | sort
Keep the Terraform state private: it holds the token.
-
How to get it - API, with
curlandjq, the same token and permissions, with the same creating token inCLOUDFLARE_API_TOKEN:ACCOUNT=<account id> ZONE=<zone id> API=https://api.cloudflare.com/client/v4/accounts/$ACCOUNT/tokens PERMS=$(curl -s -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN" "$API/permission_groups") ids() { jq -c --argjson names "$1" '[.result[] | select(.name as $n | $names | index($n)) | {id}]' <<<"$PERMS"; } ACC=$(ids '["Cloudflare Tunnel Write","Workers Scripts Write","Access: Apps and Policies Write","Access: Organizations, Identity Providers, and Groups Write"]') ZON=$(ids '["DNS Write","Workers Routes Write","Zone Read"]') jq -n --argjson acc "$ACC" --argjson zon "$ZON" --arg a "$ACCOUNT" --arg z "$ZONE" '{ name: "urbex", policies: [ {effect: "allow", permission_groups: $acc, resources: {("com.cloudflare.api.account." + $a): "*"}}, {effect: "allow", permission_groups: $zon, resources: {("com.cloudflare.api.account.zone." + $z): "*"}} ]}' | curl -s -X POST -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN" -H "Content-Type: application/json" "$API" --data @- | jq -r '.result.value' # the token: shown once
Check that
ACClists 4 groups andZON3 before creating. -
How to get it - dashboard: Manage account → Account API tokens → Create token → Custom token, with the permissions above (account ones on your account, zone ones on your zone only).
-
Checking it:
curl -s -H "Authorization: Bearer $URBEX_CLOUDFLARE_TOKEN" \ https://api.cloudflare.com/client/v4/accounts/<account id>/tokens/verify | jq .result.status # "active"
With observability.alerts in urbex.platform.yaml
(platform config), the channels' secrets.
You provide them; urbex bootstrap keeps them encrypted in the
observability Stack, and urbex teardown leaves them in the file.
| Credentials file key | Env var | For | How to get it |
|---|---|---|---|
telegramBotToken |
URBEX_TELEGRAM_BOT_TOKEN |
observability.alerts.telegram |
@BotFather, /newbot |
discordWebhookUrl |
URBEX_DISCORD_WEBHOOK_URL |
observability.alerts.discord: true |
The channel's Integrations > Webhooks > Copy Webhook URL |
alertsWebhookUrl |
URBEX_ALERTS_WEBHOOK_URL |
observability.alerts.webhook: true |
Your service's URL |
Store one with urbex-op set <key>; get the alerts on Telegram or
Discord has the
steps. urbex doctor says which one is missing, and urbex doctor --test-alerts sends a test message with them.
These exist as fields in urbex.platform.yaml/~/.urbex/credentials.yaml
because the design anticipates needing them, but no current urbex
command reads or checks them. You can leave them unset today without
anything complaining. See status.md for which priority
item each is waiting on.
- Env var / credentials file key: none defined yet - there's no
URBEX_BREVO_*variable inurbex-clitoday, since nothing consumes it. - Will be used by: apps that declare
email.provider: brevoin theirurbex.yaml(ADR-0015)- not implemented yet.
- How to get one (when you need it): Brevo dashboard → SMTP & API → API Keys → Generate a new API key.
| Credential | Env var | Required today? |
|---|---|---|
| Proxmox API token | URBEX_PROXMOX_TOKEN |
✅ yes |
| SSH private key | (SSH agent, not an env var) | ✅ yes |
| age keypair | URBEX_AGE_KEY |
✅ yes (encrypts every secret) |
| Forgejo/Komodo/Keycloak/Grafana/Technitium passwords, tokens, keys | URBEX_FORGE_*, URBEX_KOMODO_*, URBEX_TECHNITIUM_*, ... |
✅ generated by urbex bootstrap |
| Cloudflare API token | URBEX_CLOUDFLARE_TOKEN |
✅ with Cloudflare configured |
| Telegram bot token, Discord or other webhook URL | URBEX_TELEGRAM_BOT_TOKEN, URBEX_DISCORD_WEBHOOK_URL, URBEX_ALERTS_WEBHOOK_URL |
✅ with the matching alert channel |
| Brevo API key | (none defined) | ❌ not yet |