Start at login or boot

Register Pitchfork with launchd on macOS or systemd on Linux so the supervisor starts without an interactive shell. Then choose which daemons it starts with boot_start = true.

Start at login

For local development, run:

pitchfork boot enable
pitchfork boot status

This installs a user service that starts when you log in. The supervisor and its daemons run as your user and read your Pitchfork configuration. For HTTPS on the standard port, use local proxy setup; the supervisor can remain unprivileged.

Keep a stable executable path

By default, registrations use the running binary's resolved path. After a package-manager upgrade, automatic repair updates stale registrations to that path. To opt into a stable symlink instead, set an absolute path in the user config (~/.config/pitchfork/config.toml) or system config:

[settings.boot]
executable = "/home/alice/.local/share/mise/installs/pitchfork/latest/pitchfork"

Replace the example with your installed executable. Then run pitchfork boot enable (or sudo pitchfork boot enable for a system service). Initial registration, repeated enable, and automatic repair all use this literal path without resolving away symlinks, even if the symlink points to a newer version than the running supervisor. Updating the recorded invoking user also keeps this executable choice.

The path must be absolute, exist, and be executable. Pitchfork does not expand ~, search PATH, or execute a shell command here. Invalid explicit paths fail registration; automatic repair logs the error and leaves the old entry intact. Status and disable still work. Control characters are rejected. Linux and Windows currently do not support whitespace in executable paths; Linux also rejects quotes, backslashes, %, and $ because of the systemd registration format.

PITCHFORK_BOOT_EXECUTABLE overrides the setting for a process. Prefer persistent user or system configuration: a terminal-only variable might not be visible to the supervisor at boot, which would restore default repair behavior. Project config files cannot set this option, including for a system-level registration. An empty value keeps the original default behavior. This setting only affects boot registration, not other internal Pitchfork invocations.

Keep the executable and its parent directories trusted, especially for a root service. Changing the symlink does not restart the running supervisor. Reload or restart the service when ready to use a new target.

Choose which daemons start

Set boot_start = true on daemons that should start with the supervisor. For example, in ~/.config/pitchfork/config.toml:

[daemons.worker]
run = "exec /opt/my-app/bin/worker"
boot_start = true

[daemons.api]
run = "exec /opt/my-app/bin/server"
boot_start = false

Replace the commands with your application's installed programs. The worker starts at login; the API stays stopped until explicitly started or requested through a configured proxy. Omitting boot_start is equivalent to false.

Login and boot services do not load your shell's startup files. Use absolute paths or mise integration for tools normally supplied by shell activation.

Run the supervisor as root

Use a system service when the supervisor needs root privileges or must start before anyone logs in:

sudo pitchfork boot enable
pitchfork boot status

If a user registration already exists, disable it first with pitchfork boot disable. Pitchfork refuses to add a registration at another privilege level while the first is still registered.

When Alice runs sudo pitchfork boot enable, Pitchfork records her account in the generated service command:

/usr/local/bin/pitchfork supervisor run --boot --invoking-user alice

The executable path reflects the installed binary. The recorded account replaces the sudo environment that launchd and systemd do not inherit. At boot:

• The supervisor runs as root and reads /etc/pitchfork/config.toml and Alice's ~/.config/pitchfork/config.toml, including proxy settings and namespaces.
• State, logs, and the IPC socket default to Alice's ~/.local/state/pitchfork, with state ownership assigned to Alice. Her CLI commands can reach the same supervisor.
• Daemons run as Alice by default. A daemon's user overrides settings.supervisor.user, which overrides the recorded account.

PITCHFORK_STATE_DIR still overrides the state directory. To choose a different account for default daemon identity and state ownership, set this in Alice's user configuration or the system configuration:

[settings.supervisor]
user = "devservices"

This setting does not change whose user configuration is loaded. See daemon user selection and file locations for the details.

If the recorded account no longer exists, the supervisor fails before resolving configuration or state paths. Re-register from the account that should own the setup. A system service installed from a root login shell without SUDO_USER records no account and keeps root's configuration and identity unless explicitly overridden.

Update an existing system service

Re-run sudo pitchfork boot enable to update an older registration that does not record your account, or one that points to a different executable. An unchanged registration is left alone. Reload the service to use the updated command; this interrupts its running daemons:

macOS

sudo pitchfork boot enable
sudo launchctl bootout system /Library/LaunchDaemons/pitchfork.plist
sudo launchctl bootstrap system /Library/LaunchDaemons/pitchfork.plist

Linux

sudo pitchfork boot enable
sudo systemctl restart pitchfork

A machine restart also loads the updated registration. Automatic registration repair after an executable moves preserves the account already recorded in the service.

Check registration

pitchfork boot status

Status reports the registered privilege level and, for a system service, the recorded account or root configuration. It describes the registration; use pitchfork supervisor status to check the running process.

Registration files

Platform	User service	System service
macOS	~/Library/LaunchAgents/pitchfork.plist	/Library/LaunchDaemons/pitchfork.plist
Linux	~/.config/systemd/user/pitchfork.service	/etc/systemd/system/pitchfork.service

Disable registration

pitchfork boot disable

Use sudo pitchfork boot disable for system registrations. Disable removes registrations at both privilege levels where permissions allow it, including legacy macOS registrations. Check pitchfork boot status afterward.

Keep one supervisor owner

When the service manager should be the only owner of the supervisor, add this to the configuration it reads:

[settings.supervisor]
auto_start = false

CLI commands, the TUI, and shell activation then connect to the managed supervisor without spawning a replacement if it is unavailable or still starting. Explicit pitchfork supervisor start and pitchfork supervisor run remain available.