Install

Pilothouse is one static binary. There is no runtime to install and nothing to sign up for.

	Supported
Operating systems	macOS, Linux
Architectures	amd64 (x86_64), arm64 (Apple Silicon, Graviton, Raspberry Pi 4/5)
Agents	Claude Code, Codex
Windows	Not yet — on the roadmap

Install script

curl -fsSL https://pilothouse.dev/install.sh | sh

The script:

1. detects your OS and architecture,
2. downloads the latest release archive and checksums.txt from GitHub Releases,
3. verifies the archive’s SHA-256 checksum and stops if it doesn’t match,
4. installs pilothouse to /usr/local/bin if that directory is writable, otherwise to ~/.local/bin (and tells you if that isn’t on your PATH).

It never runs sudo for you. Read it first if you like — it’s short: pilothouse.dev/install.sh.

Options

Variable	Effect
PILOTHOUSE_VERSION	Install a specific version, e.g. 0.1.0 or v0.1.0. Default: latest.
PILOTHOUSE_INSTALL_DIR	Install somewhere else, e.g. $HOME/bin.

curl -fsSL https://pilothouse.dev/install.sh | PILOTHOUSE_VERSION=0.1.0 PILOTHOUSE_INSTALL_DIR="$HOME/bin" sh

Homebrew

brew install xasdta/tap/pilothouse

Upgrade with brew upgrade pilothouse.

Manual download

Every release has archives named pilothouse_<version>_<os>_<arch>.tar.gz (for example pilothouse_0.1.0_linux_arm64.tar.gz) and a checksums.txt. To verify by hand:

grep pilothouse_0.1.0_linux_arm64.tar.gz checksums.txt | sha256sum -c -
# macOS: shasum -a 256 -c

Set up

pilothouse setup

This installs the agent hooks, installs and starts the user service, and runs the same checks as pilothouse doctor. You can do each part separately:

pilothouse hooks install     # Claude Code + Codex hooks (merged, backed up)
pilothouse service --help    # manage the launchd / systemd user service
pilothouse doctor            # check everything, print what to fix

Hook installation merges into the agent’s settings and never removes hooks you already have. Before changing ~/.claude/settings.json Pilothouse writes a backup next to it (settings.json.pilothouse-bak-<timestamp>). Pilothouse’s own entries are the ones whose command contains pilothouse hook.

Running agents as a service on Linux

The daemon runs as a systemd user service. On a headless server where you log in over SSH, enable lingering so it keeps running after you log out:

loginctl enable-linger "$USER"

Where things live

Path	What
~/.pilothouse/config.yaml	Configuration (reference)
~/.pilothouse/policy.yaml	Your rules
~/.pilothouse/trusted-repos.yaml	Repos whose allow rules you trust
~/.pilothouse/pilothouse.db	Event log (SQLite)
~/.pilothouse/logs/	Daemon and holder logs

The data directory is created with mode 0700; the database, keys and config are 0600. Set PILOTHOUSE_HOME to move it.

Updating

Run the install script again, or brew upgrade pilothouse. Pilothouse checks for new versions once a day with an anonymous request (version, OS, architecture and a random ID that rotates monthly). Turn that off with update_check: false in config.yaml or PILOTHOUSE_NO_UPDATE_CHECK=1.

Uninstall

pilothouse hooks uninstall   # removes only Pilothouse's hook entries
pilothouse stop

Then remove the user service (pilothouse service --help shows how), delete the binary (which pilothouse), and delete ~/.pilothouse if you don’t want to keep your rules and history.