Onboarding developers

Developers authenticate to your edge with a token that maps to a routing namespace. You mint tokens; the developer runs beamd login --server <edge> --token <token>.

Flat vs namespaced

A token maps to a slug in your tokens.json:

• Flat (empty slug "") — tunnels live directly at <name>.YOUR_DOMAIN. Best for personal use or a trusting team that coordinates names. Multiple flat tokens can coexist (e.g. several of your own machines).
• Namespaced (a slug like turing) — that developer's tunnels live under <name>.turing.YOUR_DOMAIN, so untrusted developers can't collide on names. Opt-in.

{
  "<long random token>": "",          // flat
  "<another random token>": "turing"   // namespaced under `turing`
}

beamd add-developer

The one command that does everything — mint a token, append it to tokens.json, write the DNS records, and pre-warm the wildcard cert:

# flat (default) — tunnels at <name>.YOUR_DOMAIN
beamd add-developer --config /etc/beamd/beamd.yaml
 
# namespaced — tunnels at <name>.hopper.YOUR_DOMAIN
beamd add-developer --slug hopper --config /etc/beamd/beamd.yaml

It prints the token once — send it over a private channel. Under Docker:

sudo docker compose exec beamd \
  beamd add-developer --slug hopper --config /etc/beamd/beamd.yaml

A non-empty slug is one developer → one token; add-developer refuses to issue a second for the same slug (delete the old entry to rotate). Pass --skip-provision to mint a token-only entry without touching DNS/certs.

beamd provision-dev (low-level)

If you'd rather manage tokens yourself, provision-dev does just the DNS + cert-prewarm half for a slug (what add-developer wraps):

beamd provision-dev --slug hopper --config /etc/beamd/beamd.yaml

Then add the token → slug entry to tokens.json by hand.

Reloading tokens

tokens.json is read at startup, so restart the edge after changing it:

sudo docker compose restart beamd      # Docker
sudo systemctl restart beamd           # systemd

A restart briefly drops connected clients, but they auto-reconnect and replay their tunnels — URLs stay stable.

Revoking a developer

Delete their entry from tokens.json and restart. Their active sessions drop immediately and they can't reconnect. (On the hosted service, API keys are revoked from the dashboard or the REST API instead.)