> ## Documentation Index
> Fetch the complete documentation index at: https://rakumux.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Phone access

> Use your sessions from the Rakumux phone app, over your own Tailscale network.

The Rakumux app shows your sessions on a phone and types into them. It connects directly to the
machine running your sessions over [Tailscale](https://tailscale.com), not through any Rakumux
server. Phone access is **off** until you turn it on, and then only devices on your tailnet that
have the pairing token get in.

> [!TIP]
>
> Without Tailscale or the app, [rakumux.com](https://rakumux.com/docs/account/feed.md#your-sessions-on-the-web) shows your
> sessions, their chats and the Feed in your phone's browser, and lets you write back to your agents.
> In a phone's terminal over SSH, Rakumux itself shows one thing at a time; see
> [Layouts](https://rakumux.com/docs/guides/layouts.md#phones).

## Turn it on and pair

**1. Install Tailscale**

Install Tailscale on the machine running Rakumux and on your phone, signed in to the same
tailnet.

**2. Turn on phone access**

```bash theme={null}
rakumux remote on
```

The first time Rakumux sees Tailscale running, it also offers this once in the UI (**Use Rakumux
from your phone?**). It stays on until you turn it off.

**3. Pair the app**

`rakumux remote on` prints the URL, the pairing token, a `rakumux://connect` link and, on a
terminal, a QR code. Scan the QR code with the app, or tap the link on the phone. Show them again
any time:

```bash theme={null}
rakumux remote pair
```

## Manage it

| Command | Does |
| - | - |
| `rakumux remote on [--port N]` | Turn phone access on (port 7337 by default) and print the pairing details |
| `rakumux remote pair` | Show the URL, token, link and QR code again |
| `rakumux remote status [--json]` | Whether it's on, the URLs it listens on, and the start of the token |
| `rakumux remote token [--rotate]` | Print the token; `--rotate` makes a new one (re-pair the app) |
| `rakumux remote off` | Turn phone access off |

## Security

* **Where it listens.** Only on the machine's Tailscale addresses, never on your local network or
  the internet. Addresses that merely look like Tailscale's (some ISPs and VPNs use the same range)
  are never used.
* **Who gets in.** Every request needs the pairing token. A paired phone acts as **you**: it can do
  what the UI does, including typing into any session.
* **Keep the token secret.** Anyone on your tailnet with it can run commands as you. If a phone is
  lost, run `rakumux remote token --rotate`: the old token stops working at once.
* **Encryption.** Traffic over Tailscale is encrypted by WireGuard, so plain `http://` to a Tailscale
  address stays private to your tailnet.

## HTTPS with `tailscale serve`

For a real certificate (`https://<machine>.<tailnet>.ts.net`), let Tailscale terminate TLS. Enable
HTTPS certificates for your tailnet in the Tailscale admin console first, then:

```bash theme={null}
rakumux remote on
tailscale serve --bg --https=443 http://<tailscale-ip>:7337
```

Use `https://<machine>.<tailnet>.ts.net` and the same token in the app. If `tailscale serve`
refuses a Tailscale IP as its target, bind the remote listener on loopback instead: add
`"listen": ["127.0.0.1:7337"]` to `~/.rakumux/remote.json`, run `rakumux remote on`, and proxy
`http://127.0.0.1:7337`. `tailscale serve reset` undoes it.

> [!WARNING]
>
> Use `tailscale serve`, never `tailscale funnel`: `funnel` publishes the port on the public
> internet.

The technical details (how the remote listener differs from the local API, `remote.json`) are in
the [API reference](https://rakumux.com/docs/api-reference/introduction.md#remote-access).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.