Struct SettingsProxy 

pub struct SettingsProxy {

    pub auto_start: bool,
    pub auto_start_timeout: String,
    pub auto_trust: bool,
    pub enable: bool,
    pub host: String,
    pub https: bool,
    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

When enabled (default), visiting a proxy URL for a stopped daemon will automatically start that daemon. The browser receives a “Starting…” page that refreshes every 2 seconds until the daemon is ready, at which point the request is proxied normally.

Set to false to disable auto-start and return a plain 502 error for stopped daemons (the previous behaviour).

auto_start_timeout: String

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

When a daemon is auto-started via a proxy request, the proxy waits up to this duration for the entire auto-start operation to complete — including waiting for the daemon’s readiness signal and detecting the bound port.

If the daemon does not become ready and bind a port within this timeout, the browser receives an error page indicating the startup timed out.

Examples:

• "15s" - Shorter timeout for fast-starting services
• "30s" - Default, suitable for most daemons
• "60s" - For daemons with slow initialisation (e.g. large Java apps)

auto_trust: bool

Automatically install the proxy TLS certificate into the system trust store

When enabled (default), pitchfork automatically installs the proxy’s self-signed CA certificate into the system trust store during supervisor startup, so that browsers and tools trust HTTPS proxy URLs without certificate warnings.

On macOS, this triggers a system authorization dialog (Touch ID or password). On Linux, this requires write access to the system CA directory (typically needs sudo).

If auto-trust fails (e.g. due to permissions), it is silently skipped and a warning is logged. You can manually install the certificate with: pitchfork proxy trust

Set to false to disable auto-trust entirely.

enable: bool

Enable the reverse proxy server for daemons

When enabled, pitchfork starts a reverse proxy that routes requests from <slug>.<tld>:<port> to the daemon’s actual listening port.

Only daemons with an explicit slug are routable through the proxy. No slug = not proxied.

Example: myapp.localhost:7777 -> localhost:3000 (daemon with slug = “myapp”)

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).

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.

Ports below 1024 require the supervisor to be started with elevated privileges (e.g. sudo pitchfork supervisor start).

sync_hosts: bool

Automatically sync slug hostnames to /etc/hosts

When enabled (default), pitchfork automatically adds entries to /etc/hosts for registered slugs (e.g. 127.0.0.1 myapp.localhost) so that browsers can resolve them.

This is needed because Safari does not auto-resolve .localhost subdomains, and custom TLDs (e.g. .test) always require DNS entries.

Entries are managed in a marked block in /etc/hosts and cleaned up when the proxy shuts down. Writing to /etc/hosts may require sudo.

Set to false to disable automatic hosts file management. You will need to configure DNS resolution yourself (e.g. dnsmasq, /etc/resolver/ on macOS).

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: myapp.localhost:7777 (for a daemon with slug = “myapp”)

For custom TLDs (e.g. test), you need wildcard DNS resolution. On macOS, you can use dnsmasq or add entries to /etc/resolver/.

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.

If left empty and proxy.https = true, pitchfork will auto-generate a self-signed certificate and store it in $PITCHFORK_STATE_DIR/proxy/cert.pem.

tls_key: String

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

Path to a PEM-encoded private key file used when proxy.https = true.

If left empty and proxy.https = true, pitchfork will auto-generate a self-signed key and store it in $PITCHFORK_STATE_DIR/proxy/key.pem.

wildcard: bool

Enable wildcard subdomain matching for proxy routes

When enabled (default), requests for subdomains of a registered slug will fall back to the parent slug’s daemon.

For example, with slug “myapp”:

• myapp.localhost → exact match (always works)
• tenant.myapp.localhost → wildcard fallback to “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