Getting started

A local mesgd node gives your programs a shared place to exchange messages without tying each sender to a particular receiver. The initial setup has three parts: build and start the service, enroll an account, and connect a client using that account's credentials. Once that works, you can assign routing permissions and publish public keys for encrypted payloads.

Build and start the service

mesgd requires Erlang/OTP 25 or newer and beamer. From the mesgd source, run:

make
make keys
make start
./mesgd status

make builds mesgd and its dependencies, installs the Erlang code in ~/.beamer, and copies the account UI into ~/.beamer/mesgd-user-ui. make keys creates the service's signing and encryption identity in keys/mesgd.json, along with the administrator PKI identity in keys/admin.json. Both files contain private keys. The administrator key file is separate from an administrator account; possessing that file does not give a username administrative privileges.

Before starting, check the listener ports and certificate paths in mesgd.config. The local example uses port 4433 for HTTPS and WebSocket, port 5544 for the management console, and certificates under certs/. Configure clients to trust the issuing CA and verify the hostname they connect to. The current listener does not require client certificates, so supplying a CA file does not enable mutual TLS.

make start starts epmd and launches mesgd@localhost. The command and the node must use the same distribution cookie, read from MESGD_COOKIE_FILE or {cookie, Atom} in mesgd.config. A successful ./mesgd status prints ok, which means the command can reach the node. See Building and Configuration for the complete setup.

The examples below use ./mesgd from the source directory. If the launcher is on your PATH, you can use mesgd from elsewhere.

Enroll the administrator

The local configuration reserves admin@localhost as an administrator name. Create its account from the node:

./mesgd user add admin@localhost

The command generates a password, enrolls and confirms an authenticator, and writes four files in the current directory: the password, authenticator details, QR code, and recovery codes. It prints Enrolled followed by the file paths. The files are readable only by the operating-system account that ran the command.

Import the authenticator into your authenticator app and retain the recovery codes separately. Administrative privileges come from {admin, Name} and auth_admins in the configuration, rather than from the enrollment itself. Account administration describes the operations available to that account.

Create an application account

Use the same command with another email address to create an ordinary account:

./mesgd user add alice@example.com

This produces the same credential files without granting administrative privileges. Alternatively, open https://<host>:4433/account and complete signup in the browser. Public signup lets the person choose a password and confirm an authenticator before the account becomes active.

The account page handles login, sessions, and public keys. Configured administrators also see user administration and message access. The separate console listener provides statistics and a message-access form.

Connect a program

Log in through POST /auth/login with the username, password, and a fresh six-digit authenticator code. The response includes access_token, which you send as Authorization: Bearer TOKEN. Sessions last 24 hours by default; session_ttl changes that lifetime. POST /auth/refresh exchanges a live bearer for a new one and retires the previous bearer.

A login session is accepted for a WebSocket connection, but it carries no path restrictions. For a program that should operate within assigned routes, have an administrator create permissions and issue a grant token. Grant tokens last one hour and are checked against the user's current assignments.

Open the WebSocket on the main HTTPS port and send JSON text frames. Browser clients can offer ['json', token] as the subprotocol list because the browser WebSocket API cannot set an Authorization header. mesgd returns json as the selected protocol. WebSocket describes authentication and message delivery in detail.

Publish public signing and encryption JWKs with PUT /auth/keys, or include them at signup, when other programs need to verify signatures or encrypt payloads for this account. Private keys remain with the client. The SDK's authentication client wraps the common account calls; its PKI layer handles signing and encryption.

The SDK ping/pong samples send a sealed registration frame that the current mesgd listener does not process. Use the JSON connection format above for mesgd, and read Samples before treating those programs as an integration example.