# Troubleshooting & FAQ

## FAQ

<Toggle title="Is Pane free?">

Yes. Pane is open-source under the AGPL-3.0 license. There is no paid tier, no usage limits, and no account required.

</Toggle>

<Toggle title="Can I fork or extend Pane? What's the license?">

Yes. Pane is AGPL-3.0, with two extra terms: keep the visible Dcouple Inc attribution in the UI, and don't use the Dcouple name or logo to promote your fork.

Fork it, extend it for your team, build on it: all fine under those terms. The one thing AGPL adds is that if you serve a modified version of Pane over a network, you have to share your source too.

</Toggle>

<Toggle title="What agents does Pane support?">

Any CLI agent works. If it runs in a terminal, it runs in Pane.

| Agent | What Pane adds |
| --- | --- |
| Claude Code, Codex, Cursor, OpenCode, Pi | Built in: a tab button and shortcut, status, and conversation resume after a restart. Cursor runs on macOS, Linux and WSL repos on Windows. |
| Claude Code, Codex | Also [token and cost tracking](/docs/usage). |
| Gemini, Aider, Goose or any other CLI | Runs as a [custom command](/docs/custom-agents), and you can give it resume too. |

See the [Quick Starts](/docs/quick-starts/claude-code) for setup guides.

</Toggle>

<Toggle title="Does Pane replace my editor?">

No. Pane runs your agents, and your editor stays your editor. Pane does have a file tree, a simple editor tab and a diff view, so you can check and tweak an agent's work without switching apps. For real editing, open the pane's worktree in VS Code, Cursor, Zed or Neovim. They work on the same files.

</Toggle>

<Toggle title="Where is my data stored?">

Everything lives in `~/.pane` (or the folder in `PANE_DIR`, if you set it): `sessions.db` for your panes and history, and `config.json` for settings. That's the same on macOS, Windows and Linux.

