Support

Contact us

Found a bug in the server, muxrctl, or the wider open-source muxr-core project? File it on GitHub Issues — that's the fastest way to get eyes on a reproducible server-side problem, and lets other self-hosters find it too.

Quick links

• Getting Started — install muxrd, mint a token, and pair your device via QR.
• Usage Guide — gestures, the command center, keyboard bar, and read-only mode.
• muxr-core README — the open-source server repository on GitHub.

FAQ

Pairing fails, or the QR code won't scan

• Confirm muxrd is actually running — check with muxrd status, or start it with muxrd start.
• Make sure the phone can reach the server — over your tailnet (see Reach it over Tailscale), or, if you chose the LAN route, on the same Wi-Fi (see LAN instead of a tailnet).
• Check that the token hasn't been revoked — run muxrd list-tokens on the server to confirm it still exists.
• QR codes are shown once, right when a token is minted — muxrctl stores only a hash of the secret, so the code cannot be shown again for a token you have already dismissed (see token secrets can't be retrieved after creation). If you missed the scan: in muxrctl press t, choose Revoke… on that token, then Create… a new one and press Show pairing QR on the minted-secret dialog; or run the setup wizard again (w) and scan at its last step.
• If the camera won't focus or read the code, try the manual fallback — entering the server URL and token by hand on the Connect screen.

"TLS fingerprint mismatch"

When you pair by QR against a self-signed server, the app pins trust to that exact certificate's SHA-256 fingerprint. This error means the fingerprint the app has stored no longer matches what the server presents — almost always because the server's self-signed certificate was regenerated (for example, after running muxrd init again to add a LAN SAN).

Connection refused, or the connection times out

• muxrd binds 127.0.0.1:50051 by default, which only accepts connections from the same machine. To reach it from a phone or tablet, start it with a LAN bind address (muxrd start --bind 0.0.0.0:50051) and add that address as a certificate SAN — see LAN instead of a tailnet.
• Confirm the server is listening on port 50051 (or whatever port you configured) and that the address you entered in the app matches it exactly.
• Check your firewall — both the host OS firewall and any router-level rules — allows inbound connections to that port from your phone's network.

My read-only token can't modify sessions

This is by design. Mutating RPCs — creating, renaming, or closing sessions, tabs, and panes, and server-side pane fullscreen — fail closed on read-only tokens; the app also hides those affordances entirely when connected read-only. If you need to make changes, mint a read-write token instead: muxrd create-token --name mobile (omit --read-only).

Push notifications aren't arriving

Notifications are an optional feature, and only arrive once your device is registered with a relay — device registration is a capability arriving with app-side push support. Whether push is available at all is decided by your server, and the app learns it from the server — there is no app-side relay setting. Things to check, in order:

• Your server runs the herdr backend. Push requires herdr's event kernel — a zellij-only muxrd refuses device registration and reports push as unsupported.
• Your server has a relay configured. muxrd's notify_relay_url setting (or the MUXRD_NOTIFY_RELAY_URL environment variable) points at the hosted Muxr Push relay by default; setting it empty disables push entirely.
• Your server can reach the relay. Notifications are sent by muxrd to the relay — not by your phone — so check the server's network and firewall if sends fail. Your phone only contacts the relay once, at registration time. If you're self-hosting muxr-notify, confirm it is running and reachable from the server.
• The hosted relay currently supports Android devices only (see the Privacy Policy). It is what a Muxr Push subscription pays for; a self-hosted relay is free and needs no subscription.

See the Privacy Policy's Muxr Push section for what a notification does and doesn't contain.

Before you write in

These three things let us diagnose most issues on the first reply:

• App version — found in the app's Settings screen.
• Server version — run muxrd --version, or check the Connection info panel in the app's Settings, which shows the connected server's version.
• A relevant muxrd log snippet — copy the lines around when the problem occurred. If you ran the server in the foreground with muxrd start, this is in your terminal; as a daemon, check muxrd status for the log location. Skim the snippet before sending and redact anything sensitive — hostnames, tokens, or session content.

Questions about data instead of a technical issue? See the Privacy Policy and the Terms of Use.