roles: name the family in the role — `-server` for fleet machines, `-box` for box tenants #76

New issue

Closed

opened 2026-07-19 23:54:09 +00:00 by dan-claude-bot · 1 comment

dan-claude-bot commented

2026-07-19 23:54:09 +00:00

(Migrated from github.com)

The rule

suffix	family	roles
`-server`	fleet machines	`control-plane-server`, `workload-server`, `runner-server`, `staging-server`, `dev-server`
`-box`	box tenants (guests)	`claude-box`, `codex-box`, `grok-box`, `staging-box`
(bare)	neither	`custom`, `workstation`

custom presets nothing and can be any shape — a guest included — so a family suffix would be a claim it is not entitled to make. workstation is somebody own device, not fleet infrastructure: it joins by interactive login, comes up user-owned and untagged, and the tailnet never manages it.

staging-server is a NEW preset (class=server host=yes join=authkey) — the VM-host shape #31 retired, restored under a name that cannot be confused with its own guests. host=yes already installs the box CLI and runs box setup-host, so it is a table row rather than new machinery.

Deliberately a hard cut

No aliases. Old role names stop working, and a box minted against the old names is re-minted rather than migrated. The fleet is two operators who can re-mint at will, and the alternative — nine deprecation paths, each a place where the old name quietly keeps working — costs more than it buys at this size.

Nothing reads role names back out of /etc/rig/role: the marker consumers (users apply, close-root) key off the class= and host= traits, so this is a CLI-surface change, not a fleet migration.

Known wart, tracked separately

-server collides with the --class human|server trait: dev-server is class=human, because operators enter it as themselves and close-root shuts its root door. The suffix names the FAMILY, the class names the DOOR POLICY, and they are orthogonal — but they share a word, and that is genuinely confusing. Fixing it means renaming the class trait to what it actually controls, which touches markers on live machines and so gets its own issue rather than riding along here.

Shape of the work

machine roles: rename presets, dispatch, usage, README table, tests
tenant roles: rename the tenant mechanism + lib/tenant-config.sh, dispatch, usage, README, tests
heavy-duty/box: the seeds BOX_BOOTSTRAP_ROLE values follow the tenant names

One flat namespace holds two families that live on opposite sides of a trust boundary — tailnet machines rig builds, and guests a box mints — and nothing in a role name says which one you are asking for. `staging` made that concrete: the word names both the metal that hosts guests and the guests themselves, and only one of them could have the name. ## The rule | suffix | family | roles | |---|---|---| | `-server` | fleet machines | `control-plane-server`, `workload-server`, `runner-server`, `staging-server`, `dev-server` | | `-box` | box tenants (guests) | `claude-box`, `codex-box`, `grok-box`, `staging-box` | | *(bare)* | neither | `custom`, `workstation` | `custom` presets nothing and can be any shape — a guest included — so a family suffix would be a claim it is not entitled to make. `workstation` is somebody own device, not fleet infrastructure: it joins by interactive login, comes up user-owned and untagged, and the tailnet never manages it. `staging-server` is a NEW preset (`class=server host=yes join=authkey`) — the VM-host shape #31 retired, restored under a name that cannot be confused with its own guests. `host=yes` already installs the box CLI and runs box `setup-host`, so it is a table row rather than new machinery. ## Deliberately a hard cut No aliases. Old role names stop working, and a box minted against the old names is re-minted rather than migrated. The fleet is two operators who can re-mint at will, and the alternative — nine deprecation paths, each a place where the old name quietly keeps working — costs more than it buys at this size. Nothing reads role *names* back out of `/etc/rig/role`: the marker consumers (`users apply`, `close-root`) key off the `class=` and `host=` traits, so this is a CLI-surface change, not a fleet migration. ## Known wart, tracked separately `-server` collides with the `--class human|server` trait: `dev-server` is `class=human`, because operators enter it as themselves and `close-root` shuts its root door. The suffix names the FAMILY, the class names the DOOR POLICY, and they are orthogonal — but they share a word, and that is genuinely confusing. Fixing it means renaming the class trait to what it actually controls, which touches markers on live machines and so gets its own issue rather than riding along here. ## Shape of the work - [ ] machine roles: rename presets, dispatch, usage, README table, tests - [ ] tenant roles: rename the tenant mechanism + `lib/tenant-config.sh`, dispatch, usage, README, tests - [ ] heavy-duty/box: the seeds `BOX_BOOTSTRAP_ROLE` values follow the tenant names

dan-claude-bot commented

2026-07-19 23:56:17 +00:00

(Migrated from github.com)

Correction to the issue body: role names are not purely informational. Two commands match the marker on the role NAME, not on traits:

commands/coolify-install.sh:56 — ""|"role=control-plane"|"role=control-plane "*)
commands/coolify-backup-install.sh:82 — the same pattern

Both WARN rather than die, so a stale marker degrades gracefully rather than breaking a box, but the rename has to carry them or rig coolify install starts warning on a correctly-bootstrapped control plane. Folded into the machine-role PR.

Second consequence worth stating up front: TS_HOSTNAME defaults to the role name, so the default tailnet hostname for these boxes changes with the rename (control-plane -> control-plane-server). Anything pinning a hostname — ACL entries, environments.yaml server names, host keys — is affected on the next bootstrap that takes the default. --hostname has always been available to hold a name steady.

Correction to the issue body: **role names are not purely informational.** Two commands match the marker on the role NAME, not on traits: - `commands/coolify-install.sh:56` — `""|"role=control-plane"|"role=control-plane "*)` - `commands/coolify-backup-install.sh:82` — the same pattern Both WARN rather than die, so a stale marker degrades gracefully rather than breaking a box, but the rename has to carry them or `rig coolify install` starts warning on a correctly-bootstrapped control plane. Folded into the machine-role PR. Second consequence worth stating up front: `TS_HOSTNAME` defaults to the role name, so the default tailnet hostname for these boxes changes with the rename (`control-plane` -> `control-plane-server`). Anything pinning a hostname — ACL entries, `environments.yaml` server names, host keys — is affected on the next bootstrap that takes the default. `--hostname` has always been available to hold a name steady.