# Troubleshooting & FAQ

import { Callout } from "nextra/components";

## 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. See the next question for what forking and extending Pane involves.

</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. Three agents are built in: **Claude Code**, **Codex** and **Cursor**. Each gets its own tab button and shortcut, status tracking and conversation resume after a restart. Claude Code and Codex also get token and cost tracking. Cursor works on macOS, Linux and WSL repos on Windows. Any other CLI, like Gemini, OpenCode, Aider or Goose, runs as a custom command, and you can give it resume too. See the [Quick Starts](/docs/quick-starts/claude-code) section 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. Pane sends out three things: an update check to GitHub, a fetch of model prices from OpenRouter for cost estimates, and product analytics (PostHog). Analytics are on by default and can be tied to your GitHub username or git email. Turn them off in **Settings → Privacy**. See [Security](/docs/security#telemetry) for exactly what's collected.

</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. Toggle **Use Worktrees** off 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** and add the folder where your agent lives (e.g., `/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. Sessions and project config are preserved — nothing is lost. If the freeze recurs on a specific project, check the terminal 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

<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 [Remote VM Setup](/docs/remote-daemon) for the full remote daemon setup.

</Toggle>

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

A Session runs a real agent CLI, like `claude`, `codex` or `cursor-agent`, in a terminal. There's no separate Pane-side API key.

It fails when that CLI is missing or not logged in on your `PATH`. 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>`.

See [Sessions](/docs/sessions) and [Pane Chat](/docs/pane-chat) for what they do.

</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?">

None of the scary ones. Pane doesn't use Accessibility or Full Disk Access.

You'll see the normal Gatekeeper first-launch prompt (see the OS security warning entry under Common Issues above) and an optional notification permission. That's it.

</Toggle>

## Remote Connections

<Toggle title="Tailscale not found or not installed">

Pane uses Tailscale for zero-config remote connections. Check if Tailscale is installed:

```bash
tailscale version
```

Install Tailscale: [tailscale.com/download](https://tailscale.com/download). After installing, run `tailscale up` to authenticate. Then retry the remote setup in Pane.

</Toggle>

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

Check the Tailscale link between machines:

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

If the connection is relayed (DERP) instead of direct, ensure UDP port 41641 is open on both sides. Pane auto-reconnects after brief network drops. If a session freezes for more than 30 seconds, click the session in the sidebar to force a reconnect.

</Toggle>

<Toggle title="Port conflict on host">

The daemon defaults to port 42137. If another process holds that port:

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

Kill the conflicting process or change the port in Settings > Remote Access > Remote Pane, or use `--listen-port` during setup.

</Toggle>

<Toggle title="SSH tunnel fallback">

When Tailscale is unavailable, forward the daemon port over SSH:

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

Leave that terminal open, then connect the saved profile in Pane. The profile will reach the daemon through the forwarded port.

SSH tunnel mode is mainly for desktop clients. For the phone browser app, use Tailscale or a trusted HTTPS tunnel so the phone can reach the daemon URL directly.

For the full SSH setup flow and exact commands, see [Remote Pane over SSH](/docs/remote-pane-ssh).

</Toggle>

<Toggle title="Remote Pane browser app will not connect on phone">

Open [runpane.com/app](https://runpane.com/app/) on the phone and paste the full `pane-remote://...` code. If it does not 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="Install Remote Pane on a phone home screen">

On iPhone or iPad, open `https://runpane.com/app/` in Safari, tap Share, then tap **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**.

</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. Make sure the Pane window is focused.
2. Check the connection status dot in the sidebar (green = connected).
3. Turn on **Verbose logging** in **Settings > Advanced** and check the logs for "permission" events.

</Toggle>

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

Measure the round trip to the remote host:

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

Target latency is under 50 ms for responsive streaming. If latency is high, prefer direct connections over relay (DERP), reduce terminal scrollback in Settings, and close unused remote sessions to free bandwidth.

</Toggle>

## Known Issues

- **Unsigned Windows installer**: macOS releases are signed and notarized. The Windows installer isn't signed yet, so SmartScreen may warn you on install.
- **`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.

<Callout type="info">
  Track progress and report new issues at [github.com/greenfield-inc/Pane](https://github.com/greenfield-inc/Pane).
</Callout>