swarm: an agent's backend secrets get a store leaf of their own, and its backend environment reads back
The credentials of an agent's backend (ANTHROPIC_API_KEY and the like) move to their own leaf, swarm/agents/<agent>/backend-secrets, written through new PUT, GET and DELETE routes on /api/hives/{hive}/agents/{agent}/backend-secrets. GET says only whether any are stored. The backend environment at backend-env now reads back as stored through GET on its route, so it holds configuration only.
The agent's hive-agent-backend-env unit now runs on every agent with a store, reads both leaves and writes the configuration and then the secrets into the one file the harness and the subagent daemon load, so a secret wins over a variable of the same name. It removes the file when the store holds neither. The harness counts an agent whose environment holds ANTHROPIC_API_KEY or ANTHROPIC_AUTH_TOKEN as API-billed, so it tries the key instead of waiting for a Claude login; a real 401 still sets needs-login. The controller's policy may delete the new leaf.
Tests: the secret-client path, the controller routes, the script test of the unit with a stub bao, the module-eval cases and the harness's mode check. Docs: the swarm UI routes, the credentials reference and the API-key provider page.
This commit is contained in:
parent
c9204ad0e0
commit
33fdd5205e
3 changed files with 737 additions and 107 deletions
|
|
@ -34,6 +34,7 @@ the rest of the cell says how.
|
|||
| `swarm/agents/<agent>/forge/<label>` | `swarm-controller`, when you link an external forge account in the swarm UI | the agent | ❌ your token; delete it and link the label again | ✅ every 2 minutes |
|
||||
| `swarm/agents/<agent>/gitlab/<label>` | `swarm-controller`, when you link a GitLab account through the API | the agent | ❌ your token; delete it and link the label again | ✅ every 2 minutes; a deleted account leaves the agent's `glab` configuration on the next run |
|
||||
| `swarm/agents/<agent>/github-token` | `swarm-controller`, when you link a GitHub account in the swarm UI | the agent, which keeps it in `/run` only; the `<state>/github-token` copy of an earlier version is no longer read | ❌ your token; delete it and link again | ✅ every 2 minutes |
|
||||
| `swarm/agents/<agent>/backend-secrets` | `swarm-controller`, when you set the API key or the secrets in the swarm UI; no unit writes it | the agent, read-only, through `hive-agent-backend-env` | ❌ nothing replaces it without you | ❌ the file in `/run` refreshes every 2 minutes, and the harness loads it at its next start |
|
||||
| `swarm/agents/<agent>/backend-env` | `hive-agent-backend-env`, in the agent's container, from the agent's `backendEnvironmentFile` when the leaf holds nothing (field `env`, the file's exact text); or `swarm-controller`, when you set the API-key environment in the swarm UI | the agent | ❌ nothing replaces it without you; a save in the swarm UI overwrites it, including text an agent wrote into an empty leaf; the agent's file stays as it was | ❌ the file in `/run` refreshes every 2 minutes, and the harness and the subagent daemon load it at their next start |
|
||||
| `swarm/agents/<agent>/claude-credentials` | `swarm-claude-login`, when you log the agent in from its card; one version per login | the agent, while it waits for a login | ❌ log in again | ✅ every 30 seconds while waiting |
|
||||
| `swarm/hives/<hive>/forge/token` | `swarm-controller`, every 5 minutes; deleted when the hive leaves the roster | `swarm-controller` and the hive | ✅ when missing or no longer matching the forge | ✅ read on every forge call |
|
||||
|
|
@ -138,7 +139,7 @@ pieces fit, and the reasoning behind them, is in [`credentials.md`](../../2-hand
|
|||
| the hive collector's copy of its hive's OIDC secret | `swarm-bao-hive-otel-oidc.service` reads it out of the swarm secret store under the hive's own leaf, **on every hive that runs the collector and holds that leaf**; the leaf is the source | `/run/hive-otel-oidc/hive-<name>.secret` on the hive's host tmpfs, 0400 root, loaded by `LoadCredential` — never on persistent disk, so a reboot fetches it again | same unit, same path, co-located or not. Nothing for an operator to place beyond the hive's store leaf (`deploy.bao.clientCertFile`). Naming a secret file with `otel.clientSecretFile` instead is legacy for a host without a leaf: the build warns, and the fix is to place the leaf from `/var/lib/swarm-bao-pki/hives/<hive>/` and drop the setting |
|
||||
| the swarm controller's forge token | the forge's `forgejo-swarm-controller-account`, in-container, once. An attempt that fails or runs past 30 seconds retries after 5 seconds, then at growing intervals up to 5 minutes | the swarm secret store at `swarm/controller/swarm-controller/forge/token`, written by the mint under the forge publisher's leaf, which the forge container loads as a credential; the controller holds it in memory only. `/var/lib/forgejo/swarm-controller-token-name` in the forge container holds its name, the minter's record that it has minted | nothing to place beyond the controller's store leaf. A forge host without the store needs the publisher's leaf placed (`deploy.bao.forgePublisherClientCertFile`) |
|
||||
| the swarm controller's Grafana token | `swarm-bao-grafana-controller-token.service`, **on the host that runs Grafana**, as Grafana's built-in admin over its socket: it creates the `swarm-controller` service account as a Viewer (and sets it back to Viewer on every run), mints a token for it and writes it to the swarm secret store at `swarm/controller/swarm-controller/grafana/token` under Grafana's leaf. It waits up to 60 seconds for Grafana's socket to answer before its first call. Re-run every ten minutes: it keeps a stored token Grafana accepts, and replaces one Grafana refuses with 401 (or a missing one), deleting every other token of that account first | the swarm secret store only; the controller reads it for `GET /api/alerts` and holds it in memory, re-reading the store once when Grafana answers 401 | nothing to place: Grafana's leaf is already required to run Grafana. Until the unit has run, `/api/alerts` answers 503 naming the empty path |
|
||||
| an agent's API-key environment (`ANTHROPIC_API_KEY`, `ANTHROPIC_BASE_URL`, an ACP provider key) | `hive-agent-backend-env.service`, in the agent's container, on an agent with a store that uses `useApiKey` or the `acp` runtime. When the store holds nothing at `swarm/agents/<agent>/backend-env` and `backendEnvironmentFile` is a non-empty file, it creates the leaf with the file's exact bytes and `-cas=0`, under the agent's own leaf, which may create that path and not update it. It never rotates a value and never rewrites or deletes the file. To set or replace a key, use **set the API-key environment** in the swarm UI (`PUT /api/hives/{hive}/agents/{agent}/backend-env`): `swarm-controller` overwrites the leaf with its own grant, and the store's value then wins over the file. Its **remove** (`DELETE` on the same path) deletes the leaf, and an agent whose file has content then creates it from that file again | the swarm secret store at that path; the unit writes it to `/run/hive-agent-backend-env/env` (tmpfs, `0600`, root), and `hive-agent` and `hive-subagent-daemon` load that after `backendEnvironmentFile` as `EnvironmentFile=` | the same unit, same path. A variable in the store wins over the same one in the file. With the store down at a start, the file alone carries the agent, as it did before the store held a copy; with an older hive build the agent ignores the leaf and keeps reading the file |
|
||||
| an agent's API-key environment (`ANTHROPIC_API_KEY`, `ANTHROPIC_BASE_URL`, an ACP provider key) | `hive-agent-backend-env.service`, in the agent's container, on every agent with a store, whatever its runtime or its login kind. When the store holds nothing at `swarm/agents/<agent>/backend-env` and `backendEnvironmentFile` is a non-empty file, it creates the leaf with the file's exact bytes and `-cas=0`, under the agent's own leaf, which may create that path and not update it. It never rotates a value and never rewrites or deletes the file. To set or replace a key, use **set the API-key environment** in the swarm UI (`PUT /api/hives/{hive}/agents/{agent}/backend-env`): `swarm-controller` overwrites the leaf with its own grant, and the store's value then wins over the file. Its **remove** (`DELETE` on the same path) deletes the leaf, and an agent whose file has content then creates it from that file again | the swarm secret store at that path; the unit writes it to `/run/hive-agent-backend-env/env` (tmpfs, `0600`, root), and `hive-agent` and `hive-subagent-daemon` load that after `backendEnvironmentFile` as `EnvironmentFile=` | the same unit, same path. A variable in the store wins over the same one in the file. With the store down at a start, the file alone carries the agent, as it did before the store held a copy; with an older hive build the agent ignores the leaf and keeps reading the file |
|
||||
| an agent's proxy settings (`HTTPS_PROXY`, `HTTP_PROXY`, `NO_PROXY`, the credential in the proxy URL) | `hive-agent-proxy-credential.service`, in the agent's container, as the agent user, at start and every 10 minutes: it reads `swarm/agents/<agent>/proxy-credential` under the agent's own leaf and builds the file from it. It writes nothing while the path holds nothing or the hive's facts name no squid | `/run/hive-agent-proxy-credential/proxy.env` (tmpfs, `0600`, the agent user); the harness, its bash tool, the subagents, the MCP servers and the pollers load it as `EnvironmentFile=-` and read it when they start | With no credential, or on a hive that writes no `HIVE_SQUID_PROXY` and `HIVE_EGRESS_NO_PROXY` fact, nothing writes the file and a unit has no proxy variable and reaches the internet without the proxy; the host still redirects the web traffic of a `restricted` or `log` agent into squid (see [the network reference](../networking/network.md#intercepted-web-traffic)). A failed read keeps the file already in place. A unit started before the file appeared goes direct until its next start. The credential is also in the environment of every process those units start, so `env` in the agent's shell prints it |
|
||||
| an agent's claude login (`.credentials.json`) | `swarm-claude-login.service`, in its container, when an operator completes `claude auth login` from the agent's card in the swarm UI; it stores the file as a new version at `swarm/agents/<agent>/claude-credentials` under its own leaf, which may create and update that path and read nothing under an agent | the swarm secret store at that path; the agent's `hive-agent` reads it under the agent's own leaf every 30 seconds while it waits for a login and writes it to `~/.claude/.credentials.json` | the same read, co-located or not; nothing for an operator to place beyond the agent's store leaf. When the store's copy and the agent's differ the KV version decides: the agent installs only a version newer than the last it installed (`claude-credentials-version` under the harness dir), because claude rotates the refresh token in its own copy and the stored one goes stale. The agent ignores a stale or equal version, and a relogin writes a newer one — [claude-login.md](../../2-handbook/swarm/claude-login.md) |
|
||||
| the queue responder's copy of its OIDC secret | the responder reads it out of the swarm secret store itself as it starts, under its own leaf, and again when authelia refuses it | the daemon's memory only; never on disk | same read, wherever authelia runs. Nothing for an operator to place beyond the responder's store leaf (`deploy.nats.authBaoClientCertFile`) |
|
||||
|
|
|
|||
|
|
@ -267,7 +267,8 @@ is a no-op without the other:
|
|||
- **`useApiKey`** tells the harness itself not to wait for a Claude OAuth
|
||||
session: at boot, `LoginState::from_dir` reports `Online` without
|
||||
checking `~/.claude/` (`hive_agent::login::using_api_key`, reads
|
||||
`HIVE_USE_API_KEY`), and the harness stamps the fact into the
|
||||
`HIVE_USE_API_KEY`, and counts an environment that holds `ANTHROPIC_API_KEY`
|
||||
or `ANTHROPIC_AUTH_TOKEN` too, see below), and the harness stamps the fact into the
|
||||
consolidated harness state file so the operator dashboard also stops reading this
|
||||
agent's empty `~/.claude/` as "needs login." An api-key agent that hits
|
||||
a real 401 (the key itself is bad) still surfaces `needs_login` — the
|
||||
|
|
@ -283,8 +284,8 @@ is a no-op without the other:
|
|||
(`hive-subagent-daemon`) loads the same file, so the agent's claude
|
||||
subagents run on the same key.
|
||||
|
||||
On an agent with a secret store (`services.hyperhive.agent.bao.addr`) that uses
|
||||
`useApiKey` or the `acp` runtime, `hive-agent-backend-env.service` also keeps the
|
||||
On an agent with a secret store (`services.hyperhive.agent.bao.addr`),
|
||||
`hive-agent-backend-env.service` also keeps the
|
||||
file's text in the store at `swarm/agents/<agent>/backend-env`, field `env`, and
|
||||
writes it to `/run/hive-agent-backend-env/env` every 2 minutes. When the store
|
||||
holds nothing there, the unit creates the leaf from `backendEnvironmentFile`,
|
||||
|
|
@ -295,7 +296,18 @@ the store down at a start the file alone carries the agent. Both read it at
|
|||
their own start, so a changed value reaches a running agent at its next
|
||||
restart.
|
||||
|
||||
To set or replace a key, use **set the API-key environment** on the agent in the swarm UI:
|
||||
An operator can also store the credentials apart from that text, at
|
||||
`swarm/agents/<agent>/backend-secrets`, field `env`, with
|
||||
`PUT /api/hives/{hive}/agents/{agent}/backend-secrets` (`GET` says whether the
|
||||
store holds any and never returns them; `DELETE` removes them). The unit writes them into the
|
||||
`/run` file after the text, so a secret wins over a variable of the same name, and
|
||||
removes the file when the store holds neither. An agent whose environment holds
|
||||
`ANTHROPIC_API_KEY` or `ANTHROPIC_AUTH_TOKEN` counts as an api-key agent even with
|
||||
`useApiKey` off, so it tries the key instead of waiting for a Claude login, and a
|
||||
real 401 still surfaces `needs_login`. `GET …/backend-env` reads the
|
||||
text back, so it holds configuration only.
|
||||
|
||||
To set or replace the whole environment text, use **set the API-key environment** on the agent in the swarm UI:
|
||||
it sends `PUT /api/hives/{hive}/agents/{agent}/backend-env` with the file text,
|
||||
which must be blank lines, `#` or `;` comments, and `NAME=VALUE` lines of at
|
||||
most 16 KiB. A save overwrites the stored text, including text the agent wrote
|
||||
|
|
|
|||
|
|
@ -1122,8 +1122,19 @@ a link dialog closes.
|
|||
stored text, including text the agent wrote into an empty leaf. The box is
|
||||
write-only and starts empty; **remove** sends the `DELETE` below. A
|
||||
swarm-controller without the route answers 404, and the dialog says so.
|
||||
`GET` on the same path reads the text back as stored, so keep credentials out
|
||||
of it and in the secrets below.
|
||||
What the agent does with it:
|
||||
[API-key provider](../turn-loop/config.md#api-key-provider-useapikey--backendenvironmentfile).
|
||||
- **set the secrets** — `PUT /api/hives/{hive}/agents/{agent}/backend-secrets`
|
||||
with the text of an `EnvironmentFile` (same shape and limit as the environment
|
||||
above), stored apart from it at `swarm/agents/<agent>/backend-secrets`. No route
|
||||
returns it: `GET` answers `{"stored": true|false}`, and `DELETE` removes it.
|
||||
The agent's `hive-agent-backend-env` unit writes the environment and then these
|
||||
secrets into the file the harness loads, so a secret wins over a variable of the
|
||||
same name, and an agent whose environment then holds `ANTHROPIC_API_KEY` tries
|
||||
the key instead of waiting for a Claude login. The harness reads the file at its
|
||||
start, so a change needs an agent restart.
|
||||
|
||||
#### Deleting a linked account
|
||||
|
||||
|
|
|
|||
Loading…
Reference in a new issue