swarm UI: log an agent into claude from its card; the credentials go to bao and the agent picks them up
A new swarm service, `swarm-claude-login`, in its own container on the host
that sets `deploy.claude-login.enable` (defaulted on by `allSwarmServices`
where the host has the minter's store leaf, like the review classifier).
- swarm-ui: an agent card showing "login needed" gets a "log in" button.
Its dialog starts the login, shows the URL claude printed, and takes the
pasted code.
- swarm-controller: `POST/DELETE /api/agents/{name}/claude-login` and
`POST /api/agents/{name}/claude-login/code`, behind the swarm UI's
authelia-gated `/api/`, relay the steps to the minter as requests on
`$SWARM.claude-login.request`.
- swarm-claude-login: runs `claude auth login` over piped stdio with HOME
and CLAUDE_CONFIG_DIR in a per-login scratch dir, scrapes the first
https URL, writes the code to stdin, and stores the `.credentials.json`
at `swarm/agents/<agent>/claude-credentials` with a KV v2 write, a new
version over any earlier one. The scratch dir goes on every exit path; a
login waits 15 minutes for its code.
- hive-agent: while parked in `wait_for_login`, reads that leaf every 30 s
under the agent's own cert and installs it only when its KV version is
newer than the one recorded in `<harness>/claude-credentials-version`.
An equal or older version is never put back, because claude rotates the
refresh token and the stored copy is stale after the first refresh.
- swarm-secret-client: `claude_login` paths and `SecretStore::read_versioned`.
- Credentials: a `claude-login` store leaf minted by glue-bao-tls, a
`swarm-claude-login` policy (create/update on
`swarm/agents/+/claude-credentials`, read on its own queue client
secret), an authelia machine client, and a `--claude-login-client`
grant in the queue's auth-callout responder. The unit runs as a static
system user.
The hive's own web-UI login is unchanged.
Refs #5268
This commit is contained in:
atlas
mara
parent
248df20164
commit
d5de1e4943
48 changed files with 2680 additions and 42 deletions
|
|
@ -91,6 +91,9 @@ declarations.
|
|||
(planned, not implemented yet).
|
||||
- **Does an agent config PR build before it's merged?** →
|
||||
[`swarm/builder.md`](swarm/builder.md).
|
||||
- **How do I log an agent in to claude from the swarm UI, and why doesn't a
|
||||
stale stored copy log it out again?** →
|
||||
[`swarm/claude-login.md`](swarm/claude-login.md).
|
||||
|
||||
## Scheduler, CI, observability
|
||||
|
||||
|
|
|
|||
66
docs/swarm/claude-login.md
Normal file
66
docs/swarm/claude-login.md
Normal file
|
|
@ -0,0 +1,66 @@
|
|||
# Claude login from the swarm UI
|
||||
|
||||
An operator logs an agent in to claude from the agent's card in the swarm UI.
|
||||
No hive is in the path: the login runs in the swarm's `swarm-claude-login`
|
||||
service, the credentials go to the agent's own leaf in the secret store, and the
|
||||
agent's harness installs them from there.
|
||||
|
||||
Where it runs and how it's enabled: [`services.md`](services.md#claude-login-minter).
|
||||
|
||||
## What happens on a login
|
||||
|
||||
1. The agent publishes `needs_login` in its turn-state header, and its card
|
||||
shows **login needed** with a **log in** button.
|
||||
2. **log in** opens a dialog, which calls
|
||||
`POST /api/agents/<agent>/claude-login`. swarm-controller relays the start as
|
||||
a request on the queue subject `$SWARM.claude-login.request`.
|
||||
3. The minter runs `claude auth login` with `HOME` and `CLAUDE_CONFIG_DIR` in a
|
||||
fresh scratch directory, over plain stdio pipes, and answers with the first
|
||||
`https://` URL it prints. The dialog shows that URL.
|
||||
4. The operator opens the URL, signs in to the agent's own claude account, and
|
||||
pastes the code the page shows into the dialog, which posts it to
|
||||
`POST /api/agents/<agent>/claude-login/code`.
|
||||
5. The minter writes the code to claude's stdin and waits for it to exit. It
|
||||
stores the `.credentials.json` claude wrote at
|
||||
`swarm/agents/<agent>/claude-credentials` (field `value`), as a new version
|
||||
over any stored before, and removes the scratch directory.
|
||||
6. The agent's harness, while it waits for a login, reads that leaf every 30
|
||||
seconds under the agent's own certificate. When the stored version is newer
|
||||
than the one it installed last, it writes the file to
|
||||
`~/.claude/.credentials.json`, records the version, and resumes its turn
|
||||
loop as it does after a login from the agent's web UI.
|
||||
|
||||
A started login waits 15 minutes for its code, then the minter stops it.
|
||||
Starting another login for the same agent replaces the running one. Each step
|
||||
has a minute to finish; a refused code fails the login, and the dialog shows
|
||||
what claude printed.
|
||||
|
||||
## Why the harness takes only a newer version
|
||||
|
||||
`claude` rotates the refresh token in `.credentials.json` as it uses the
|
||||
session, and the agent can't write the store. After the first refresh the
|
||||
stored copy is stale. A harness that installed it whenever the bytes differed
|
||||
would replace the agent's live session with a stale copy and log the agent
|
||||
out. The harness therefore compares the store's KV version with the last
|
||||
version it installed (`claude-credentials-version` under the harness dir):
|
||||
|
||||
- it installs a newer version, that is, a new login;
|
||||
- it leaves an equal or older version alone, even when the agent needs a
|
||||
login again, so it never puts back a session that has gone bad;
|
||||
- it reads nothing while the agent has a session.
|
||||
|
||||
## Credentials
|
||||
|
||||
| Principal | Grant |
|
||||
| -------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
|
||||
| `swarm-claude-login`, in its container | `create`, `update` on `swarm/agents/+/claude-credentials`; `read` on `swarm/services/<minter client id>/oidc/client` |
|
||||
| the agent, under its own certificate | `read` on its own `swarm/agents/<agent>/*`, which covers the leaf |
|
||||
|
||||
The minter has no read on the leaf and nothing else under an agent. Every
|
||||
hive's policy reads `swarm/agents/*`, so every hive can read every agent's
|
||||
claude session, as it can read the GitHub token.
|
||||
|
||||
## What stays
|
||||
|
||||
The agent's own web UI login (`/login`) still works, unchanged. It goes away
|
||||
once the operator has confirmed the swarm login works.
|
||||
|
|
@ -68,6 +68,7 @@ of the cell says how.
|
|||
| `swarm/agents/<agent>/forge-token` | `swarm-controller`, at agent creation and in a pass every 5 minutes over every agent with a store identity | the agent container itself, under its own certificate, fetched to `/run/hive-agent-forge-token/token` | ✅ the controller re-mints when the stored token is missing or no longer matches the forge (last eight characters and scopes) | ✅ the agent re-fetches on a 10-minute timer |
|
||||
| `swarm/agents/<agent>/forge/<label>` | `swarm-controller`, when an operator links an external forge account in the swarm UI | `hive-agent-forge-accounts` in the agent container, under the agent's own certificate, into `<state>/forge-<label>-token` and `forge-<label>.json` | ❌ an operator's token; replaced only by deleting it and linking the label again | ✅ the agent re-fetches on a 2-minute timer |
|
||||
| `swarm/agents/<agent>/github-token` | `swarm-controller`, when an operator links a GitHub account in the swarm UI | `hive-agent-github-token` in the agent container, under the agent's own certificate, into `<state>/github-token` | ❌ an operator's token; replaced only by deleting it and linking it again | ✅ the agent re-fetches on a 2-minute timer, and `hive-github-notify` re-reads the file on every poll |
|
||||
| `swarm/agents/<agent>/claude-credentials` | `swarm-claude-login`, under its own certificate, when an operator logs the agent in from its card in the swarm UI; a new version per login | `hive-agent` in the agent container, under the agent's own certificate, into `~/.claude/.credentials.json`, only while the agent waits for a login and only a version newer than the one it installed last | ❌ an operator's login; a relogin writes a new version | ✅ the waiting agent reads the store every 30 seconds |
|
||||
| `swarm/hives/<hive>/matrix/sender-token` | `swarm-controller`, with the swarm's appservice token, for every hive in its directory in a five-minute pass | `swarm-controller` under its own certificate, before it decides whether to mint, and hive-c0re's `stored_sender_token()`, under the hive's own certificate | ✅ the controller's pass re-mints when the stored token is missing, unknown to the homeserver, or someone else's | ✅ hive-c0re's matrix sweep reads the store every run and overwrites its token file when the store's token differs |
|
||||
| `swarm/hives/<hive>/forge/token` | `swarm-controller`, with the forge's admin API, for every hive in its directory in a five-minute pass | `swarm-controller` under its own certificate, before it decides whether to mint, and hive-c0re's `forge::reader_token()`, under the hive's own certificate | ✅ the controller's pass re-mints when the stored token is missing or no longer matches the forge (last eight characters and scopes) | ✅ hive-c0re reads the store on every forge read |
|
||||
| `swarm/hives/<hive>/queue/agent` | authelia | `swarm-bao-queue-agent` on the hive's host, under its own per-hive certificate; no agent's policy reaches it | must be stated | must be stated |
|
||||
|
|
|
|||
|
|
@ -405,10 +405,10 @@ next controller restart.
|
|||
### Per-principal identities
|
||||
|
||||
Bao matches a cert-auth role on the certificate's subject, so a certificate is an
|
||||
identity and sharing one merges the identities. Each of these eight leaves has
|
||||
identity and sharing one merges the identities. Each of these nine leaves has
|
||||
a role and a policy of its own, and reaches one path, except the review
|
||||
classifier's, the builder's, the forge host's and Grafana's, which reach two
|
||||
each:
|
||||
classifier's, the builder's, the claude login minter's, the forge host's and
|
||||
Grafana's, which reach two each:
|
||||
|
||||
| unit | option pair under `deploy.bao.` | reads, or writes |
|
||||
| --------------------------------------------------- | ------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
|
|
@ -418,28 +418,30 @@ each:
|
|||
| `swarm-bao-forwarder-oidc` | `forwarderOidcClientCertFile` / `forwarderOidcClientKeyFile` | `swarm/services/<store forwarder client id>/oidc/client` |
|
||||
| `swarm-bao-ci-runner` | `ciRunnerClientCertFile` / `ciRunnerClientKeyFile` | `swarm/services/ci-runner/registration-token` |
|
||||
| `swarm-review-classifier`, in its container | `reviewClassifierClientCertFile` / `reviewClassifierClientKeyFile` | `swarm/services/review-classifier/anthropic-api-key`, `swarm/services/review-classifier/acp-provider` and `swarm/services/<classifier client id>/oidc/client` |
|
||||
| `swarm-claude-login`, in its container | `claudeLoginClientCertFile` / `claudeLoginClientKeyFile` | creates and updates `swarm/agents/+/claude-credentials`; reads `swarm/services/<minter client id>/oidc/client` |
|
||||
| `swarm-bao-forge-publisher`, `swarm-bao-forge-oidc` | `forgePublisherClientCertFile` / `forgePublisherClientKeyFile` | writes `swarm/controller/swarm-controller/forge/token`; reads `swarm/services/<forge client id>/oidc/client` |
|
||||
|
||||
The first exists **per hive**, because the path it reads carries a hive name
|
||||
and every hive runs its own reader. Its subject is
|
||||
`<deploy.bao.queueAgentCommonNamePrefix>-<hive>`; `swarm.nix` reserves that
|
||||
composed spelling as a hive name, so nobody can name a hive into another hive's
|
||||
role. The other seven reach a path that names a swarm service rather than a hive,
|
||||
role. The other eight reach a path that names a swarm service rather than a hive,
|
||||
so one role each is enough and their subjects are the flat
|
||||
`deploy.bao.grafanaOidcCommonName`, `deploy.bao.otelOidcCommonName`,
|
||||
`deploy.bao.forwarderOidcCommonName`, `deploy.bao.ciRunnerCommonName`,
|
||||
`deploy.bao.reviewClassifierCommonName`, `deploy.bao.builderCommonName` and
|
||||
`deploy.bao.forgePublisherCommonName`. The last is the only writer, and the one
|
||||
leaf two units share: the forge's host holds one store identity for the token it
|
||||
publishes and the OIDC client secret it reads.
|
||||
`deploy.bao.reviewClassifierCommonName`, `deploy.bao.builderCommonName`,
|
||||
`deploy.bao.claudeLoginCommonName` and `deploy.bao.forgePublisherCommonName`.
|
||||
The last two are the writers, and the last is the one leaf two units share:
|
||||
the forge's host holds one store identity for the token it publishes and the
|
||||
OIDC client secret it reads.
|
||||
|
||||
On a host that mints its own PKI, `glue-bao-tls.nix` signs all seven and defaults
|
||||
all fourteen options, and there is nothing to do. Elsewhere you copy each leaf from
|
||||
On a host that mints its own PKI, `glue-bao-tls.nix` signs all eight and defaults
|
||||
all sixteen options, and there is nothing to do. Elsewhere you copy each leaf from
|
||||
the store's host and name it here: a service principal's from the top of
|
||||
`/var/lib/swarm-bao-pki/`, another hive's queue-agent pair from
|
||||
`/var/lib/swarm-bao-pki/hives/<hive>/` ([bao.md § TLS](bao.md#tls) lists that
|
||||
directory). That's one file per principal rather than one file
|
||||
shared by seven, which is the whole of what this buys. `swarm-ci-runner.nix`
|
||||
shared by eight, which is the whole of what this buys. `swarm-ci-runner.nix`
|
||||
refuses the build wherever the runner runs without its pair, as
|
||||
`swarm-review-classifier.nix` does for the classifier and `swarm-grafana.nix`
|
||||
for Grafana. The forge's pair refuses nothing: without
|
||||
|
|
@ -448,7 +450,7 @@ naming both options, and the controller runs without forge access and the forge
|
|||
without a login source until an operator places the leaf.
|
||||
|
||||
On a host without the store, where the forwarder never runs, forgetting one of
|
||||
the other seven isn't a quiet degrade. A hand-configured remote-store hive that
|
||||
the other eight isn't a quiet degrade. A hand-configured remote-store hive that
|
||||
names the hive's own `clientCertFile` and misses a principal's pair has the
|
||||
build refused, by the module of the reader it missed, naming that pair — see
|
||||
[what a missing leaf costs](#what-a-missing-leaf-costs) below.
|
||||
|
|
|
|||
|
|
@ -330,3 +330,23 @@ secret store by name, under its own `review-classifier` leaf. On a host
|
|||
without the store, that leaf is the one file to copy, as for the CI runner.
|
||||
The swarm UI's try-out drives it through swarm-controller; what a run is
|
||||
and what it costs are in [`review-classifier.md`](review-classifier.md).
|
||||
|
||||
### Claude login minter
|
||||
|
||||
The claude login minter, in a `swarm-claude-login` container on the host that
|
||||
sets `deploy.claude-login.enable`. `allSwarmServices` defaults it on wherever
|
||||
the host has the minter's store identity, on the review classifier's terms.
|
||||
Run one: a login in progress lives in the service's memory between its start
|
||||
and its code.
|
||||
|
||||
An operator logs an agent in from the **log in** button on its card in the
|
||||
swarm UI. swarm-controller relays the start and the pasted code over the queue,
|
||||
the minter runs `claude auth login` and writes the credentials to the agent's
|
||||
`swarm/agents/<agent>/claude-credentials`, and the agent's harness installs a
|
||||
version newer than the one it installed last.
|
||||
|
||||
It needs neither the forge nor a hive on its host. It reaches the queue and the
|
||||
secret store by name, under its own `claude-login` leaf, and reaches claude's
|
||||
login endpoints over the network. On a host without the store, that leaf is
|
||||
the one file to copy, as for the CI runner. The flow and the version rule are
|
||||
in [`claude-login.md`](claude-login.md).
|
||||
|
|
|
|||
|
|
@ -22,8 +22,11 @@ domain, covers host-level detail for one hive.
|
|||
Everything it shows comes from [`swarm-controller`](../../swarm-controller/README.md).
|
||||
An agent created here or with `swarmctl agent create` starts `paused`; set it
|
||||
`up` from its card. A card shows **login needed** when the agent's own
|
||||
turn-state header says its claude has no session. Log it in from the agent's
|
||||
own web UI.
|
||||
turn-state header says its claude has no session, and a **log in** button
|
||||
that runs the claude login from a dialog: open the URL it shows, then paste
|
||||
the code back. The credentials go to the agent through the secret store
|
||||
([`claude-login.md`](claude-login.md)). The agent's own web UI login still
|
||||
works too.
|
||||
|
||||
### Agent and subagent terminals
|
||||
|
||||
|
|
|
|||
Loading…
Reference in a new issue