Roles
Bothy has four roles: viewer, editor, operator and shell. They are flat
and deliberately non-composite - holding one never implies another - because
shell grants an arbitrary terminal and must never be reachable by holding one
of the other three. Composites are how that happens by accident.
They gate five tiers - files, config, admin, ops and updates. Everything else on
the box is protected by the tailnet plus, where a service has one, its own login
on the shared DEV_LOGIN_* credential. "SSO is running" does not mean "this is
behind SSO".
What each role actually gets you#
| Role | What holding it lets you do, today |
|---|---|
viewer |
read through Bothy Files - browse, search, follow links, see history and diffs, download raw bytes and archives. Read which compose fields are patchable in Settings. Read anything in the cluster - deployments, pods, jobs, events, logs - and read what an update is doing |
editor |
write and delete a file through Bothy Files, and patch a declared field through a Settings form |
operator |
restart, stop and start a container; change a cluster workload - the 29 actions in apps/bothy-ops/catalog.toml, including scale, rollback, set-image, delete a pod or job and patch a ConfigMap key; request or pause an update; and read the admin tier (audit log, backups, credentials, users) |
shell |
nothing. It is defined, granted to nobody, and referenced by no router |
The Settings page renders shell as "Granted to nobody" rather than as an
ordinary "Not held", because it is not an absence you can fix by asking. It is
written as a condition rather than a constant, so if it is ever granted the page
will say so rather than keep insisting.
Where each role is enforced#
50 routers carry a role requirement, across 5 files in edge/dynamic/.
The requirement lives in the middleware, not in the service, and the three
middlewares are identical but for one word in a query string - which is the
property that makes the design worth having: adding a tier is four lines of
YAML, not another container.
| File | Gated routers | Requires |
|---|---|---|
edge/dynamic/bothy-files.yml |
4 | viewer to read and download, editor to write and delete |
edge/dynamic/bothy-config.yml |
2 | the same pair, over config fields |
edge/dynamic/bothy-admin.yml |
4 | operator on the audit log, backups, credentials and users |
edge/dynamic/bothy-ops.yml |
33 | operator on the three container verbs and every cluster change, viewer on every cluster read |
edge/dynamic/bothy-updates.yml |
7 | operator to request or pause an update, to check for updates or to run the night job; viewer to read its state |
| Role | Routers require it |
|---|---|
viewer |
24 |
editor |
3 |
operator |
23 |
This page used to list all fourteen routers by name. That table was written
when fourteen was the whole truth, and it was still at fourteen on 2026-09-23,
by which point the tree held forty-eight - so a reader asking "is this the whole
list" got yes from a document that had stopped counting. It is a counts table now, and
scripts/checks/router-gates.sh holds every row of it against
edge/dynamic/*.yml. The live table is always at
http://<node-ip>/-/api/traefik/http/routers; bothy-ops.yml's 33 routers are
generated from apps/bothy-ops/catalog.toml by scripts/gen-ops-wiring.py,
one per action, which is why naming them here could never have kept up.
Two structural choices behind that table are worth reading rather than skimming.
Delete is editor, not a role of its own, because removing a file is a
write, and a separate role would be a second thing to grant, a second thing to
revoke and a second thing to get wrong - for an action whose blast radius is
smaller than an overwrite's, since the service refuses to delete unless the
snapshot took a copy first. It still gets its own router: two rules that
share a role today must not share it by accident tomorrow.
The three control verbs are three routers, not one rule with three
alternatives, for the same reason. The day stop needs a tier above restart,
that is an edit to one router instead of a rule that has to be split first,
under pressure.
The middlewares themselves live in one place, and that placement is itself an argument:
sso-viewer,sso-editorandsso-operatorare defined inedge/dynamic/bothy-gates.yml, and in no router file;sso-errors- which turns a bare 401 into a sign-in page - lives inedge/dynamic/auth.ymland is borrowed by everything.
Every router file references the gates by bare name rather than defining its own
copies. Traefik's file provider merges every file in the directory into one
namespace, so two definitions of a middleware named sso-editor is a collision
whose winner no single file can decide - and the two would then drift
invisibly, with both routers still answering and one of them against the wrong
role.
Until 2026-09 each gate was defined in the first tier file that needed it
(sso-viewer/sso-editor in bothy-files.yml, sso-operator in
bothy-control.yml) and borrowed by the others, so deleting one tier's file
would have errored another tier's routers. That coupling is why the gates got a
file of their own when the tiers were consolidated.
sso-operator was deleted once, on 2026-08-15, along with the routes it gated,
for a reason worth keeping: a middleware nothing references is a loaded gun
with no trigger - it looks like protection while protecting nothing, and the
next router to want a gate might pick it up believing it is already proven in
use. It came back with the control tier. A gate in bothy-gates.yml that no
router references would be exactly that gun again - apps/bothy-ops/checks/wiring.py
asserts all three gates are defined there; keep each one in use.
One more, for completeness: the plain sso middleware in auth.yml - the one
that checks for any session rather than a role - is attached to no router at
all. Only the three role-scoped variants are in use.
It fails closed, and that was verified before it was trusted#
Against a role the user does not hold:
allowed_groups=editor -> 202 (they have it)
allowed_groups=shell -> 403 (nobody has it)
allowed_groups=<junk> -> 403 (fails closed)just files-check re-runs that probe, so the property is tested rather than
assumed. The third line is the one that matters most: because oauth2-proxy fails
closed on a group nobody holds, a tier can ship before its role exists in
the realm and refuse everybody rather than admit everybody. That is the safe
direction to be wrong in, and it is how the control tier was released.
Where the roles come from#
Keycloak, in a container on :8090, in a realm called devbox. The four roles
are declared in auth/realm-devbox.json.
Keycloak puts realm roles at a nested claim while oauth2-proxy reads a flat one,
so a protocol mapper flattens them into groups - without it,
allowed_groups=operator would silently match nothing.
There is deliberately no default-role block, so a new user lands with zero capability and is granted roles explicitly.
Who holds what is seeded by the keycloak-init one-shot in
auth/compose.yml, which grants your DEV_LOGIN_USER viewer, editor and
operator, and never shell. Without that step a fresh install refuses
everyone: the realm file declares four roles and zero users, so every gated
route would answer 403 to the only person who has just installed it, and the
product would look broken rather than unconfigured.
Two properties of that step you will meet eventually:
- The realm import is first-boot only. Adding a user or a role to the JSON
on an existing install does nothing, silently. Anything that must be true on
both a new box and an old one belongs in the one-shot, which re-runs on every
just up-auth. - Roles are re-asserted on every
just up-auth; the password is not. Granting a role somebody already holds is a no-op, so re-running restores a role revoked by accident in the console - the roles are declared in this repository, not in a console. A password is the opposite: somebody who changed theirs must not have it reset from under them.
To grant or revoke by hand, use the admin console at
http://<node-ip>:8090/admin, as KEYCLOAK_ADMIN_USER (admin by default)
with DEV_LOGIN_PASSWORD. Remember that the next just up-auth re-grants the
three seeded roles.
Three things that are not true, however they read#
The interface is not the boundary. lib/me.ts reads
/oauth2/userinfo and the Settings page lists your roles, but that is a
description of a token. Hiding a button is a courtesy that saves a round trip
and turns a bare 403 into a sentence arriving before the click. Every decision
is taken at the edge by a middleware reading a signed cookie that never trusts
anything the browser says. If that file were ever the only thing standing
between a user and an action, the action would be unprotected.
Identity headers are attribution, not permission. The services name the
commit author or the audit actor from X-Auth-Request-Email. Each of the three
tiers strips every client-supplied X-Auth-Request-* header before
forwardAuth runs, so the only one that can reach a service is the one
oauth2-proxy produced. If that were missing, the worst case would be a forged
name in a log, not an unauthorised action - which is exactly why it is defence
in depth rather than the defence. It matters most on the control tier: a forged
file write leaves a diff a human can read and revert, and a forged
stop postgres is over before anybody reads anything.
viewer is not weaker than operator on this deployment. Bothy Files
serves .env, and .env contains the cookie secret. Anyone who can read it can
mint a session for any role. That is a deliberate trade for a single-owner box
and it is documented at the point it is made, in
apps/bothy-files/policy.toml. It stops
being acceptable the moment a second person holds only viewer.
The three sources do not agree, and here is how#
The roles are described in three places, and each is authoritative for a different question. They have drifted.
The realm (auth/realm-devbox.json) is the definition. Its descriptions
name capabilities that do not exist here:
vieweris described as "Read-only: dashboards, logs, metrics, docs." Grafana and Prometheus are not behind SSO at all; they carry their own login, soviewergrants nothing there. What it actually gates is the file tier and the config tier's read.editoris described as "Can change content - wiki/docs pages, dashboards." The wiki was deleted on 2026-08-18, and no role gates a dashboard. What it actually gates is a file write, a file delete, and a config patch.operatoris described as "Can act on the stack - restart containers, silence alerts." Restarting containers is right. Nothing anywhere silences an alert.
The interface (ROLE_MEANING in
apps/bothy-web/web/src/lib/me.ts) is the user-facing wording and is much
closer, but it is scoped to the file tier and predates the config tier:
viewer reads "browse files, search their contents, download bytes" and also
gates reading config fields; editor reads "change a file on disk" and also
gates deleting one and patching a compose label through a form.
The README was the third, and it undercounted - twice, the same way. It
first listed three routers, all in bothy-files.yml, omitting
bothy-files-delete, /links, and the config and control tiers entirely; the
replacement listed fourteen and went stale in turn. Since 2026-09-23 it
carries the same checked counts tables as this page, so the three sources can no
longer disagree about how many - only about what the roles mean.
SECURITY.md disagreed with itself in the same way and in one section: the
status blockquote at the top of § 1 said nine role-gated routers in three
files, and four paragraphs later the same section still said "Three routers
do now, all in edge/dynamic/bothy-files.yml". Corrected 2026-08-19 - the
blockquote was the half that matched the router table.
The router table is the one that is true, because it is the one that runs. It
is live at http://<node-ip>/-/api/traefik/http/routers, and there is no
Traefik dashboard to check instead - it was deleted because it leaked a
credential.
Related#
- Operating it from the console - what
operatorunlocks - Bothy Files - what
viewerandeditorunlock - Settings - where your roles are shown, and why that panel changes nothing
SECURITY.md- the threat model, and the case for and against ashellrole that does something