docs: a first SSO login makes a human's forge account
setup.md said Swarm SSO creates the operator's forge account, which was not true until the previous commits. It now says how: sign in to the forge once through authelia, then `swarmctl forge make-admin <you>`. sso.md says what that first login does and why ACCOUNT_LINKING is `login`. README, hivectl.md and forge.md drop `hivectl forge create-user`, and the swarmctl README gains `forge make-admin`. Refs #3782
This commit is contained in:
parent
d56d8f2b36
commit
0cbb7db2c0
6 changed files with 62 additions and 33 deletions
|
|
@ -11,7 +11,7 @@ Available via the `hive-c0re` package in the host NixOS config.
|
|||
|
||||
Unlike the `hive-c0re` daemon subcommands (which go through the broker),
|
||||
`hivectl` covers direct host-side administration: manual provisioning of
|
||||
forge + matrix accounts, gateway htpasswd management, container
|
||||
matrix accounts, gateway htpasswd management, container
|
||||
lifecycle shortcuts, and interactive agent shell access.
|
||||
|
||||
This page is the curated guide. For the exhaustive flag-by-flag
|
||||
|
|
@ -24,30 +24,18 @@ markdown-docs > docs/tools/hivectl-cli.md`.
|
|||
|
||||
## Forge
|
||||
|
||||
Manual entry to the same idempotent provisioning flow `hive-c0re` runs
|
||||
at boot. Useful for recovery, ad-hoc re-provisioning, or fixing a single
|
||||
agent without bouncing the daemon.
|
||||
Reconciles an agent's config between this hive and the forge. `hivectl`
|
||||
makes no forge accounts: a human's first SSO login to the forge makes
|
||||
theirs, and `swarmctl forge make-admin <name>` makes it a site admin.
|
||||
swarm-controller makes an agent's, and `swarmctl agent mint-forge-token
|
||||
<agent>` checks and, if needed, re-mints its token.
|
||||
|
||||
```bash
|
||||
hivectl forge create-user iris # refused: `iris` is an agent; use `swarmctl agent mint-forge-token iris`
|
||||
hivectl forge create-user mara # create forge account for a human user; prints token to stdout
|
||||
hivectl forge create-user mara --password hunter2 # set a web-login password
|
||||
hivectl forge create-user mara --password-stdin # read password from stdin (safer for scripting)
|
||||
|
||||
hivectl forge reconcile-config iris # show local-applied <-> forge config divergence, then prompt
|
||||
hivectl forge reconcile-config iris --from forge # reset local applied checkout to forge main (effective next deploy)
|
||||
hivectl forge reconcile-config iris --verbose # include the full diff, not just --stat
|
||||
```
|
||||
|
||||
- For **agents** (name has a state dir under `/var/lib/hyperhive/agents/`):
|
||||
`create-user` refuses. swarm-controller mints an agent's token into
|
||||
the swarm secret store; `swarmctl agent mint-forge-token <agent>` checks
|
||||
and, if needed, re-mints it.
|
||||
- For **non-agents** (humans): creates the account and prints the token to
|
||||
stdout, creating no state dir. Re-running after account already exists
|
||||
re-mints the token and prints it again — safe for password resets.
|
||||
- Without `--password` / `--password-stdin` `create-user` uses a random
|
||||
throwaway password (fine for agents — they auth by token).
|
||||
- `reconcile-config <agent>` shows the divergence between the agent's local
|
||||
applied config checkout and its forge `agent-configs/<agent>` `main`, then
|
||||
reconciles. `--from forge` resets the local checkout to forge `main` (takes
|
||||
|
|
@ -101,7 +89,7 @@ hivectl matrix invite @mara:server --room '#hive-chat:server' # ...or to a spec
|
|||
|
||||
Write an operator-supplied GitHub personal access token (PAT) into an
|
||||
agent's token file so its `gh` wrapper + git credential helper can act as
|
||||
the bot account. Unlike forge/matrix there is no account creation — the PAT
|
||||
the bot account. Unlike matrix there is no account creation — the PAT
|
||||
is for an existing GitHub account. A CLI alternative to the dashboard
|
||||
credentials tab; the [GitHub integration](../integrations/github.md) is on by default
|
||||
(`services.hyperhive.agent.github.enable`), so no per-agent config is needed.
|
||||
|
|
|
|||
Loading…
Reference in a new issue