pitchfork

The Log Viewer provides real-time access to daemon logs. Features include:

• Streaming: Real-time log streaming with a 'follow mode' (auto-scroll).
• Navigation: Search within logs and jump to the top (g) or bottom (G) of the buffer.
• View Modes: Toggle an expanded full-screen view for better readability.

Pitchfork loads configuration files in a specific order where later files override earlier ones. This allows for global defaults that can be overridden by user-specific or project-specific settings.

Loading Order

1. System-level: /etc/pitchfork/config.toml (namespace: global)
2. User-level: ~/.config/pitchfork/config.toml (namespace: global)
3. Project-level: Files are searched from the filesystem root down to the current directory in this order:
   • .config/pitchfork.toml (lowest precedence in directory)
   • .config/pitchfork.local.toml (overrides .config/pitchfork.toml)
   • pitchfork.toml (overrides everything in .config/)
   • pitchfork.local.toml (highest precedence in directory; typically not committed to version control)

This hierarchy mirrors mise behavior.

Pitchfork uses a graceful shutdown strategy when running pitchfork stop:

1. SIGTERM: It sends a SIGTERM and waits up to the stop_timeout (default 5 seconds) for the process to exit.
2. SIGKILL: If the process does not exit within the timeout, it sends a SIGKILL to force termination.

If your daemon takes longer than 3 seconds to stop, it may be ignoring SIGTERM or performing slow cleanup.

Testing signal handling: You can test if your daemon responds to SIGTERM by manually sending the signal to its PID:

kill -TERM $(pitchfork status myapp --json | jq .pid)

Debugging shutdown timing: Start the supervisor with debug logs, stop your app, and grep the supervisor logs for termination signals:

PITCHFORK_LOG=debug pitchfork supervisor start --force
pitchfork stop myapp
pitchfork logs pitchfork | grep -i "sigterm\|sigkill\|terminated"

The auto option in pitchfork.toml accepts an array of strings to define daemon lifecycle rules:

• ["start"]: The daemon starts automatically when you cd into the project directory.
• ["stop"]: The daemon stops automatically when you cd out of the project directory.
• ["start", "stop"]: The daemon both starts on entry and stops on exit.

Lifecycle Logic:

1. Entering a directory with auto = ["start", ...] triggers daemon startup.
2. Leaving a directory with auto = [..., "stop"] marks the daemon for stopping.
3. Pitchfork implements a delay before stopping to handle quick directory switches.
4. Daemons only stop if no other active terminal sessions remain in that directory.

The Dashboard view provides a live overview of your daemons. Key capabilities include:

• Monitoring: View live daemon status (color-coded), CPU usage, and memory usage per daemon.
• Filtering: Use fuzzy search to filter the list of daemons.
• Sorting: Use sortable columns to organize the view.
• Batch Operations: Use Space to select multiple daemons, then perform actions like starting, stopping, or restarting them all at once.

The Config Editor allows you to manage daemon definitions through a form-based interface. You can:

• Create new daemons.
• Edit existing daemon configurations.
• Delete daemons from configuration files.
• Benefit from built-in validation for required fields and formats.

Authentication requirements depend on the bind_address used:

• Loopback only (127.0.0.1, ::1): No authentication is required.
• Non-loopback (e.g., 0.0.0.0, LAN IP): A 64-character hex token is auto-generated at startup and printed to stderr. You must include this token in the X-Pitchfork-Token header for all requests.

You can also define a fixed token in your configuration under [settings.api].token to avoid using the auto-generated one.

# Example using a token for a non-loopback address
curl -H "X-Pitchfork-Token: <token>" http://192.168.1.100:3120/api/daemons

Templates are rendered level-by-level following the dependency graph:

1. Level 0: Daemons with no dependencies (start first).
2. Level 1: Daemons depending on Level 0 (can reference Level 0).
3. Level 2: Daemons depending on Level 1 (can reference Level 0 and 1).

Important Rules:

• Concurrency: Daemons within the same level start concurrently and cannot reference each other's ports via templates.
• Self-Reference Limitation: A daemon's own port and ports are not available at template rendering time because ports are resolved after the command is constructed. To access the current daemon's own resolved ports, use the $PORT, $PORT0, $PORT1, etc., environment variables.
• Dependency Requirement: Use {{ daemons.xxx.port }} to reference the ports of your dependencies.

A 'Ready Check' allows Pitchfork to determine when a service is actually functional, rather than just when the process has started. You can use the ready_http key in your configuration to point to a health check endpoint. Pitchfork will wait for this endpoint to become available before considering the daemon 'ready'.

[daemons.api]
run = "npm run server"
ready_http = "http://localhost:3000/health"

Pitchfork uses several methods to determine if a daemon has successfully started and is ready to receive traffic. The first check to succeed marks the daemon as ready.

• Delay: Waits for a fixed number of seconds. This is only used if no other check type is configured.
• Output: Matches a regex against stdout or stderr.
• HTTP: Checks if a specific endpoint returns a 2xx status code.
• Port: Checks if a TCP port is listening.
• Command: Executes a shell command; success is defined by an exit code of 0.