60 lines
3.1 KiB
Markdown
60 lines
3.1 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](../../4-implementation/web-ui/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 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.
|