Settings Reference
This page documents all configurable settings for pitchfork. Settings can be configured via:
- Environment variables (highest priority)
- Project-level:
pitchfork.tomlorpitchfork.local.tomlin[settings]section - User-level:
~/.config/pitchfork/config.tomlin[settings]section - System-level:
/etc/pitchfork/config.tomlin[settings]section
Settings are merged in precedence order, with later sources overriding earlier ones.
Configuration in pitchfork.toml
Add a [settings] section to any pitchfork.toml file:
# Daemon definitions
[daemons.myapp]
run = "node server.js"
# Settings configuration
[settings.general]
autostop_delay = "5m"
log_level = "debug"
[settings.web]
auto_start = true
bind_address = "0.0.0.0"
bind_port = 8080
[settings.tui]
refresh_rate = "1s"
[settings.supervisor]
file_watch_debounce = "2s"Global Configuration
For user-wide settings, create ~/.config/pitchfork/config.toml:
# Global daemons (e.g., database services)
[daemons.postgres]
run = "postgres -D /usr/local/var/postgres"
# Global settings
[settings.general]
log_level = "info"
[settings.web]
auto_start = trueEnvironment Variables
Every setting has a corresponding environment variable that overrides all file configurations:
# Override via environment
export PITCHFORK_LOG=debug
export PITCHFORK_WEB_AUTO_START=true
export PITCHFORK_AUTOSTOP_DELAY=5mAll Settings
General Settings
general.autostop_delay
DurationDelay before auto-stopping daemons when leaving a directory
When using shell hooks with auto = ["stop"], this controls how long pitchfork waits
before stopping a daemon after you leave its directory.
This delay prevents unnecessary stop/start cycles when briefly switching directories.
Examples:
"0s"- Stop immediately (no delay)"30s"- Wait 30 seconds"1m"- Wait 1 minute (default)"5m"- Wait 5 minutes
Set to "0s" to disable the delay and stop daemons immediately.
general.interval
DurationSupervisor background task refresh interval
Controls how often the supervisor refreshes its internal state and checks for:
- Daemon health status changes
- Configuration file updates
- Process state synchronization
Lower values provide more responsive status updates but use more resources.
Recommended values:
"5s"- For development/testing"10s"- Default, balanced"30s"- For production with many daemons
general.log_level
StringConsole log level (trace, debug, info, warn, error)
Controls the verbosity of log output to the console.
Available levels:
"trace"- Most verbose, includes all internal details"debug"- Detailed information for debugging"info"- Normal operation messages (default)"warn"- Warnings and potential issues"error"- Only errors
general.log_file_level
StringFile log level (trace, debug, info, warn, error)
Controls the verbosity of log output written to log files.
Can be set independently from log_level to have more verbose file logs.
For example, set console to "info" but file to "debug" to keep
detailed logs for troubleshooting without cluttering the console.
general.mise
BooleanWrap daemon commands with mise x -- globally
When enabled, pitchfork wraps every daemon command with mise x -- so that
mise sets up the correct tool versions, PATH,
and environment variables before the daemon runs.
This is especially useful when pitchfork is started as a login item or boot
daemon, where the shell profile (.zshrc, .bashrc) is not sourced and
tools installed via Homebrew or mise are not on PATH.
Individual daemons can override this with mise = true or mise = false
in their configuration.
general.mise_bin
StringExplicit path to the mise binary
By default, pitchfork searches well-known locations for the mise binary:
~/.local/bin/mise~/.cargo/bin/mise/usr/local/bin/mise/opt/homebrew/bin/mise
Set this to an absolute path if mise is installed elsewhere.
IPC Settings
ipc.connect_attempts
NumberNumber of connection retry attempts
How many times to retry connecting to the supervisor before giving up.
Each attempt uses exponential backoff between connect_min_delay and connect_max_delay.
ipc.connect_min_delay
DurationMinimum delay between connection retries
The initial delay between connection retry attempts.
The actual delay increases exponentially up to connect_max_delay.
ipc.connect_max_delay
DurationMaximum delay between connection retries
The maximum delay between connection retry attempts. Exponential backoff will not exceed this value.
ipc.request_timeout
DurationDefault timeout for IPC requests
Maximum time to wait for a response from the supervisor for most operations.
Note: Daemon start operations may use a longer timeout calculated from
the daemon's ready_delay setting plus a buffer.
ipc.rate_limit
NumberMaximum IPC requests per second per connection
Rate limiting for IPC connections to prevent local DoS attacks. Uses a sliding window algorithm.
Most users won't need to change this. Increase if you have automated tools making many rapid requests to the supervisor.
ipc.rate_limit_window
DurationRate limit sliding window duration
The time window for rate limiting calculations.
rate_limit requests are allowed within each window.
Web UI Settings
web.auto_start
BooleanAutomatically start web UI when supervisor starts
When enabled, the web UI server will automatically start alongside the supervisor.
By default, this is disabled. You can start the web UI manually with:
pitchfork web
Or enable auto-start via environment variable:
export PITCHFORK_WEB_AUTO_START=true
web.bind_address
StringWeb server bind address
IP address for the web UI to listen on.
Security Warning: The default 127.0.0.1 only allows local connections.
Setting this to 0.0.0.0 will expose the web UI to your network.
Examples:
"127.0.0.1"- Local only (default, recommended)"0.0.0.0"- All interfaces (use with caution)"192.168.1.100"- Specific interface
web.bind_port
NumberDefault web server port
The port number for the web UI. If this port is in use, pitchfork will
try subsequent ports up to port_attempts times.
web.port_attempts
NumberNumber of ports to try if default is in use
If the default port is occupied, pitchfork will try this many consecutive ports before giving up.
For example, with bind_port = 3120 and port_attempts = 10,
it will try ports 3120, 3121, 3122, ... up to 3129.
web.log_lines
NumberInitial number of log lines to display
How many lines of logs to show initially when viewing daemon logs in the web UI. More lines means slower initial load but more history visible.
web.base_path
StringURL path prefix for the web UI (e.g. "ps" serves at /ps/)
Serves the web UI under a sub-path prefix, useful when running behind a reverse proxy that routes a path prefix to pitchfork.
Examples:
""- Serve at root/(default)"ps"- Serve at/ps/"tools/pitchfork"- Serve at/tools/pitchfork/
Equivalent to the --web-path CLI flag. The CLI flag takes priority over this setting.
web.sse_poll_interval
DurationServer-Sent Events poll interval for log streaming
How often the web UI checks for new log lines when streaming logs. Lower values provide more real-time updates but use more resources.
TUI Settings
tui.refresh_rate
DurationDaemon list refresh interval
How often the TUI refreshes the daemon list and status information.
Lower values provide more responsive updates but may increase CPU usage, especially with many daemons.
Recommended values:
"1s"- More responsive"2s"- Default, balanced"5s"- Lower resource usage
tui.tick_rate
DurationEvent loop tick rate
How often the TUI checks for keyboard input and other events. This affects input responsiveness.
Most users won't need to change this. Lower values make the UI more responsive but use more CPU.
tui.stat_history
NumberNumber of stat samples to keep for graphs
How many CPU/memory stat samples to keep for each daemon's graph. With the default refresh rate of 2s, 60 samples = ~2 minutes of history.
Increase for longer history in graphs, at the cost of more memory.
tui.message_duration
DurationStatus message display duration
How long status messages (like "Daemon started") remain visible in the TUI before automatically clearing.
Supervisor Settings
supervisor.ready_check_interval
DurationInterval between ready checks (HTTP, TCP, command)
How often to poll when checking if a daemon is ready using:
ready_http- HTTP health endpointready_port- TCP port listeningready_cmd- Shell command exit code
Lower values detect readiness faster but use more resources.
supervisor.file_watch_debounce
DurationFile watch debounce duration
When using watch patterns to auto-restart daemons on file changes,
this controls how long to wait after the last change before triggering
a restart.
This prevents rapid restart cycles when many files change at once (e.g., during a build or git checkout).
supervisor.log_flush_interval
DurationDaemon log buffer flush interval
How often daemon log output is flushed to disk. Lower values mean logs appear faster in the UI but may impact performance.
supervisor.stop_timeout
DurationMaximum time to wait for daemon to stop gracefully
When stopping a daemon, pitchfork sends SIGTERM and waits this long for the process to exit gracefully before sending SIGKILL.
Increase for daemons that need time to clean up (e.g., flush data).
supervisor.restart_delay
DurationDelay between stop and start during restart
Brief pause after stopping a daemon before starting it again. Helps ensure resources (like ports) are fully released.
supervisor.cron_check_interval
DurationInterval for checking cron schedules
How often to check if any cron-scheduled daemons should be triggered.
The default of 10 seconds supports sub-minute cron schedules. Increase for lower resource usage if you don't need fine-grained scheduling.
supervisor.watch_interval
DurationFile watcher poll/refresh interval
How often the file watcher checks for filesystem changes when using watch patterns.
Lower values detect changes faster but use more CPU and I/O.
A value of "100ms" is useful for tests or highly interactive workflows;
the default "10s" is appropriate for production.
supervisor.http_client_timeout
DurationTimeout for HTTP ready checks
Maximum time to wait for a response when checking ready_http endpoints.
Increase if your services take a while to respond during startup.
supervisor.port_bump_attempts
NumberMaximum port increment attempts when auto_bump_port is enabled
When auto_bump_port = true is set on a daemon, pitchfork will try incrementing
all of the daemon's ports by the same offset to find a free range. This setting
controls how many offsets are tried before giving up with an error.
For example, with port = [3000] and port_bump_attempts = 10, pitchfork will
try ports 3000, 3001, 3002, ... up to 3009 before reporting failure.
This is a global default; individual daemons can override it with
port_bump_attempts in their daemon configuration.