# Tailscale and Remote VMs

<a id="two-pieces"></a>

The host is the machine that owns the repos and runs the agents, with its own shell, git config and credentials. Your laptop, phone or [runpane.com/app](https://runpane.com/app/) only shows its [panes](/docs/panes-and-worktrees). This setup is called Remote Pane. It's free and open source, and nothing on these paths goes through Pane's servers.

> **Note:** **Just want Pane on your phone or another computer?** [Scan a QR code](/docs/phone). It works on any network with no Tailscale, no code and no port forwarding.

| You have | Use |
|---|---|
| Tailscale on every computer | [Connect your own computers over Tailscale](#connect-your-own-computers-over-tailscale) |
| A VM or server with no desktop | [Set up a headless VM or server](#set-up-a-headless-vm-or-server) |
| A browser, or a device on another account | [Connection codes](#connection-codes-for-browsers-and-other-accounts) |
| Another VPN, SSH or your own HTTPS proxy | [Fallbacks](#fallbacks) |

Comparing Pane with SSH clients or remote desktop? See [Remote access](/remote).

<div style={{ margin: "2rem 0" }}>
  <RemotePanePreview />
</div>

## Connect your own computers over Tailscale

1. Install Tailscale and sign in with the same login on both computers. If your tailnet has HTTPS certificates turned off, turn them on in [Tailscale DNS settings](https://login.tailscale.com/admin/dns).
2. Open Pane on both.
3. Open **Settings → Remote Access → Computers**, or the machine menu at the top of the sidebar. Every computer on your tailnet that runs Pane is listed.
4. Click **Switch** next to the other computer. If it has a password, enter it when asked.
5. To come back, pick **This computer** in the machine menu at the top of the sidebar.

A saved connection belongs to the tailnet you saved it on. After switching tailnets, connect again from **Computers**. Pane won't send a saved password to a same-named machine on another tailnet. A computer you also [linked another way](/docs/your-computers) or over [SSH](/docs/remote-pane-ssh) shows once, with a pill for each route. If the route in use fails, Pane uses another without closing your panes.

### Who can connect over Tailscale

On the host, open **Settings → Remote Access → Tailscale → Who can connect**.

| Setting | Who gets in |
|---|---|
| **Off** | No one over Tailscale. Same as `runpane workspace disable`. Phones paired with a QR code and connection codes still work. |
| **Only me** (default) | Devices signed in with your Tailscale login. |
| **Everyone on tailnet** | People with untagged devices on this tailnet. Devices shared from another tailnet aren't included. Pane warns that they could run agents and commands here, and asks you to click **Allow Everyone**. |

**Password** is off by default. With **Set Password**, every Tailscale client must enter it, your own computers included. The host stores only a hash, and only someone at the host can change these settings. To reach a password-protected machine from the [`runpane workspace`](/docs/runpane-workspaces) CLI or [Handoff](/docs/runpane-handoff), connect to it once from **Computers** and enter the password.

## Connection codes for browsers and other accounts

<a id="security"></a>

A connection code is a `pane-remote://...` string with the host's address and a token for one client. It works in desktop Pane, the [Pane phone app](/docs/phone#ios-app-beta) and runpane.com/app, and it's the only way into a host with no desktop.

> **Warning:** A code holds a bearer token that controls the host. Treat it like a password.

<a id="host-data-modes"></a>

<a id="current-pane-data"></a>

<a id="isolated-daemon-data"></a>

### Choose a data mode

| Data mode | What clients see | Use it for |
|---|---|---|
| **Current Pane Data** | The projects, sessions and settings of the Pane app open on the host, while it's open. | A desktop, laptop or WSL machine you keep running |
| **Isolated Daemon Data** | A separate data directory (`~/.pane_remote`), run by a background service where the OS supports it. Headless setup always uses this. | A VM, server or always-on host |

### Create a code on a computer with desktop Pane

Codes for every connection type, SSH and Manual HTTPS included, are made and pasted under **Settings → Remote Access → Tailscale**.

1. On the host, click **Set Up Host** under **Hosts and connection codes**.
2. Under **Data**, choose a data mode. Change **This Machine Label** if you like.
3. Choose **Tailscale**, or a [fallback](#fallbacks): **SSH Tunnel** or **Manual HTTPS**.
4. Click **Create Connection Code**, or **Open Guided Setup** for a terminal that installs Tailscale, signs you in, sets up Tailscale Serve and makes the code.
5. Click the code to copy it.

**Advanced**, next to **Set Up Host**, has listener settings and manual pairing.

<a id="phone-and-browser-access-with-a-code"></a>

### Paste the code on the client

| Client | Steps |
|---|---|
| Desktop Pane | **Settings → Remote Access → Tailscale → Paste a connection code**, paste it into **Connection Code**, click **Connect**. The host joins **Computers** and the machine menu. |
| Browser or phone | Open [runpane.com/app](https://runpane.com/app/), paste the code, tap **Import & Connect**. If the code uses a Tailscale address, the device needs Tailscale on the same tailnet. |

If the host can't be reached, desktop Pane still saves it and shows a checklist of the connection's steps. The first failed step says how to fix it, such as **Open Tailscale Setup**.

<a id="install-the-browser-app"></a>

The browser app is a <Term id="pwa">PWA</Term> with fewer panel types than desktop Pane. A phone can't use an SSH tunnel running on your laptop, so use Tailscale or Manual HTTPS for phones.

<Toggle title="Install the browser app">

On iPhone or iPad: open `https://runpane.com/app/` in Safari, tap Share, then **Add to Home Screen**.

On Android: open `https://runpane.com/app/` in Chrome, open the browser menu, then tap **Add to Home screen** or **Install app**.

On desktop Chrome or Edge: open `https://runpane.com/app/`, then click the install icon in the address bar or choose **Install app** in the browser menu.

On desktop Safari: open `https://runpane.com/app/`, then choose **File → Add to Dock**.

Open **Remote Pane** from the home screen, launcher or Dock and paste your code.

</Toggle>

When the host stops or reboots, its running agents stop and its files stay. See [What is session persistence?](/what-is-session-persistence)

<a id="headless-vm-or-server-setup"></a>

## Set up a headless VM or server

A headless host has no Settings screen, so you set it up from its terminal. [Run Pane on a Cloud VM](/docs/cloud-workspaces) walks through a full VM.

1. <a id="host-credentials"></a>Install `git` and your agent CLIs on the host, like `claude` or `codex`, and sign in to each there. For keys, see [AI providers](/docs/providers).
2. For `npx` or `pnpm`, install Node.js 22.23.4+ (22.x), 24.22.1+ (24.x) or 26.12.1+ (26.x). `pipx` needs Python instead.
3. Run the guided setup and choose **Set up a remote host**:

   <RemotePackageInstall />

4. Copy the code it prints and [paste it on the client](#paste-the-code-on-the-client).

Setup installs Pane if it's missing, writes its config to `~/.pane_remote`, installs a background service where it can, and sets up Tailscale Serve.

<Toggle title="Other ways to run setup">

Skip the wizard, for scripts:

```bash
npx --yes runpane@latest install daemon --label "My Server"
pnpm dlx runpane@latest install daemon --label "My Server"
pipx run runpane install daemon --label "My Server"
```

SSH tunnel mode:

```bash
npx --yes runpane@latest install daemon --label "GPU VM" --prefer-tunnel ssh
```

See what setup would do first:

```bash
npx --yes runpane@latest install daemon --label "GPU VM" --dry-run --verbose
```

Pane is already installed on the host:

```bash
pane --remote-setup --label "My Server"
pane --remote-setup --label "GPU VM" --prefer-tunnel ssh
```

From a Pane source checkout:

```bash
pnpm remote:setup -- --label "My Server"
```

Shell installer, for a nightly build:

```bash
curl -fsSL https://runpane.com/install-remote.sh | sh -s -- --channel nightly
```

PowerShell, installer and setup together:

```powershell
& ([scriptblock]::Create((irm https://runpane.com/install-remote.ps1))) -Label "Windows VM"
& ([scriptblock]::Create((irm https://runpane.com/install-remote.ps1))) -Label "Windows VM" -PreferTunnel ssh
```

</Toggle>

<a id="cli-options"></a>

### Setup flags

| Flag | What it does |
|---|---|
| `--label "Name"` | The host name clients see. |
| `--format deb` | Installs the Debian package instead of the AppImage, so the host doesn't need FUSE. |
| `--pane-dir <path>` | A data directory other than `~/.pane_remote`. |
| `--listen-port 42137` | The loopback port the host listens on. |
| `--auto-listen-port` | Picks a nearby free port if that one is taken. |
| `--prefer-tunnel tailscale` | Sets up Tailscale Serve. The default. |
| `--prefer-tunnel ssh` | Prints an SSH forward command and makes a code for `http://127.0.0.1:42137`. |
| `--prefer-tunnel manual --base-url <url>` | Uses your own HTTPS tunnel or reverse proxy. |
| `--no-install-service` | Skips the background service. |
| `--no-tailscale-serve` | Skips Tailscale Serve. |
| `--print-only` | Prints the commands without running them. Only with `--prefer-tunnel ssh` or `manual`, because Tailscale setup must set up Serve to make a code. |

### Voice dictation keys

Voice dictation in the browser app uses the host's keys: a **Deepgram API key** for live dictation, a **Fal API key** for recorded dictation, and an optional **OpenRouter API key** to clean up the text. Add them under **Settings → Integrations → Voice transcription** on a host with desktop Pane, or set `DEEPGRAM_API_KEY`, `FAL_KEY` and `OPENROUTER_API_KEY` in a headless host's environment.

<a id="networking-requirements"></a>

## How it connects

The host listens only on `127.0.0.1:42137` by default and refuses LAN or public addresses. Each path forwards to it:

| Path | What reaches the host |
|---|---|
| Tailscale, with a code | Tailscale Serve on port **443** of the host's tailnet name: `tailscale serve --bg --tls-terminated-tcp=443 42137`. The code's token decides who gets in. |
| Tailscale, from **Computers** | The [Workspaces](/docs/runpane-workspaces) listener on port **8443**. **Who can connect** and **Password** decide who gets in. |
| SSH tunnel | `ssh -L` from your client to the host's `42137`. |
| Manual HTTPS | Your own HTTPS reverse proxy forwarding to `42137`. |

<a id="tailscale-details"></a>

On macOS and Windows, the Tailscale app may need a moment after first login before Serve is ready. If a new code times out, wait a minute or two and connect again.

### Fallbacks

<a id="ssh-tunnel"></a>

**SSH tunnel.** Setup with `--prefer-tunnel ssh` prints a forward command. Run it on the client and keep it open:

```bash
ssh -N -L 42137:127.0.0.1:42137 user@your-host
```

> **Warning:** If the client has paired a phone or linked a computer, its own Pane already uses `42137`. Run setup with `--listen-port 42138` or another free port, or use desktop Pane's [SSH tab](/docs/remote-pane-ssh), which picks one for you.

<a id="manual-https"></a>

**Manual HTTPS.** Put Caddy, nginx or another HTTPS reverse proxy on the host, forward it to `127.0.0.1:42137`, and set up with `--prefer-tunnel manual --base-url <url>`. Any address that isn't loopback must be `https://`. Never expose the loopback port straight to the internet.

**Netbird, WireGuard, ZeroTier or another VPN.** Pane has no built-in support. Run the SSH tunnel to the host's VPN address, or put an HTTPS proxy on the host so phones can reach it too.

<a id="code-based-host-controls"></a>

## Manage the host

<a id="multi-client-device-labels"></a>

On a host with desktop Pane, **Set Up Host** shows **Host is on** or **Host is off** and each client that has a code. Clients that connect from **Computers** aren't listed.

| You do | What happens |
|---|---|
| Click **Create & Copy Code** (once the host is on) | Makes and copies a code for one more client. |
| Click **Disconnect** on a client | Drops its connection. Its code still works. |
| Click the trash icon on a client | Revokes it. Its code stops working. |
| Click **Disconnect Clients** | Drops every client. |
| Click **Stop Host** | Shuts the host down and disconnects everyone. |

The machine menu at the top of the sidebar shows where your agents run, and switches hosts. The **Remote** item in the sidebar has a status dot:

| Dot | Meaning |
|---|---|
| Green | This computer is hosting. |
| Red | Hosting failed. Hover for the error. |
| Grey | Connected to another host, or not hosting. |
| Grey, pulsing | Reconnecting to the host. |
| Grey, faded | Can't reach the host. |

<a id="permissions-in-remote-mode"></a>

When an agent asks Pane for permission, the prompt goes to every connected client. Answer it from whichever device you're on. A prompt waits until someone answers it or the session is cleared. See [Security](/docs/security#agent-permissions).

<a id="remote-desktop-for-gui-apps"></a>

For apps with a window on the host, like an Electron app or an OS setup screen, use a remote desktop alongside Pane. While you're connected, the sidebar's **Remote Desktop** shortcut opens Chrome Remote Desktop, which you set up on the host first.

## Stop or remove the host

With desktop Pane, click **Stop Host**. On a headless Linux host, stop the service and remove the Serve forward (add `sudo` if Tailscale asks), then delete `~/.pane_remote` if you want its data gone:

```bash
systemctl --user disable --now pane-remote-daemon.service
tailscale serve --tls-terminated-tcp=443 off
```

## Check and repair the service

Check the isolated remote service before you restart it or reboot the host. If you chose a different directory during setup, use that path instead of `~/.pane_remote`. On a headless host, `runpane` isn't on your `PATH`, so use `npx --yes runpane@latest` instead.

```bash
runpane doctor --pane-dir ~/.pane_remote --json
```

Doctor checks two separate things:

1. Is the remote daemon reachable now?
2. Can its saved launcher find the installed Pane executable after a restart?

That second check matters after an upgrade. A Linux service can stay alive after its executable was deleted. It looks healthy, but its old launcher may fail on the next restart. Doctor reports this as `PANE_REMOTE_DAEMON_EXECUTABLE_DELETED`. It also gives you the recovery command.

Repair the managed service:

```bash
runpane daemon repair --pane-dir ~/.pane_remote --yes --json
runpane doctor --pane-dir ~/.pane_remote --json
```

Repair rewrites the launcher and restarts the service. Connected clients will drop briefly. Your pairing and tunnel settings stay the same. You can run repair again safely. The result tells you whether anything changed.

`runpane update` updates the desktop app. It doesn't migrate an old managed launcher. Use `runpane daemon repair` when doctor tells you the launcher is stale or unsafe to restart. See the [`runpane` CLI](/docs/runpane-cli).

If a remote connection fails, check these in order:

1. Run doctor (above).
2. Check the tunnel. From the client, `curl` the address in the saved connection. Any HTTP response means the tunnel reached Pane. A timeout or connection refusal means the tunnel is still down.
3. Make sure you pasted the whole `pane-remote://...` code. These codes are long and easy to truncate.
4. On Tailscale, make sure both devices are signed into the same tailnet.
