Struct SettingsProxy 

pub struct SettingsProxy {

    pub auto_start: bool,
    pub auto_start_timeout: String,
    pub auto_trust: bool,
    pub dns: bool,
    pub dns_port: i64,
    pub enable: bool,
    pub host: String,
    pub https: bool,
    pub idle_timeout: String,
    pub lan: bool,
    pub lan_ip: String,
    pub port: i64,
    pub sync_hosts: bool,
    pub tld: String,
    pub tls_cert: String,
    pub tls_key: String,
    pub wildcard: bool,
}

The proxy.* settings.

Fields

auto_start: bool

Automatically start daemons when accessed via proxy URL

Enabled by default. Opening a stopped daemon’s proxy URL starts its depends dependencies first, using the same startup order and readiness checks as pitchfork start. Oneshot dependencies must complete successfully.

The first request waits for startup. Additional requests to the same daemon receive a “Starting…” page that refreshes every two seconds until it is ready. Opening a project or stack page does not start any daemons.

Set to false to return a 502 error for stopped daemons and require manual startup.

auto_start_timeout: String

Maximum time to wait for an auto-started daemon to become ready

Limits how long a proxy request waits for dependency startup, readiness checks, and detection of the daemon’s bound port. Defaults to 30 seconds.

On timeout, the request receives an error page, but startup continues in the background. Reload to check again, or increase this setting for a longer startup sequence, for example "60s".

auto_trust: bool

Automatically trust the generated proxy CA certificate

When enabled (default), pitchfork attempts to install its generated CA certificate into the system trust store during HTTPS proxy startup.

On macOS, this triggers a system authorization dialog (Touch ID or password). On Linux, use pitchfork proxy setup to install the CA with sudo while keeping the supervisor unprivileged.

If auto-trust fails, pitchfork logs a warning and continues starting the proxy. Use pitchfork proxy doctor to check trust, or pitchfork proxy trust to install the CA manually (with sudo on Linux).

Set to false to disable auto-trust entirely.

dns: bool

Run a loopback DNS resolver for the proxy TLD

While the proxy is running, answer UDP and TCP DNS queries on 127.0.0.1:<proxy.dns_port> for names under proxy.tld, including nested project and worktree hostnames. Answers follow proxy.host, or the LAN IPv4 address in LAN mode. Names outside the TLD receive REFUSED; queries are never forwarded.

Run pitchfork proxy setup to configure system resolution separately. Set to false when using another resolver or when DNS is not needed.

dns_port: i64

Port the loopback DNS resolver listens on

The resolver binds 127.0.0.1:<dns_port> on both UDP and TCP.

The default avoids privileged port 53 and the mDNS port, 5353.

enable: bool

Enable the reverse proxy server for daemons

When enabled, pitchfork starts a reverse proxy that routes a stable hostname to the daemon’s actual listening port.

Every daemon with a port gets a hostname built from its name, its worktree when it lives in one, and its project, unless it opts out with proxy = false. A daemon without a port is not routed.

Example: api.myproject.localhost:7777 -> localhost:3000

host: String

Bind address for the reverse proxy server

IP address the reverse proxy listens on.

Security Warning: The default 127.0.0.1 only allows local connections. Setting this to 0.0.0.0 will expose the proxy on every network interface, including externally routable ones – anyone on the same LAN can then reach your local daemons.

Examples:

• "127.0.0.1" - Local only (default, recommended)
• "0.0.0.0" - All interfaces (use with caution)
• "::1" - IPv6 loopback

https: bool

Enable HTTPS for the reverse proxy

When enabled (default), the proxy serves HTTPS instead of HTTP.

You must also configure proxy.tls_cert and proxy.tls_key, or pitchfork will auto-generate a self-signed certificate stored in the state directory.

Set to false to use plain HTTP (e.g. for simple local development).

idle_timeout: String

Stop proxy-started daemons after this long without proxy activity

Disabled by default: an empty string or "0" disables the default timeout. Set a duration such as "15m" or "1h" to enable idle shutdown for daemons started through their proxy URL. A daemon’s proxy_idle_timeout overrides this setting; dependencies without an override inherit the requested daemon’s timeout.

HTTP requests count until their response ends. Streaming responses, WebSockets, and TLS passthrough connections keep a daemon active while open. DNS lookups, idle keep-alive connections, and traffic sent directly to the daemon’s port do not count.

Only proxy-started daemons are eligible. Explicitly starting a daemon exempts it and its dependencies from idle shutdown. Live dependents and tracked shell sessions also prevent shutdown.

Eligibility is checked every general.interval (10 seconds by default). Dependencies stop after their dependents; shutdown may take longer than the idle timeout. The timeout is recorded at startup, and activity tracking resets after a supervisor restart.

lan: bool

Enable LAN mode for the reverse proxy

When enabled, the proxy switches to the .local TLD and publishes slug hostnames via mDNS so that other devices on the same network can reach your daemons (e.g. myapp.local from a phone or another computer).

LAN mode:

• Forces proxy.tld to local (mDNS requirement)
• Publishes each slug as an mDNS address record (<slug>.local → <LAN-IP>)
• Binds the proxy to 0.0.0.0 instead of 127.0.0.1 (overridable via proxy.host)
• Auto-detects your LAN IP and re-publishes mDNS records if it changes

Other devices must trust the pitchfork CA certificate to use HTTPS. Run pitchfork proxy trust on each device, or use proxy.https = false.

lan_ip: String

Pin a specific LAN IP address instead of auto-detecting

When set, skips auto-detection and uses this IP for mDNS publishing. Implies proxy.lan = true if a non-empty value is provided.

