Accounts & scopes

Beamd separates three things the word "profile" usually tangles together: where you're logged in, who you're acting as, and what a given repo uses. The model in one sentence:

Your machine is logged into Beamd as you (per edge); you can act as any of your orgs; a project pins which org and edge it uses; automation uses a workspace-scoped API key instead of your login.

It's gh × Vercel: per-edge login like gh's multi-host, plus per-org scope within a login like vercel --scope — degrading cleanly to a plain {server, token} for a self-hosted edge.

Accounts — one per edge

Each edge you log into is an account, keyed by its server host. Stay logged into several at once; no logout churn:

beamd login                      # hosted: browser login; edge assigned automatically
beamd login --server acme.com --token <T>   # self-host: pass the edge + token
beamd accounts                   # list them; * marks the current
beamd logout --server acme.com   # remove one

The first account becomes current. Override the edge per command with --server, or per shell with the BEAMD_SERVER environment variable.

Scopes — one login, many orgs

On a hosted edge you belong to one or more scopes: your personal namespace plus any teams. Scope is a selector, not a separate login — pick it per command, per project, or set a standing default:

beamd orgs                       # list the orgs this account can act in
beamd default acme               # your standing default scope (personal until set)
beamd open 3000 --scope beta     # one-off override
beamd whoami                     # show the resolved account + scope

On the hosted service the scope is folded into the subdomain as a hyphen suffix — https://<name>-<scope>.beamd.run — so --scope beta lands at https://api-beta.beamd.run. One *.beamd.run certificate covers them all.

beamd default is a set-once preference, not a mode you toggle — and the scope is visible in whoami, status, and every URL, so it can't silently misroute you. A self-hosted (OSS) edge has no org concept: beamd orgs says so and --scope is a no-op — your token fixes the namespace.

Where a tunnel lands

Every open / run resolves two things — which edge and which scope — on the same ladder, first match wins:

1. --server / --scope flag    # this command (explicit one-off)
2. .beamd  server: / scope:    # this repo  (committed, shared)
3. beamd default + current     # your primary account · default scope (personal unless set)

There is no beamd use. Beamd deliberately has no sticky, machine-global "current scope" to toggle day-to-day — that hidden, easily-stale mode is the footgun it removes. The only persistent routing lives in the repo's .beamd, where it's visible and shared.

Command summary

Automation skips all of this — see Auth & tokens and Embed in your app.