Documentation

Advanced Setup

Everything off the quick start path: the dashboard, the command line, LAN, a public domain and the Docker rig.

The muxrctl dashboard

Once set up, muxrctl opens on the dashboard: five panels for the daemon, network, certificate, tokens and devices. Each key opens a dialog; Esc closes it.

The muxrctl dashboard: Daemon, Network, Certificate, Tokens and Devices panels above a row of buttons and their keys
Press a key from the bottom row to open its dialog.
KeyAction
sstart or stop the daemon
cbind host and port
ecertificate: mode, fingerprint, SANs, advertised trust, regenerate
ttokens: create, show pairing QR, revoke
ddevices registered for push notifications
wreopen the setup wizard
rrefresh
qquit

The CLI route

Every wizard step is a muxrd subcommand, for scripted installs. Replace 100.x.y.z with your server's address.

Create the data directory (~/.local/share/zellij/muxrd/ on Linux) and a self-signed certificate for that address (--san is repeatable; MUXRD_SAN takes a comma-separated list):

muxrd init --san 100.x.y.z

Start the daemon, detached (MUXRD_BIND also sets the address; the default, 127.0.0.1:50051, is unreachable from a phone):

muxrd start --bind 100.x.y.z:50051 --daemonize

Mint a token, a view-only token, and one that stops pairing new devices after 24 hours (--expires-in takes 30m, 24h, 7d or never, the default):

muxrd create-token --name mobile
muxrd create-token --name viewer --read-only
muxrd create-token --name guest --expires-in 24h

Manage them, and the daemon:

muxrd list-tokens
muxrd revoke-token guest
muxrd status
muxrd stop
Secret shown once

A token's secret is printed only at creation and stored only as a hash, so neither it nor its pairing QR can be shown again; if you lose it, revoke the token and mint a new one. Pair a CLI-minted token by hand: enter the host and paste the secret on the app's Connect screen.

LAN instead of a tailnet

Bind a LAN address and list it in the certificate, or TLS verification fails:

muxrd init --san 192.168.0.42
muxrd start --bind 192.168.0.42:50051

--bind 0.0.0.0:50051 listens on every interface and lets the QR advertise a real address; on a host with a public interface that also exposes the port, so firewall it.

Changing the SANs means a new certificate: rerun muxrd init with the new --san or regenerate from the dashboard (e), restart the daemon, and re-pair every phone.

A LAN address only works on that LAN; a tailnet follows the phone onto mobile data.

Public domain — least recommended

A public domain puts muxrd on the open internet: anyone with your DNS name and a token can reach it. It suits only something you would be comfortable making public, like the read-only demo at demo.muxr.app; for your own machine use a tailnet.

Read this before you expose muxrd

A public listener changes the threat model.

  • Every host on the internet can reach the login endpoint; the bearer token is the only barrier. muxrd revoke-token <name> is the kill switch: it invalidates the token and every live session minted from it.
  • muxrd has no per-login session isolation: everyone presenting the same token attaches to the same session and sees the same activity.
  • Whatever terminates TLS in front of muxrd sees your terminal traffic and bearer tokens in plaintext.
  • Edge proxies commonly drop idle connections after a minute or two, so a viewer parked on a silent pane can be cut off.

Behind a TLS-terminating reverse proxy

The proxy owns the public certificate, terminates TLS, and proxies gRPC over HTTP/2 to muxrd as plaintext h2c. muxrd listens only on a private address the proxy can reach; never publish that port.

muxrd start --bind <private-address>:50051 --insecure-h2c --i-know-this-is-behind-a-proxy

muxrd refuses a non-loopback h2c bind without the second flag, because the proxy-to-muxrd hop is plaintext. The phone dials your.host:443 and the QR carries tm=ca. A self-signed muxrd behind such a proxy needs Advertised trust set to CA in the certificate dialog.

Serve your own certificate

Point muxrd at a publicly trusted certificate for your DNS name, with no proxy in front:

muxrd init --tls-cert /path/fullchain.pem --tls-key /path/privkey.pem
muxrd start --bind 0.0.0.0:50051 --tls-cert /path/fullchain.pem --tls-key /path/privkey.pem

The phone dials your.host:50051; type the port, because a bare host defaults to 443 under Public domain (CA). Restart muxrd after every renewal. A self-signed certificate with --san your.host also works: the QR then pins the fingerprint, but the host is exposed the same way.

Environment variables and mode precedence: see the README.

Harden it like the demo

  • Firewall to 22, 80 and 443 behind a proxy, or 50051 alone for a direct certificate.
  • Run muxrd as an unprivileged user in a container with a read-only root filesystem, no Linux capabilities and resource limits; the demo's compose files are the template.
  • Mint read-only tokens for anyone you do not fully trust.
  • Keep muxrd revoke-token at hand.
  • Test the long-lived attach through your proxy on a real device before publishing a QR.

Docker dev rig

The repository's Compose rig builds and runs muxrd in a container, with no local Rust toolchain or zellij needed. From a clone of muxr-core:

docker compose -f docker/compose.yaml up --build

Set BIND_ADDR to publish on a tailnet or LAN address; the rig adds it to the certificate's SANs, and it also publishes the rig's passwordless SSH port (2222) there:

BIND_ADDR=100.x.y.z docker compose -f docker/compose.yaml up --build

Reset all container state, volumes included:

docker compose -f docker/compose.yaml down -v
Dev-only — never expose on an untrusted network

The rig uses passwordless SSH and self-signed certificates. Do not expose it on the public internet or any untrusted network.

Profiles and options: see the README.