Perch
Guide contents

Field guideGet set up

Remote hosts (SSH)

Keep the Perch window on your desktop and run Git, language servers, and agents on the machine where your code lives.

Setting up a host

Use a Linux or macOS host (x86_64 or arm64) that you can reach with ssh <host>. Perch uploads and starts its own engine on your first connection. Prepare the host under the account you use for SSH.

  1. If you use Claude Code on Linux, install its sandbox dependencies with apt install bubblewrap socat or your distribution’s equivalent. See Without the agent sandbox if you run on a dedicated VM or container.
  2. Run gh auth login or set token in the host’s config.toml. Sign in to each agent CLI you plan to use there (claude, codex, agy, or opencode). The host uses its own credentials.

Click your GitHub name at the bottom of the sidebar. Choose a saved host or Connect to SSH host…. You can also enter a host under Settings → Environment and click Connect.

Account menu showing the current local environment, two saved SSH hosts, and Connect to SSH host

Switching closes the current item in this window and opens the host’s repositories and agent runs. Other windows keep their place. Choose Use local environment in Settings to switch back. The menu includes hosts open in other windows. Click × beside an unused host to forget it. Perch saves the list in your local hosts.json.

Perch reopens the windows from your previous session, including each window’s environment, size and open item. A remote window reopens its item when its host connects. Closing one window removes it from the session. Closing the last window keeps it for the next launch.

New Window inherits the environment of the window in front. On a first launch with no saved windows, Perch uses the existing [remote] host in the local config if one is set, or opens locally.

Enter an SSH config alias, user@host, or an SSH URL. For a custom port, use chris@devbox:2222 or ssh://chris@devbox:2222. Put IPv6 addresses in brackets when specifying a port, as in [fe80::1]:2222. Perch uses the port for the engine, installation, and Open in Terminal. For Open in Editor with a custom port or IPv6 address, use Zed or give the host an alias in ~/.ssh/config.

Connect once from a terminal to accept the host key. Perch connects in batch mode, so your SSH credentials must work without a prompt.

On a Mac host, perchd runs caffeinate -i to prevent idle sleep while the engine runs. Closing a laptop’s lid still puts it to sleep.

You can add or clone a repository from Perch after you connect.

Adding a repository on a host

In a remote window, choose Add repository… to open Settings > Repositories. Enter a repository name or a path on the host.

  • GitHub repository. Enter owner/name or a github.com URL. The engine clones into the folder shown under Clone into (clone_root in the host’s config.toml), or your home directory if unset. It reuses an existing clone of the same repository. If another folder has that name, Perch reports the conflict and leaves it alone. The engine supplies its GitHub token for that clone operation only. Later fetches and pushes use the host’s Git credentials.
  • Existing clone. Enter its path on the host, starting with / or ~/.

Press Enter or click Add to submit. Perch keeps your entry while the clone runs and shows any error so you can correct it. For GitHub Enterprise, clone the repository yourself and add its path.

Connecting

Windows on the same host share one SSH connection. Perch starts its local engine only when a window uses the local environment. For a remote window it runs this command.

ssh -T -o BatchMode=yes -o ConnectTimeout=10 -o ServerAliveInterval=15 \
    -o ServerAliveCountMax=3 -o ForwardAgent=no -o ForwardX11=no \
    -o ClearAllForwardings=yes -- <host> <command>

Perch sends engine traffic over SSH’s standard input and output. The host runs ~/.perch/bin/perchd-<build> bridge in your login shell, so it uses the PATH you set for Git, gh, and agents. You can override the command for your default host with [remote] command. See The app’s own engine.

SSH uses your usual configuration, keys, and agent to log in. Perch disables agent, X11, and port forwarding. If your key has a passphrase, load it into your SSH agent or macOS keychain first. SSH errors go to the log. To use a different SSH program, set PERCH_SSH in the app’s environment.

In a remote window, paths belong to the host. For example, ~ refers to your home directory on that host.

  • Open in Terminal starts a shell in the remote directory with ssh -t -- <host> 'cd -- <path> && exec $SHELL -l'. Use an absolute path. Perch refuses paths with a quote, backslash, !, or control character because shells interpret these differently.
  • Open in Editor replaces Reveal in Finder. For an absolute path, Perch opens Zed with zed ssh://<host>/<path> if the command or app is installed. Otherwise it tries Visual Studio Code with code --remote ssh-remote+<host> <path> and tells you if neither can open.
  • Copy Path copies the path on the host.

