Matrix plugin¶

wsctl matrix deploys a private Matrix chat server (tuwunel) into your Waveshift deployment and manages its users and sign-up tokens.

The server is private: it is reachable only inside the VPC (through the Waveshift VPN) or through wsctl matrix proxy, it does not federate with other Matrix servers, and nobody can register without a token.

Read Plugins first for installation and prerequisites.

Quick start¶

wsctl matrix deploy                    # takes a few minutes to install and start
wsctl matrix logs                      # install progress, then the server's own output
wsctl matrix status

wsctl matrix user add alice            # prints alice's generated password
wsctl matrix token create              # a one-use, 7-day sign-up token

wsctl matrix destroy --yes             # deletes all chat data

Connecting a client¶

People sign in with any Matrix client, such as Element (desktop, mobile or web), using:

Homeserver: https://matrix.<domain>, for example https://matrix.waveshift.internal
User ID: @alice:matrix.waveshift.internal, or just alice in most clients

The device must be on the Waveshift VPN and must trust the Waveshift CA (wsctl cert export), because the server's certificate is issued by it.

From a machine outside the VPN, wsctl matrix proxy forwards https://localhost:8448 to the server.

There is no web page at the server address

The server provides the Matrix service only. Opening its address in a browser shows a short greeting, not a chat interface: use a Matrix client.

Commands¶

Every command takes --help.

Lifecycle¶

Command	Notes
`wsctl matrix deploy`	`--version` (default `v1.9.4`), `--instance-type` (default `t4g.small`), `--server-name` (default `matrix.<domain>`). Version and instance type fall back to the previous deploy's values.
`wsctl matrix destroy --yes`	Terminates the server and removes its DNS record, IAM role, certificate and admin password. All chat history, users and rooms are deleted.
`wsctl matrix status`	Reads `wsctl.json` only; makes no AWS calls.
`wsctl matrix proxy`	`--local-port` (default 8448), `--remote-port` (default 443)
`wsctl matrix connect`	Shell on the server host; `--root` for root.
`wsctl matrix logs`	`--tail N` (default 100), `-f` to follow. Shows the install log until the server starts.

Users: `wsctl matrix user <action>`¶

Action	Notes
`add [--admin] <name>`	Creates the user with a generated password, shown once.
`list`	All users, with admin and deactivated status.
`reset-password <name>`	Sets a new generated password and signs out all of the user's sessions.
`deactivate [--erase] <name>`	Permanent. `--erase` also erases their profile and messages. The account `wsctl` manages the server with cannot be deactivated.

Names are lowercase letters, digits and . _ = -.

Sign-up tokens: `wsctl matrix token <action>`¶

Action	Notes
`create [--uses N] [--expires D]`	Default one use and 7 days. `--uses 0` for unlimited; `--expires` takes `7d`, `12h` or `never`.
`list`	Tokens with uses (`completed/allowed`) and expiry.
`delete <token>`

A person signs up by choosing "Create account" on the homeserver in their client and entering the token.

How it works¶

Server: tuwunel's official arm64 image in Docker on Amazon Linux 2023. It serves HTTPS on port 443 itself, with a certificate issued by the Waveshift CA.
No federation. The server does not talk to other Matrix servers.
Registration needs a token. Tokens from wsctl matrix token create have their own use limits and expiry.
Admin account: created when the server first starts, before anyone could register. Admin commands run on the server through SSM.
Secrets: the admin password and the server's TLS key are kept in SSM Parameter Store as encrypted parameters; nothing secret is in the instance's start-up data.

Configuration¶

State lives in wsctl.json under plugins.matrix:

Field	Set by	Cleared by destroy
`version`, `instance_type`, `admin_user`	`deploy`	No
`instance_id`, `private_ip`, `server_name`, `admin_password`, `deployed_at`	`deploy`	Yes

Troubleshooting¶

Symptom	Cause
`unknown command "matrix" for "wsctl"`	`wsctl` predates plugin support, or `wsctl-matrix` is not on your `PATH`.
`admin login failed: ...`	The text after the colon is the server's own error. With no response, the server is still installing or has failed: check `wsctl matrix logs`.
`admin login failed: M_LIMIT_EXCEEDED`	The server's per-account login rate limit. Wait a few minutes; repeated attempts extend the wait.
`logs` shows `[ERROR] Matrix setup failed at line N`	First-boot setup stopped. The lines above it show which step.
A client says the certificate is untrusted	The device does not trust the Waveshift CA. Install it with `wsctl cert export`.
A client cannot reach the homeserver	The device is not on the Waveshift VPN. From a workstation, use `wsctl matrix proxy`.

Limitations¶

Data does not survive destroy. The database is on the server's disk.
Private only. No federation and no public endpoint.
Certificate lifetime: the server certificate is valid for one year. Redeploying issues a new one.