Configuration

Pilothouse works without a config file; every option has a default. To change something, create ~/.pilothouse/config.yaml (or $PILOTHOUSE_HOME/config.yaml). Durations use Go syntax: 45s, 9m, 720h.

web:
  addr: 127.0.0.1:7517          # loopback only
  public_url: ""                # set by `pilothouse remote tailscale`

presence:
  idle_threshold: 60s           # idle longer than this = away (min 5s)
  notify_after: 45s             # at the desk: desktop notification after this long

approvals:
  hold_limit: 9m                # how long to hold a request for your devices (min 10s)
  always_hold: false            # send every permission request to devices, even at the desk
  fail_closed: false            # deny PreToolUse when the daemon is unreachable

notify:
  desktop: true
  ntfy:
    server: https://ntfy.sh
    topic: ""                   # empty = ntfy off
    token: ""
  webhooks: []                  # Slack/Discord-compatible incoming webhook URLs

retention: 720h                 # closed requests and hook events (30 days)
machine: ""                     # name shown in the inbox and on your phone (default: hostname)
update_check: true              # anonymous daily update check

Options

Key	Default	Description
web.addr	127.0.0.1:7517	Listener for the web app and device API. Keep it on loopback; use Tailscale Serve for remote access.
web.public_url	—	HTTPS address of the web app, e.g. https://mac.tailnet.ts.net. Used for pairing links, push and ntfy buttons.
presence.idle_threshold	60s	How long without input before you count as away.
presence.notify_after	45s	At the desk, send a desktop notification if a dialog has waited this long.
approvals.hold_limit	9m	Maximum time a request is held for your devices before the agent’s own dialog takes over. Always clamped below the agent’s hook timeout.
approvals.always_hold	false	Route every permission request to devices regardless of presence.
approvals.fail_closed	false	If the daemon is unreachable, deny PreToolUse instead of having no opinion.
notify.desktop	true	Desktop notifications.
notify.ntfy.server	https://ntfy.sh	ntfy server.
notify.ntfy.topic	—	ntfy topic. Empty disables ntfy.
notify.ntfy.token	—	ntfy access token.
notify.webhooks	[]	Incoming webhook URLs (Slack, Discord).
retention	720h	How long closed requests, hook events and state evidence are kept.
machine	hostname	Display name for this machine in the inbox, web app and notifications. Also settable with PILOTHOUSE_MACHINE.
update_check	true	Anonymous daily update check.

Environment variables

Variable	Effect
PILOTHOUSE_HOME	Data directory (default ~/.pilothouse)
PILOTHOUSE_NO_UPDATE_CHECK=1	Disable the update check

Inside wrapped agents Pilothouse sets PILOTHOUSE=1 and PILOTHOUSE_SESSION_ID.