3.1 KiB
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 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 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 checkbox also decides what happens to the account's key-backup passphrase, the secret its end-to-end key backup opens with. With it off, the passphrase stays, so linking the same account again finds the passphrase the backup used and the agent can recover its keys. With it on, the controller deletes the passphrase after the account, and a later link gets a new one, which can't open a backup made with the old one. Tick it when you've lost the account for good. If the controller can't delete the passphrase, the account is already gone and the dialog says so; deleting the account again with the box ticked finishes the job.
The agent isn't told about a delete. Its matrix daemon drops the account the next time it lists the accounts, within two minutes.