# Quick start: install muxrd and pair your phone

> Install the muxrd server, run the setup wizard and pair the Muxr app on your phone by scanning a QR code, in five short steps.

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

# 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](https://muxr.app/assets/img/badges/app-store.svg)](https://apps.apple.com/app/muxr-zellij-herdr-client/id6815185967) [![Get it on Google Play](https://muxr.app/assets/img/badges/google-play.png)](https://play.google.com/store/apps/details?id=com.it.f0x.muxr)

## 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](https://tailscale.com/download) 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](https://muxr.app/advanced.html#lan) or a [public domain](https://muxr.app/advanced.html#public) 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](https://muxr.app/assets/img/screenshots/wizard-1-welcome.webp)

1 · Press Next.

![muxrctl setup wizard, step 2 of 6: Network, with the bind host and port fields and the reachable-address picker](https://muxr.app/assets/img/screenshots/wizard-2-network.webp)

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](https://muxr.app/assets/img/screenshots/wizard-3-certificate.webp)

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](https://muxr.app/assets/img/screenshots/wizard-4-token.webp)

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](https://muxr.app/assets/img/screenshots/wizard-5-daemon.webp)

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](https://muxr.app/assets/img/screenshots/wizard-6-pair.webp)

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](https://muxr.app/guide.html), or [Advanced setup](https://muxr.app/advanced.html) for the dashboard, the CLI, LAN, a public domain and the Docker rig.
