# Advanced setup: LAN, public domain, CLI and Docker

> Set up Muxr beyond the basics: the muxrctl dashboard, the muxrd command line, LAN and public-domain access, and the Docker dev rig.

Source: https://muxr.app/advanced.html

# Advanced Setup

Everything off the [quick start](https://muxr.app/docs.html) 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](https://muxr.app/assets/img/screenshots/dashboard.webp)

Press a key from the bottom row to open its dialog.

| Key | Action |
|---|---|
| `s` | start or stop the daemon |
| `c` | bind host and port |
| `e` | certificate: mode, fingerprint, SANs, advertised trust, regenerate |
| `t` | tokens: create, show pairing QR, revoke |
| `d` | devices registered for push notifications |
| `w` | reopen the setup wizard |
| `r` | refresh |
| `q` | quit |

## 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](https://demo.muxr.app); for your own machine use a [tailnet](https://muxr.app/docs.html#tailscale).

> **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](https://github.com/f0x-it-llc/muxr-core#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](https://github.com/f0x-it-llc/muxr-core/tree/main/demo) 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](https://github.com/f0x-it-llc/muxr-core#readme).
