First Admin Setup

First Admin Setup

Audience: Sysadmin Status: ✅ Ready

A fresh TelosMUD install has accounts but no authority: every account starts at the player tier. This page covers how you mint the very first admin safely, how that admin promotes builders and further admins from inside the game, and how ordinary players are onboarded (spoiler: there's nothing to do). Authority lives in telos-account — it is the tier authority, and the world applies a character's tier as capability flags on login. For what the tiers mean, see Trust Tier Model.

The trust ladder is player < builder < admin, stored on the account, signed into the session assertion at login, and applied by the world on the target's next login.

(a) Pin the first admin at deploy time — TELOS_BOOTSTRAP_ADMIN

The intended way to create your first admin is the bootstrap-admin config pin. Set TELOS_BOOTSTRAP_ADMIN (config key bootstrap_admin) on telos-account to a GitHub login — the username, not an email address:

TELOS_BOOTSTRAP_ADMIN=octocat

The first account ever created for that OAuth login is created as an admin, atomically with an account_role_audit row recording a system actor (NULL), in a single transaction. Then, on that person's first GitHub sign-in (the normal OAuth flow — see Running Locally / OAuth Setup), their account is minted at the admin tier.

Important properties, so you use it correctly:

• Login match, not email. The pin matches the OAuth login (case-insensitive), because email is user-settable and unverified. Pin the GitHub username.
• Only at account creation. The pin grants admin only when the account is first created. It cannot re-grant or promote an account that already exists — if the person has already signed in once as a player, the pin does nothing for them. Set it before their first sign-in, or use the break-glass CLI below.
• Atomic and audited. The admin tier and the audit row are written together; there is no window where the account exists as a player first.

There is no in-game claim-code or trust-on-first-use ceremony — the config pin is the whole mechanism.

(b) Break-glass: telos-account set-tier

If you didn't set the pin before the first sign-in, or you need to recover from a last-admin lockout, use the break-glass CLI on the host. Here, host / database access is the authorization — the command talks to Postgres directly and bypasses the in-game permission check and the promotion ceilings entirely:

telos-account set-tier --character <name> --tier admin --force yes

It sets the tier unconditionally, writes an account_role_audit row attributed to a system (NULL) actor, and — note — has no last-admin-demote guard, so it will happily demote your only admin. Treat it as the root shell of the tier system: use it to mint the first admin when you skipped the pin, or to dig out of a lockout, and otherwise prefer the in-game verbs.

(c) Add more admins and builders — in-game promote / demote

Once you have one admin in the world, further tier changes are done from inside the game with two gate verbs:

promote <character> <tier>     # e.g. promote Alice builder
demote <character>             # demote to the baseline (player)

The gate itself makes no trust decision — it forwards the request to telos-account via the SetAccountTier RPC, and all authorization is enforced there:

• The actor must hold the manage-tiers capability (i.e. be an admin).
• Promotions are bounded by ceilings enforced with a compare-and-set under a row lock, so an actor cannot grant a tier above their own authority, and concurrent changes can't race.
• The path is fail-closed: if the trust ladder can't be validated, the change is refused.
• Every change writes an account_role_audit row.

Two behaviors worth calling out: demote <character> sends a demote-to-baseline sentinel (it resets to player), and any tier change takes effect on the target's next login — the world applies the new capability flags when they next connect, not mid-session. The RPC is reachable only by a trusted gate, which authenticates to the account service with a shared caller token (TELOS_ACCOUNT_CALLER_TOKEN); see OAuth Setup for that wiring.

(d) Add players — nothing to provision

There is no "create player" step. A player account comes into existence implicitly on first OAuth sign-in: the GitHub callback resolves-or-creates an account keyed on the OAuth identity (provider, provider_uid — never email), defaulting to the player tier, and the player then selects or creates a character over telnet through the content-driven chargen flow. Under the dev bypass this collapses further — typing a name spawns you with no account row at all. So onboarding a player is simply: point them at the server and have them sign in.

Where authority lives (recap)

• telos-account is the tier authority. Tiers are stored on the account, changed only through the audited paths above, and signed into the session assertion at login.
• The world applies, never mints. A world shard reads the tier from the signed session and turns it into capability flags for that session; it never decides tiers itself. This is why a tier change lands on next login and why it's consistent across shards and reconnects.
• Everything is audited. account_role_audit records every grant — system-actor rows for the bootstrap pin and the break-glass CLI, actor-attributed rows for in-game promote/demote.

See Trust Tier Model for how the tiers map to in-world capabilities and the reserved builder-admin permission model.