Environment variables

Environment variables have two roles: configure pitchfork, and pass runtime information to daemon commands. For every setting's environment override, see the full settings reference.

Configure pitchfork

Variable	Purpose
PITCHFORK_CONFIG_DIR	Override the user config directory
PITCHFORK_STATE_DIR	Override state and IPC paths
PITCHFORK_LOGS_DIR	Override the log directory
PITCHFORK_LOG	Console verbosity: error, warn, info, debug, trace
PITCHFORK_LOG_FILE_LEVEL	File-log verbosity
PITCHFORK_SUPERVISOR_AUTO_START	Allow client commands to launch the supervisor; default true
PITCHFORK_READY_DELAY	Default readiness delay as a whole-second duration, such as 5s
PITCHFORK_AUTOSTOP_DELAY	Delay after the last project session leaves; default 1m

Environment overrides affect the process that reads them. Exporting a variable does not change an already running supervisor; restart it when changing its settings. Keep the same state directory in clients and the supervisor.

PITCHFORK_LOG=debug PITCHFORK_LOG_FILE_LEVEL=debug pitchfork supervisor start --force
pitchfork logs pitchfork

Enable the web UI

These similarly named variables do different jobs:

Variable	Effect
PITCHFORK_WEB_PORT=3120	Enable the web UI for this supervisor invocation
PITCHFORK_WEB_AUTO_START=true	Enable the web UI through the settings system
PITCHFORK_WEB_BIND_PORT=3120	Choose the settings-based default port; does not enable the UI alone
PITCHFORK_WEB_PATH=ps	Serve the UI under /ps/ for this invocation

PITCHFORK_WEB_PORT=3120 pitchfork supervisor start --force

The server tries up to web.port_attempts consecutive ports (default 10). Check supervisor logs for the bound address. See web UI setup.

Daemon process variables

Pitchfork supplies these to daemon commands and readiness/health command probes:

Variable	Value
PITCHFORK_DAEMON_ID	Qualified ID, such as my-project/api
PITCHFORK_DAEMON_NAMESPACE	Namespace alone, such as my-project
PITCHFORK_RETRY_COUNT	0 on the initial run, 1 on the first retry, and so on
PORT / PORT0	First resolved port, when port is configured
PORT1, PORT2, …	Additional resolved ports, indexed from zero

Ports include any offset chosen by port bumping. Your service must read them or accept them as command arguments:

[daemons.web]
run = "python3 -u -m http.server $PORT --bind 127.0.0.1"
port = { expect = [8000], bump = 10 }

Hook variables

Lifecycle hooks receive daemon metadata and configured environment values, plus event-specific fields:

Variable	Available in
PITCHFORK_EXIT_CODE	on_fail, on_stop, on_exit; -1 when a Unix signal leaves no exit code
PITCHFORK_EXIT_REASON	on_stop, on_exit: stop, exit, or fail
PITCHFORK_MATCHED_LINE	on_output: the matching raw output line
PITCHFORK_PORT, PITCHFORK_PORT0, …	Hooks for a daemon with resolved ports

Quote variables when using them in shell scripts:

printf '%s exited: reason=%s code=%s\n' \
  "$PITCHFORK_DAEMON_ID" "$PITCHFORK_EXIT_REASON" "$PITCHFORK_EXIT_CODE"

To supply your own values, use top-level [env] or a daemon's env field in pitchfork.toml.

External configuration

PITCHFORK_CONFIG is an invocation-scoped platform path list of additional config files, associated with the nearest ordinary project (or the current directory when none exists). It overrides registered attachments and is not inherited by an automatically started supervisor. See external configuration files.