One engine to a Perch home
The engine runs GitHub requests, checkouts, language servers, and agents. The desktop app or perchd can run it. Only one engine can use a given PERCH_HOME. It locks $PERCH_HOME/engine.lock and writes its process ID there. If another engine owns the lock, Perch names the process and stops startup. When the process exits, the lock is released. On filesystems without locking, the engine logs a warning and cannot enforce this limit.
Read-only commands can run alongside the engine. These include perch context, perch --items, --agents, --timeline, --scope, and --scan.
Using perchd from a terminal
perchd runs Perch’s engine without a window. The desktop app normally uploads the right executable for your SSH host. To install it yourself, download perchd-linux-<arch>.tar.gz or perchd-macos-<arch>.tar.gz for x86_64 or arm64. Releases include a SHA256SUMS file. Put the executable in ~/.local/bin. The Linux build is statically linked with musl, works on Alpine, and does not need GTK.
Start and stop the engine. perchd serve listens on $PERCH_HOME/run/perchd.sock. The directory is accessible only to its owner and the socket uses mode 0600. The engine keeps polling GitHub and running agents after clients disconnect. When started by hand it runs until stopped. Add --exit-after-idle <seconds> to stop it after that long without clients or queued or active runs.
SIGTERM, SIGINT, or SIGHUP shuts it down, marks unfinished runs Interrupted, removes the socket, and releases the lock. A second SIGTERM or SIGINT forces an immediate exit. Repeated SIGHUP does not. Logs go to standard error and $PERCH_HOME/logs. A conflicting engine lock gives exit code 75. The engine refuses a database from a newer build. On startup failure it also writes the reason to $PERCH_HOME/run/serve-failed (0600) and clears the file at its next successful start.
When started from an SSH session, the engine discards SSH_AUTH_SOCK, SSH_CONNECTION, SSH_CLIENT, and SSH_TTY. Remote Git commands use the host’s own keys. An engine started from a desktop login on the host keeps that login’s SSH agent.
Connect a client. perchd bridge connects standard input and output to the engine socket. Perch runs this command over SSH. If nothing answers, the bridge starts perchd serve --exit-after-idle 900 in a separate session and waits up to ten seconds. Set PERCH_IDLE_EXIT_SECS on the host to change that 15-minute idle period. The bridge reports a recorded startup failure or names the process holding the lock. Only engine messages go to standard output.
A bundled bridge in $PERCH_HOME/bin/perchd-<build> updates its file’s modification time on use. It removes other builds unused for a week and incomplete uploads older than an hour.
Switch builds. perchd bridge --replace asks a different build to shut down through the socket. It waits up to a minute for the lock and starts its own engine, or joins one that another bridge started in the meantime. It joins a matching build immediately. Build IDs distinguish executables, regardless of release order. For bundled engines the ID is the first 12 hex digits of the executable’s SHA-256. A manually installed engine can identify itself by version.
Use --replace-if-idle to leave a busy engine running. With connected clients or active runs, the bridge prints perch-busy: <version> <runs> <clients> to standard error and exits 98. Neither command kills processes by PID. If a desktop app holds the lock on the host, quit that app there first.
Inspect the engine. perchd status reports the running engine’s version, protocol, build, home, other clients, and queued or active runs. It starts nothing and exits 0 if an engine answers or 3 if none does. perchd --version prints the executable’s version and protocol, for example perchd 0.9.0 (protocol 6).
Read a worktree’s context. perchd context takes the same arguments as perch context and reads the host’s database. At startup, the engine points $PERCH_HOME/bin/perchd at its own build. Use ~/.perch/bin/perchd context for the default home. The engine leaves an existing regular file at that path alone.
If a crash leaves a socket file behind, the next engine checks that nothing answers before removing it.
After a host restart, engine crash, or idle shutdown, the app starts the engine on its next connection. To keep an engine stopped, disconnect its windows or switch them to the local environment before stopping it.
On Linux, logind can end processes at logout. If KillUserProcesses=yes, the SSH user needs to be in KillExcludeUsers to keep the engine running after disconnect. A user explicitly listed under KillOnlyUsers is also subject to cleanup. Perch checks the policy under Host setup.
An idle app sends a keepalive every 15 seconds. After a minute of silence the engine releases that client’s windows and language servers. The same timeout applies to a connection that never finishes its handshake. A Mac reconnects on waking and disables App Nap while connected so a hidden window can keep its connection.
The app's own engine
By default, the desktop app supplies the host’s engine. The host stores it as ${PERCH_HOME:-~/.perch}/bin/perchd-<build>. The build ID is the first 12 hex digits of the executable’s SHA-256. Apps carrying the same executable reuse it. Different builds can sit side by side. See How an app gets its engines for development builds.
- The host’s login shell runs a short
shscript to find the engine for its OS and processor. If the requested build exists, its bridge starts or joins the engine. Otherwise the script printsperch-install: <uname -s> <uname -m>to standard error and exits 97. - Perch shows upload progress and uses a second SSH connection with the same options to send the executable. The host writes an owner-only temporary file and verifies its SHA-256 with
sha256sum,shasum, oropensslbefore installing it. Two clients can upload the same build safely. An incomplete file is never run. - After a successful upload, Perch reconnects immediately. A failed upload retries with the next connection attempt. If the upload succeeded but the host still reports the engine missing, retries stop. Check whether the login shell changes
PERCH_HOME. - If the app lacks a build for the host and cannot build one from source, it reports the missing platform. For a separately installed compatible engine, set
[remote] command.
How an app gets its engines
When you build the app, crates/perch-app/build.rs builds the available Linux and macOS engines for x86_64 and arm64 using the app’s build profile. It compresses each executable, records its SHA-256, and embeds it in the app. This also happens with cargo run. The desktop app itself targets the build machine.
- Linux engines use musl and
cargo zigbuild. Install Zig and cargo-zigbuild (for examplebrew install zigandcargo install cargo-zigbuild). On Linux without those tools,musl-gcccan build for the local CPU. - On macOS, the Rust toolchain can build for either CPU. On other systems, building a macOS engine also requires Zig and an Apple SDK specified by
SDKROOT. - Rustup installs the four targets listed in
rust-toolchain.toml. Missing tools skip that target with a warning. A compiler error fails the build. Cargo keeps engines underenginesin its target directory and rebuilds them when their sources change. - Set
PERCH_ENGINESto the absolute path of a directory containing all fourperchd-<linux|macos>-<x86_64|arm64>.tar.gzarchives to embed prebuilt engines. Release builds use this method and require all four files. UsePERCH_ENGINES=nonefor an app-only build. Clippy and rust-analyzer also skip engine builds.
If a development build lacks the host’s engine but its original source tree is still available, Perch builds the missing executable on demand. For Linux it uses cargo zigbuild with musl. For macOS it uses cargo build on a Mac. The connection notice reports missing tools or shows upload progress. On each launch Cargo checks whether it needs to rebuild. Perch uploads the result only if the host lacks that build ID.
With [remote] command set, Perch runs that command and skips the upload.
A bundled bridge keeps regularly used builds on the host and cleans up builds unused for a week.
When the engine is another build
Check for Updates… and Restart to update update the desktop app even when the host is disconnected. The update check uses the public GitHub repository and needs no token from the host.
After an update, Perch uploads its new engine alongside the old one. If an engine is already running, Perch compares build IDs. What happens next depends on who’s using it.
- Idle engine. With no runs or other clients, Perch reconnects with
perchd bridge --replace-if-idleto start its matching engine. It tries once per connection. If someone starts using the engine in the meantime, Perch leaves it running. - Busy engine. If the protocols match, Perch connects to the running build and offers Restart. If they differ, it offers Restart and Reconnect. The notice includes the run and client counts seen at connection time. Restart uses
perchd bridge --replace, interrupts active runs, and makes other clients reconnect. - Several app versions. Two clients can share a build when their protocols match. Each automatically replaces a different build only when it is idle. If a newer engine has upgraded the database beyond what your build supports, update your desktop app.
If you configured [remote] command, Perch uses the engine that command reaches. You manage its updates.
Starting with protocol 5, the app and engine can exchange version information and request a shutdown even if the rest of their protocols differ. Older engines cannot handle that request. Stop the old perchd serve on the host and reconnect.
For a connection test without opening a window, run perch --connect [host]. It uses the app’s normal connection procedure, including uploading a missing engine or replacing an idle build. Omit the host to use [remote] host from the desktop configuration.
The command prints the engine version, protocol, build, host, home, data folder, and client and run counts. If it joined a busy engine with a different build, it says so. It waits up to 30 seconds for the host checks and prints suggested fixes for failed checks. A successful connection exits 0. A connection failure prints the reason and exits 1.