port: i64

Port the reverse proxy server listens on

The port pitchfork’s reverse proxy binds to. Must be in the range 1-65535.

Default is 443 (standard HTTPS port) since the proxy defaults to HTTPS. Users can override this to any port (e.g. 7777) to avoid requiring elevated privileges.

To use standard ports without running the supervisor as root, choose an unprivileged listener such as 8443 and run pitchfork proxy setup to redirect local traffic on macOS or Linux. On Linux, setup can also grant permission to bind ports below 1024 directly.

sync_hosts: bool

Automatically sync slug hostnames to /etc/hosts (deprecated)

Deprecated and scheduled for removal after one release. Run pitchfork proxy setup, check resolution with pitchfork proxy doctor, then set sync_hosts = false. The loopback DNS resolver supports nested hostnames without per-host entries.

When enabled (default), pitchfork adds entries to /etc/hosts for registered slugs (e.g. 127.0.0.1 myapp.localhost) so that browsers can resolve them. Entries are managed in a marked block and cleaned up when the proxy shuts down. Writing to /etc/hosts may require sudo, and it only ever covers registered slugs, never wildcard names.

tld: String

Top-level domain used for proxy URLs

The TLD appended to daemon hostnames in proxy URLs.

With the default localhost, daemon URLs look like: api.myproject.localhost:7777 (daemon api of project myproject)

Run pitchfork proxy setup to configure system resolution, including for custom TLDs such as test, or use --pac for applications that honor automatic proxy settings. Restart the supervisor after changing the TLD.

tls_cert: String

Path to TLS certificate file (PEM format) for HTTPS proxy

Path to a PEM-encoded TLS certificate file used when proxy.https = true. It is served as-is for every hostname, and must match proxy.tls_key.

If left empty and proxy.https = true, pitchfork generates a local certificate authority at $PITCHFORK_STATE_DIR/proxy/ca.pem and signs a certificate per hostname from it on the first TLS handshake, caching them in $PITCHFORK_STATE_DIR/proxy/host-certs/. Trusting the CA once with pitchfork proxy trust covers every proxy hostname.

With a custom certificate, pitchfork serves that certificate without signing per-hostname certificates. It must cover every hostname you use, and clients must trust its issuer. Setup skips CA installation; set proxy.auto_trust = false to also disable startup CA trust.

tls_key: String

Path to TLS private key file (PEM format) for HTTPS proxy

Path to a PEM-encoded private key file matching proxy.tls_cert. The pair is checked at startup, so a mismatch is reported rather than failing every handshake.

If left empty and proxy.https = true, pitchfork generates a CA key at $PITCHFORK_STATE_DIR/proxy/ca-key.pem instead. See proxy.tls_cert.

wildcard: bool

Enable wildcard subdomain matching for proxy routes

When enabled (default), extra labels to the left of a daemon’s hostname route to that same daemon.

For example, with a daemon reachable at api.myproject.localhost:

• api.myproject.localhost → exact match (always works)

• tenant.api.myproject.localhost → wildcard fallback to the same daemon

The same holds for a legacy slug, where tenant.myapp.localhost falls back to the slug myapp.

This is useful for multi-tenant apps where each tenant gets a unique subdomain (e.g. acme.myapp.localhost, globex.myapp.localhost) but all share the same backend server.

Set to false to require exact hostname matches only.

Implementations

impl SettingsProxy

pub const SETTINGS_PROPS: &'static [PropMeta] = <Self as ::usage_config::Props>::PROPS

Every setting this struct declares, one entry per field, flattened groups included. The registry a build.rs used to generate, generated from the struct instead — there is no second declaration to keep in step.

pub const SETTINGS_REGISTRY: Registry

The registry over Self::SETTINGS_PROPS, for resolve, drift, and the layers.

pub const SETTINGS_SPEC: ConfigSpec

Metadata used only when lowering this declaration into a usage spec.

pub fn read(__usage_resolved: &Resolved) -> Result<Self, ReadErrors>

This resolution’s values, as the struct.

Every field is read before anything is returned, so the error is the whole list of what is wrong rather than the first thing found.

pub fn read_lossy(__usage_resolved: &Resolved) -> (Option<Self>, ReadErrors)

This resolution’s values, keeping every setting that reads.

Self::read is all or nothing, which leaves a CLI two moves when one field is bad: refuse to start, or fall back to a struct of declared defaults and lose the environment and every config file along with the offending value. Neither is a choice this crate should be making.

So: a field that will not read falls back to its own declared default and the rest keep what the merge gave them, with every failure returned alongside for the CLI to raise, log, or ignore as it sees fit. The errors are the same ::usage_config::ReadErrors Self::read returns, so a caller that decides a bad value is fatal has lost nothing by asking.

None only where a setting has no value and no declared default — a hole in the declaration rather than a bad value, and nothing to fall back to.

pub fn spec_kdl() -> String

The spec config block for these settings, as KDL.

What documents, JSON schema and completions read. A CLI deriving usage::Cli names this type in #[usage(config = ...)] instead of calling this, and its to_kdl carries the block.

Trait Implementations

impl Clone for SettingsProxy

fn clone(&self) -> SettingsProxy

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for SettingsProxy

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl PartialEq for SettingsProxy

fn eq(&self, other: &SettingsProxy) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl Props for SettingsProxy

const PROPS: &'static [PropMeta]

This group’s settings, in declaration order.

const PROP_SPECS: &'static [PropSpec]

Spec-only metadata parallel to Props::PROPS.

impl StructuralPartialEq for SettingsProxy