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, and 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. It degrades 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, with 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, since 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.yaml  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.yaml, where it's visible and shared.

Write that beamd.yaml in one step with beamd link (interactive, like vercel link): it pins the edge + org, and can capture named services so beamd open api Just Works.

Command summary

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