If the connection drops, the window keeps your place and shows the last SSH error. Click Reconnect to retry immediately. Perch also retries after one second, then two, doubling the delay up to 30 seconds. An attempt times out after 30 seconds. A connection that drops within a minute keeps its retry delay.

While disconnected, Perch tells you when it cannot send a comment or command. If you ask to open an item during the first connection attempt, Perch opens it if that attempt succeeds. If you lose the connection after sending a request, check the list before trying again. The engine might already have created the worktree. Perch never repeats that request automatically.

When you reconnect, Perch refreshes the inbox, runs, settings, and open item. It keeps text you typed into the composer or review, retries missing images, and updates which window has keyboard focus.

If the app and engine use incompatible protocol versions, Perch pauses retries. For a bundled engine, the window offers to restart it with a compatible build. For a custom [remote] command, it tells you which side needs an update. Click Reconnect when ready.

In a remote window, repositories, agents and GitHub settings belong to the host. Appearance, display and keyboard shortcuts come from the app’s local configuration. General > Configuration files shows where each file lives. If a file cannot be read, Perch keeps its last settings and disables edits to that file. You can still switch the window’s environment.

What runs where

The host keeps the GitHub token, perch.db, repositories, worktrees, and engine settings. It runs Git, language servers, and agents, and records approvals. Your desktop draws the windows and keeps window positions and the [ui], [display], [keybindings], and [remote] settings in its local Perch home.

You can close Perch or put your laptop to sleep during a remote run. The host finishes active runs, starts queued ones, polls the inbox, and watches checks. If a Work run needs your answer, it waits up to eight hours by default. Answer in the window when you reconnect.

An engine started by the app stops after 15 minutes with no connected clients, queued or active runs, or clones in progress. A run waiting for an answer still counts as active. Perch restarts the engine and refreshes your windows when you reconnect. An engine you start yourself with perchd serve runs until you stop it. Stopping the engine interrupts active runs.

What the app checks

Open Settings > Environment > Host setup for failed checks and instructions you can copy. Show details includes passed checks and optional tools. Each affected window also offers Open Settings. To see the same list in a terminal, run perch --connect.

The remote engine checks the host at startup, after a configuration change, and when it receives a new GitHub token.

  • GitHub token. The engine checks GITHUB_TOKEN, GH_TOKEN, gh auth token, token in its config.toml, then the two variables in the host’s login shell. The app shows the source. The token stays on the host. Run gh auth login if the check fails.
  • Git. The engine runs git --version. If Git is missing, Perch shows the install command for the host’s package manager (apt-get, dnf, yum, pacman, zypper, or apk).
  • Repositories. At least one [[repo]] entry needs a root directory on the host. Perch lists missing directories, offers the clone command for github.com repositories, and provides an Add repository… button.
  • Coding agents. Perch shows the path and version for Claude Code, Codex, agy (Gemini), and OpenCode. Any one is enough. If all are missing, the panel prompts you to install Claude Code. It offers curl -fsSL https://claude.ai/install.sh | bash for Claude Code, npm install -g @openai/codex for Codex, and a link to the agy documentation.
  • Claude Code’s sandbox. On Linux, install bubblewrap and socat on the host’s PATH. When you disable Claude Code’s sandbox in config ([agent] sandbox = false), this check reads Off.
  • Gemini’s (agy) sandbox. On Linux, agy’s sbox needs unprivileged user namespaces with sethostname allowed (container seccomp profiles such as Podman’s default block sethostname). When blocked, Perch surfaces the reason here and refuses sandboxed Gemini print runs up front; turn off Gemini’s sandbox alone ([agent.gemini] sandbox = false) on a container or VM host where the machine is already the boundary.
  • Linux login sessions. Where logind is available, Perch uses loginctl show-session to check whether logging out kills your processes. If it does, add the SSH user to KillExcludeUsers in a logind drop-in and restart systemd-logind. Perch skips this check on hosts without loginctl or logind.

Checks run in the background. Each command has ten seconds to respond before the engine reports it as missing. These checks run only on remote hosts.

Limits

  • If you set [remote] command, you manage engine updates. When Perch reports an incompatible protocol version, install the matching perchd on the host and restart it.
  • Use a Linux or macOS host. Windows hosts are unsupported.

To check or restart the engine yourself, see The remote engine (perchd).