Remote Access

Not a collaboration tool

Remote access is for accessing your own machine from your other devices. It is not intended for sharing sessions with other people. Every connected user gets full, unrestricted shell access. See Security for the full threat model.

By default, gmux only listens on localhost. To access it from another device, you can enable the built-in Tailscale listener. Tailscale creates an encrypted private network between your devices without opening ports or configuring firewalls.

Setup

The fastest path: run gmuxd remote and follow the prompts. It handles configuration, walks you through Tailscale registration, and verifies the result. You can run it again at any time to check the status.

The steps below cover the same process in detail.

1. Set up Tailscale

If you haven’t used Tailscale before:

1. Create an account (free for personal use, up to 100 devices).
2. Install Tailscale on the machine running gmux and on the device you want to connect from.
3. Sign in on both devices with the same account.

If you already use Tailscale, just make sure both devices are on the same tailnet.

2. Enable HTTPS and MagicDNS

In the Tailscale admin console:

1. Enable MagicDNS so devices can find each other by name.
2. Enable HTTPS Certificates so Tailscale can issue valid TLS certificates for *.ts.net hostnames.

Both are required. You can verify they’re enabled by running gmuxd remote after setup.

3. Enable and register

gmuxd remote

This walks you through the process interactively: it explains what remote access does, asks for confirmation, enables Tailscale in ~/.config/gmux/host.toml, restarts the daemon, and waits for Tailscale to connect.

On first setup, Tailscale needs you to log in:

Enable remote access? [y/N] y

Enabled tailscale in /home/user/.config/gmux/host.toml
Restarting daemon...
gmuxd: running (pid 12345)
  Logs: /home/user/.local/state/gmux/gmuxd.log

Connecting to Tailscale...

To complete setup, log in to Tailscale:
  https://login.tailscale.com/a/...

After logging in, run `gmuxd remote` again to check the connection.

Visit the URL to approve the device. gmux registers as its own device in your tailnet, separate from the machine’s Tailscale. After login, run gmuxd remote again:

$ gmuxd remote
Connecting to Tailscale...
  local:  http://127.0.0.1:8790
  remote: https://gmux.your-tailnet.ts.net

Remote access is active.

You can also edit host.toml manually instead:

[tailscale]
enabled = true

See host.toml reference for all fields (hostname, allow list).

Multiple machines

Each machine on the same tailnet needs a unique hostname. Set it in host.toml:

[tailscale]
enabled = true
hostname = "gmux-desktop"

This gives you https://gmux-desktop.your-tailnet.ts.net.

4. Connect

On your other device, open https://gmux.your-tailnet.ts.net. The connection is HTTPS with a valid certificate.

Note

The Tailscale listener is independent from the localhost listener. Local access (127.0.0.1:8790) always works, so you can’t lock yourself out by misconfiguring Tailscale.

Sharing access

Every connection is verified by Tailscale’s cryptographic identity and checked against an allow list. Your primary account is allowed automatically. See Security for the full verification design.

Adding your other accounts

If you use multiple Tailscale accounts (e.g. personal and work), add them to the allow list so you can connect from either:

[tailscale]
enabled = true
allow = ["your-work-account@github"]

Then restart: gmuxd restart.

If the other account is on a different tailnet, you also need to share the gmux device via the Machines page (⋯ → Share). The device is then accessible at gmux.owner-tailnet.ts.net (using the owner’s tailnet name).

Troubleshooting

Run gmuxd remote to diagnose most issues. It checks whether the daemon is running, whether the device is registered, and whether HTTPS and MagicDNS are enabled.

ERR_NAME_NOT_RESOLVED in the browser: the device isn’t registered, or MagicDNS is disabled. Run gmuxd remote to check.

gmux doesn’t appear in the Tailscale dashboard: gmux registers as its own device, not through the machine’s Tailscale. Check the daemon log for the login URL: cat $(gmuxd log-path) | grep tsauth. You can also run gmuxd run in foreground mode to see the URL directly.

Certificate warning: HTTPS certificates aren’t enabled in your tailnet. Enable them in your Tailscale DNS settings, then restart gmuxd.

Certificate error when accessing a shared machine: Tailscale issues certificates for the active tailnet DNS name only. If the owner renamed their tailnet after issuing certificates, the guest may see a mismatch. Check that the active name in DNS settings matches what gmuxd remote shows.

Can’t reach from a specific device: make sure Tailscale is installed, signed in, and connected on that device.