Operations

Invites

One invite = one tenant. Revoking removes the tenant.

towonel invite create --name alice --hostnames '*.alice.example.eu'
towonel invite create --name bob   --hostnames 'app.bob.example.eu' --expires 48h
towonel invite list
towonel invite revoke --id <invite-id>

Default --expires is never.

Tenants

Tenants manage their own hostnames:

# from the agent side
towonel entry submit --op upsert-hostname --hostname new.alice.example.eu

Operator cleanup:

towonel tenant remove --tenant-id <hex>
# or, tenant-side
towonel tenant leave --key-path tenant.key --hub-url https://hub.example.eu:8443

Static tenants

Without the web console, tenants come from an operator-managed JSON allowlist in TOWONEL_TENANTS. name and hostnames are required; the rest pin identity and reachability and can be left empty. towonel tenant prints the entry to paste.

[
  {
    "name": "alice",
    "hostnames": ["*.alice.example.eu"],
    "pq_public_key": "<tenant ML-DSA-65 pubkey>",
    "agent_node_ids": [],
    "direct_addresses": []
  }
]

Operator auth

export TOWONEL_HUB_URL=https://hub.example.eu:8443
export TOWONEL_OPERATOR_KEY=$(docker exec towonel cat /data/operator.key)

If the operator key is supplied via env (TOWONEL_HUB_OPERATOR_API_KEY), read it from your secret manager instead.

Backup

What needs to survive a restore depends on the database driver.

SQLite (default):

• /data — hub.db, node.key, operator.key, ACME cert cache.

Postgres:

• The Postgres cluster — pg_dump or barman-cloud. No /data to back up if every key comes from env.

Either way, these keys must be preserved:

• TOWONEL_HUB_KEK — encrypts the secrets table. Losing it loses the ability to decrypt secrets.
• TOWONEL_INVITE_HASH_KEY — losing it invalidates every outstanding invite.
• TOWONEL_IDENTITY_KEY (or /data/node.key) — the hub’s iroh identity. Losing it forces every edge and agent to re-trust the new hub.

Each inline key has a file alternative — TOWONEL_IDENTITY_KEY_PATH, TOWONEL_HUB_KEK_PATH, TOWONEL_INVITE_HASH_KEY_PATH, TOWONEL_HUB_OPERATOR_API_KEY_PATH — defaulting under TOWONEL_DATA_DIR. Mount the key file and set the _PATH var instead of the inline value.

Privileged ports

TCP/UDP listen ports below 1024 are blocked. Allow on the hub:

-e TOWONEL_HUB_ALLOW_PRIVILEGED_PORTS=true

UDP port ranges

A tenant may claim a contiguous UDP port range in one binding (see TCP and UDP services). Cap the size on the hub:

-e TOWONEL_HUB_MAX_UDP_PORT_RANGE=512