Documentation

Quick Start

Five steps from a bare server to a terminal on your phone.

1. Get the app

Install Muxr on your phone or tablet.

Download on the App Store Get it on Google Play

2. Install the server

Run this on the machine whose sessions you want to reach:

curl -fsSL https://raw.githubusercontent.com/f0x-it-llc/muxr-core/main/install.sh | bash

It installs muxrd, the server, and muxrctl, its setup TUI.

Prerequisite: zellij 0.45.1 (muxrd refuses a mismatched version) or herdr on the server.

3. Reach it over a tailnet

  1. Install Tailscale on the server and on your phone.
  2. Sign both into the same tailnet (sudo tailscale up on a Linux server).
  3. Note the server's 100.x.y.z address: tailscale ip -4.
Device keys expire after 180 days

Disable key expiry for an always-on server in the Tailscale admin console, or it drops off the tailnet.

Using a LAN or a public domain instead? Follow Advanced setup for that step, then come back for step 4.

4. Run muxrctl

Run muxrctl on the server, over SSH if it is headless. The setup wizard opens on first run; press w on the dashboard to reopen it later.

muxrctl setup wizard, step 1 of 6: Welcome, listing the steps ahead and what it detected on this machine
1 · Press Next.
muxrctl setup wizard, step 2 of 6: Network, with the bind host and port fields and the reachable-address picker
2 · Pick your 100.x address from the list as the bind host and keep port 50051; the pairing code carries that address.
muxrctl setup wizard, step 3 of 6: Certificate, showing the self-signed certificate, its planned addresses and the advertised trust
3 · Keep the self-signed certificate.
muxrctl setup wizard, step 4 of 6: Pairing token, with the name field, the read-only checkbox and the expiry
4 · Name the token; tick Read-only for a view-only phone.
muxrctl setup wizard, step 5 of 6: Daemon, showing whether muxrd is running and on which address
5 · Start the daemon.
muxrctl setup wizard, step 6 of 6: Pair your phone, a pairing QR with the server address and certificate fingerprint beneath it
6 · Scan the code from the app (step 5), then press Done.

5. Scan the QR

  1. Open the Muxr app.
  2. Tap the QR scan button on the Connect screen.
  3. Point the camera at the code in muxrctl.

The token secret is shown once and kept only as a hash, so scan before you press Done; if you miss it, revoke the token and mint a new one.

Can't scan? On the Connect screen, enter the server address with its port (100.x.y.z:50051) and paste the token. Only the QR carries a self-signed certificate's fingerprint, so a manual connection to such a server needs Trust anyway, which is for development only.

Next: Using the app, or Advanced setup for the dashboard, the CLI, LAN, a public domain and the Docker rig.