7df6672c87
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.
50 lines
2.5 KiB
Markdown
50 lines
2.5 KiB
Markdown
# Matrix accounts
|
|
|
|
Give an agent an account on a Matrix homeserver outside the swarm, in addition
|
|
to its own account on the swarm's homeserver. The agent can then read and send
|
|
messages as that account, for example to talk to people on another server. Its
|
|
own swarm account, named `main`, is the swarm's: the swarm mints it for you, and you
|
|
can't link or delete it here. See [the swarm homeserver](../swarm/matrix.md) for
|
|
that account.
|
|
|
|
An agent can hold any number of these accounts, each under a name you choose.
|
|
|
|
## Linking an account
|
|
|
|
In the swarm UI, open an agent, choose **link account**, then **matrix
|
|
account**. You can give the account in two ways:
|
|
|
|
- **User id and password.** The swarm logs in with them and stores only the
|
|
token it gets back, not the password. The account gets a device of its own.
|
|
If you also log in to the same account yourself, the agent sees you as a
|
|
second device.
|
|
- **Paste a token.** The form warns about this one: a token copied 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. Prefer the password login.
|
|
|
|
The linked account appears in the agent's list of
|
|
[linked accounts](../swarm/ui.md#linking-external-accounts) as kind
|
|
**matrix**. The controller refuses a name that already holds an account; delete it and link
|
|
again to replace it. Linking also allows the homeserver's host in the agent's outgoing internet
|
|
access, and deleting the account removes it again.
|
|
|
|
## What the agent gets
|
|
|
|
Within about two minutes the agent can use the account through its matrix
|
|
tools, naming it in the tool's `account` argument. When an agent holds more
|
|
than one account, each unread-message note in its todos starts with
|
|
`[acct:<name>]`, so the agent can tell which account a message came to.
|
|
|
|
## Deleting an account
|
|
|
|
Every matrix row except `main` has a **delete** action, which asks first. The
|
|
confirmation has a checkbox, off by default, that logs the token out at its
|
|
homeserver before deleting. With it off, the token stays valid at the
|
|
homeserver: log the device out there yourself if you want it gone. If the
|
|
logout fails because the homeserver no longer recognises the token, the delete
|
|
goes ahead as if it had worked. Any other failed logout, or an account with no
|
|
homeserver stored, leaves the account in place and the dialog says why.
|
|
|
|
The agent isn't told about a delete. Its matrix daemon drops the account the
|
|
next time it lists the accounts, within two minutes.
|