Your code, prompts and terminal output stay on your machine. Product analytics are on by default and can be tied to your GitHub username or git email. Turn them off in **Settings → Privacy**. [Security](/docs/security#telemetry) lists what Pane sends.

</Toggle>

<Toggle title="How do I update Pane?">

Go to **Settings → General → Updates** and click **Check Now**. If there's a new version, click **Update Pane**. Pane also checks on its own every 24 hours, and you choose when to install.

Or re-run the install script from the [Download](/docs/download) page. It installs over the existing version.

</Toggle>

<Toggle title="Can I use Pane without worktrees?">

Yes. Turn off **Use worktree** in the New Pane dialog. The agent runs in your main working tree instead of an isolated branch. Useful for repos where worktree setup is impractical (large monorepos with complex setups).

</Toggle>

## Common Issues

<Toggle title="Git not found">

Pane requires git to be installed and available on your `PATH`. Install git from [git-scm.com](https://git-scm.com), then restart Pane. On macOS, `xcode-select --install` also provides git.

</Toggle>

<Toggle title="Agent not found / command not found">

Pane can't find the agent. Go to **Settings → Advanced → Additional PATH directories** and add the folder your agent lives in, like `/usr/local/bin` or `~/.local/bin`. Restart Pane after saving.

</Toggle>

<Toggle title="Worktree creation fails">

Stale worktree references can block new worktree creation. Run this in your repo root:

```bash
git worktree prune
```

Then retry creating the pane. If the error persists, check that you have write access to the directory and that the branch name doesn't already exist.

</Toggle>

<Toggle title="OS security warning on launch">

- **macOS**: Release builds are signed and notarized. If you still see a warning (on a nightly build, say), open **System Settings → Privacy & Security** and click **Open Anyway** next to Pane. You only do it once.
- **Windows**: The installer isn't code-signed yet. Click **More info → Run anyway** on the SmartScreen prompt.

</Toggle>

<Toggle title="UI freeze or blank screen">

Restart Pane. Your panes, Sessions and project settings stay as they were. If the freeze keeps happening on one project, check the latest log in `~/.pane/logs` for errors before restarting.

If the issue is reproducible, open a bug report at [github.com/greenfield-inc/Pane/issues](https://github.com/greenfield-inc/Pane/issues) with steps to reproduce.

</Toggle>

## Pane Chat and the Daemon

> **Note:** The daemon is Pane's background process. It runs your panes and terminals, and the app and the [`runpane` CLI](/docs/runpane-cli) talk to it.

<Toggle title="How do I check or repair the daemon?">

For the desktop app:

1. Run `runpane doctor --json` in a terminal.
2. If the local daemon is unreachable, quit Pane completely and reopen it.

For a headless remote host:

1. Check the Pane directory used during remote setup. If you chose a custom directory, use it instead of `~/.pane_remote`.
2. Run:

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

3. If doctor prints a recovery command, run it before restarting or rebooting. The usual command is:

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

A remote daemon can be reachable now but unable to start again. Repair briefly disconnects clients while the service restarts. It keeps the existing pairing and tunnel settings.

See [Tailscale and Remote VMs](/docs/remote-daemon) for the full remote daemon setup.

</Toggle>

<Toggle title="A Session doesn't work or won't open">

A [Session](/docs/sessions) runs a real agent CLI, like `claude` or `codex`, with no separate Pane API key. It fails when that CLI is missing from your `PATH` or not logged in. Check:

1. Run `runpane agents doctor --agent claude --repo active --json`. Swap `claude` for `codex` or `cursor` to match the Session's agent.
2. If it's not found, add its folder in **Settings → Advanced → Additional PATH directories**, then restart Pane.
3. Still stuck? Create a new Session with a different agent, or switch this one with `runpane sessions set-agent --session <id> --agent <agent>`.

</Toggle>

<Toggle title="Where are the logs on macOS?">

`~/.pane/logs/pane-YYYY-MM-DD.log`. Logs rotate at 10 MB and Pane keeps the last 5 files. They're not in `~/Library/Logs`.

A headless remote daemon logs to `~/.pane_remote/logs` instead.

</Toggle>

<Toggle title="What macOS permissions does Pane need?">

Pane doesn't use Accessibility or Full Disk Access. You'll see the normal Gatekeeper prompt on first launch (see **OS security warning on launch** above) and an optional request to send notifications.

</Toggle>

## Remote Connections

### What the Remote dot means

The **Remote** item in the sidebar's **More** (**…**) menu has a status dot. Hover it for the label.

| Dot | Label | Meaning |
| --- | --- | --- |
| Green | **Remote host live** | This computer is accepting remote connections. |
| Red | **Remote host offline** | Pane couldn't start the remote listener here. The hover text says why. |
| Grey | **Remote inactive** | Remote hosting is off on this computer. |

When this window runs your agents on another computer, the grey dot is solid while connected, pulses while connecting, and fades when Pane can't reach it.

<Toggle title="Pairing a phone with a QR code doesn't work">

You pair from **Home → Pair a phone** or **Settings → Remote Access → Add a device**. See [Pane on your phone](/docs/phone) for the full steps. If it goes wrong:

- **"This code was already used" or "This code expired":** each code works once and lasts 10 minutes. Scan the new code the computer shows.
- **"Reconnecting to &lt;computer&gt;…":** the app keeps retrying, at least every 5 seconds, while it's open. There's nothing to do. On the same Wi-Fi it connects directly even when the internet is down.
- **"Asleep since 9:40":** the computer is asleep. Wake it, or turn on Keep Awake.
- **A browser on Wi-Fi with no internet** can't reach the computer, because a browser needs internet DNS (the lookup that turns a name into an address). Open the Pane app instead.
- **"Phones can't connect: this computer's phone listener isn't running":** another app, often a second Pane, holds the listener's port. Quit that app, or give the listener a free port in **Settings → Remote Access → Tailscale → Advanced**.

</Toggle>

<Toggle title="Connect my own computers over Tailscale">

Pairing is easier: **Settings → Remote Access → Add a device → Computer** ([Your computers](/docs/your-computers)). Over Tailscale:

1. Open Pane on both computers and sign in to Tailscale with the same login.
2. Open **Settings → Remote Access → Computers**, or the machine menu at the top of the sidebar.
3. Click **Switch** next to the other computer. If you can't pick it, its label says why:
   - **Needs password**: enter its password.
   - **Older Pane**: update Pane there.
   - **Owner only**: another Tailscale user's computer that admits only its owner.
   - **Pane not open**: open Pane there, and check its **Who can connect** isn't **Off**.
   - **Offline**: wake it or sign it in to Tailscale.
4. On the host, check **Settings → Remote Access → Tailscale → Who can connect**. **Only me** allows your login. Other tailnet users need **Everyone on tailnet**, which warns before you click **Allow Everyone**.

To go back to local mode, pick **This computer** (or the name you gave it) in the machine menu. A saved computer belongs to its tailnet, so after you switch tailnets, connect again. If Pane says **Too many wrong passwords for this machine**, wait a minute.

For browsers, other Tailscale accounts and headless hosts, use a connection code: **Settings → Remote Access → Tailscale → Paste a connection code**.

</Toggle>

<Toggle title={`Connecting says "This machine is password protected"`}>

Enter the password when desktop Pane asks, and Pane saves it. [`runpane workspace`](/docs/runpane-workspaces) and [`runpane handoff`](/docs/runpane-handoff) use that saved password, so connect once from **Settings → Remote Access → Computers** before using the CLI. Only someone at that computer can change its password or **Who can connect**.

</Toggle>

<Toggle title={`Connecting says "Tailscale is not installed on this computer"`}>

You don't need Tailscale to pair a phone or link your computers. You need it only for the Tailscale path: **Settings → Remote Access → Tailscale**, connection codes over Tailscale, and `runpane workspace` to machines that aren't linked. Check if Tailscale is installed:

```bash
tailscale version
```

Install Tailscale from [tailscale.com/download](https://tailscale.com/download), run `tailscale up` to sign in, and retry. For **Tailscale is signed out on this computer**, run only `tailscale up`.

</Toggle>

<Toggle title="Connection drops or slow reconnection over Tailscale">

For a phone or computer paired with a QR code, see the pairing entry above. Over Tailscale, check the link between machines:

```bash
tailscale status
tailscale ping <hostname>
```

If Tailscale relays the connection through its DERP servers instead of going direct, open UDP port 41641 on both sides. Pane reconnects on its own after brief network drops.

</Toggle>

<Toggle title={`Remote host offline: port 42137 is in use`}>

The daemon listens on `127.0.0.1:42137` by default. If another process holds that port, find it:

```bash
lsof -i :42137        # macOS / Linux
netstat -ano | findstr 42137   # Windows
```

Stop that process, or change **Listen Port** in **Settings → Remote Access → Tailscale → Advanced**, or pass `--listen-port` during setup.

</Toggle>

<Toggle title="SSH tunnel fallback">

When Tailscale is unavailable, connect over SSH. The easiest way is **Settings → Remote Access → Add a device → SSH**. Pane connects with your own SSH setup and picks a free local port for the tunnel.

By hand, avoid port 42137. Once you've paired a phone or linked a computer, your own Pane listens there, so the tunnel fails or reaches your own Pane. Run host setup with `--listen-port 42138` (or another free port), then forward it:

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

Leave that terminal open. Save a profile for `http://127.0.0.1:42138` under **Settings → Remote Access → Tailscale → Advanced → Save existing remote profile**, then connect to it.

SSH tunnels are for desktop clients. Phones pair with a QR code ([Pane on your phone](/docs/phone)). Full steps: [Remote Pane over SSH](/docs/remote-pane-ssh).

</Toggle>

<Toggle title="A connection code won't connect on a phone">

For QR pairing, see the pairing entry above. Open [runpane.com/app](https://runpane.com/app/) on the phone and paste the full `pane-remote://...` code. To install it on your home screen, see [Install the browser app](/docs/remote-daemon#paste-the-code-on-the-client). If it doesn't connect:

1. Make sure the host daemon is running.
2. If the code uses Tailscale, install Tailscale on the phone and sign in to the same tailnet.
3. Open the Tailscale app once and confirm the host is visible.
4. Return to `runpane.com/app` and retry the saved profile.
5. If the code uses SSH tunnel mode, create a new connection code with Tailscale or Manual HTTPS instead.

</Toggle>

<Toggle title="Permission dialogs not appearing remotely">

Permission prompts go to every connected client, and they wait until someone answers. If prompts don't appear:

1. Check that you're connected: hover the **Remote** dot, and its label should say **Connected to** and your host's name (see [What the Remote dot means](#what-the-remote-dot-means)).
2. Turn on **Verbose logging** in **Settings → Advanced** and check the logs for "permission" events.

</Toggle>

<Toggle title="High latency or slow terminal streaming">

With QR pairing, Pane picks the faster of the direct path and the relay every 5 seconds ([How it connects](/docs/how-it-connects)).

Over Tailscale, measure the round trip to the remote host:

```bash
tailscale ping <hostname>
```

Aim for under 50 ms. If it's higher, get a direct Tailscale connection instead of one relayed through DERP, and close remote sessions you aren't using.

</Toggle>

## Known Issues

- **`runScriptMode: nonconcurrent`**: Pane detects this setting in `pane.json` but does not enforce it yet. The run script always starts concurrently regardless of the value.

> **Note:** Track progress and report new issues at [github.com/greenfield-inc/Pane](https://github.com/greenfield-inc/Pane).
