mara/hyperhive
mara/hyperhive
Watch
0
0
Fork
You've already forked hyperhive
 0
Code Activity

docs: external forge and matrix accounts get pages in external-accounts

Browse source 
The directory covered GitHub and GitLab only; the forge and matrix account
kinds an operator can link were described under the swarm UI page. Two new
pages (forgejo.md, matrix.md) cover linking, what the agent gets and
deleting in operator terms, the directory README lists them, and the UI page
keeps a pointer for each kind.
This commit is contained in:
iris 2026-11-10 20:49:47 +01:00 • committed by mara
commit 7df6672c87
1 changed files with 108 additions and 28 deletions
Download patch file Download diff file Expand all files Collapse all files

36
docs/2-handbook/swarm/ui.md
View file

@ -912,24 +912,8 @@ The matrix `main` row is the agent's own account, which the swarm mints;
it carries an **own account** badge. The card requests the list again when
a link dialog closes.
- **link a matrix account** — `PUT /api/hives/{hive}/agents/{agent}/matrix-accounts/{account}`,
either a user id + password that swarm-controller logs in with, storing the
token it gets back, or a pasted bearer token. The form starts on the password
login: the account gets a device of its own, and the form notes that an
operator who also logs in to it appears to the agent as a second device. Choosing
**paste a token** shows a warning: a token from Element or another client
belongs to a device that's already logged in, so the agent can't use that
device's encryption keys and the account won't decrypt encrypted rooms.
- **link a forge account** — `PUT /api/hives/{hive}/agents/{agent}/forge-accounts/{label}`
with a forge URL and an access token, stored at
`swarm/agents/<agent>/forge/<label>`. The agent's
`hive-agent-forge-accounts` unit fetches it into
`<state>/forge-<label>-token` and `<state>/forge-<label>.json`, the files
`hive-forge -f <label>` reads. The unit rewrites a pair whenever the
store's account for its label differs, and never deletes one: a pair whose
label the store doesn't list stays untouched. swarm-controller answers 409
to a link for a label that already holds an account, so replacing one
takes a delete, then a new link.
- **link a matrix account**: see [Matrix accounts](../external-accounts/matrix.md).
- **link a forge account**: see [Forgejo accounts](../external-accounts/forgejo.md).
- **link a gitlab account** — `PUT /api/hives/{hive}/agents/{agent}/gitlab-accounts/{label}`
with a GitLab base URL and an access token, stored at
`swarm/agents/<agent>/gitlab/<label>`. Link it from the agent's **link account** menu. What the token needs and how the agent uses
@ -972,16 +956,12 @@ again after a delete, including a 404 one: the account being already gone is
the end state the delete wanted, so the dialog closes without an error.
The matrix confirmation has a checkbox, off by default, that logs the token
out at its homeserver first (`?revoke=true`). A 401 `M_UNKNOWN_TOKEN` from
that logout means the homeserver already doesn't recognise the token, so the
delete proceeds as if it had succeeded. Any other failed logout, or an account
with no homeserver stored, leaves the account in the store and the dialog
shows why. Deleting a forge account or GitHub token leaves the token valid at
its provider; revoke it there.
The agent isn't told about a delete. Its matrix daemon drops the account when
it next lists the store, within two minutes. Its forge and GitHub units never
delete a file, so a token already fetched into `<state>` stays there.
out at its homeserver first (`?revoke=true`); what that and the agent do
after a delete is in [Matrix accounts](../external-accounts/matrix.md#deleting-an-account).
Deleting a forge account or GitHub token leaves the token valid at its
provider; revoke it there. The agent isn't told about a delete. Its forge and
GitHub units never delete a file, so a token already fetched into `<state>`
stays there.
Where each credential lives and who reads it:
[`credentials-reference.md`](credentials-reference.md).