Configuration and launch

STATIC can run as a standalone binary or inside Rose. Proxy mode requires a selected profile from --profile <name> or pipeline.default_profile in TOML. --list-profiles prints the catalog without starting a listener. Profile anatomy explains the selected JSON; Build from source covers toolchain setup.

Standalone and config-driven runs

From the source checkout, after building:

./src/STATIC_proxy/target/release/static_proxy \
  --profiles-path ./src/STATIC_proxy/profiles --list-profiles
./src/STATIC_proxy/target/release/static_proxy \
  --profiles-path ./src/STATIC_proxy/profiles --profile firefox-windows

Without a config file, the CLI defaults to loopback port 8443, reserves 8444 for the disabled HTTP/3 path, and serves control on 8445. When run from src/STATIC_proxy/, an existing config/static.example.toml is loaded implicitly; that sample uses loopback proxy port 4040, a disabled HTTP/3 placeholder on 4041, and control on 4042.

cd src/STATIC_proxy
cargo run -- --config config/static.example.toml --profile edge-windows

The leading -- in cargo run -- ... separates Cargo arguments from the application’s arguments. Do not add it when invoking the binary directly. Use a browser from the same engine family as the profile; STATIC logs coherence warnings but does not enforce every match.

Config surfaces and modes

The sample TOML sets the listener, TLS keystore, pipeline.profiles_path, js_debug, alt_svc_strategy, explicit request/response/HTML body limits, disabled HTTP/3 placeholder, and telemetry. The control listener has its own bind setting and uses listener.bind_port + 2; see API authentication. A body over its configured buffer limit may fail instead of passing through unchanged. The release ZIP has a separate Windows-mounted static.runtime.toml, profiles, and token; see Distribution anatomy.

--mode proxy starts the data plane and control listener. --mode control runs the control-only sidecar. The local sample config uses a keychain keystore, while the WSL runtime TOML uses file-backed key custody inside Linux; legacy TLS path fields are compatibility inputs and the managed CA paths resolve under the app-data directory. Use GET /ca/status to locate the public certificate instead of guessing an OS-specific path. CA and trust covers private-key storage and host installation.

For local Linux or WSL eBPF development, scripts/run-static-with-ebpf-caps.sh --profile firefox-windows builds and launches STATIC with capabilities for the pinned map, using a sudo fallback on WSL. A normal cargo run can work as a proxy while map sync fails for lack of BPF permissions. See eBPF verification.

Reference provenance

The defaults below are traced to settings.rs, main.rs, and the release workflows. A config file can replace CLI defaults; relative profile/token paths resolve against the config file’s directory, while --profiles-path resolves against the current working directory.

Defaults by launch contract

0.0.0.0 is an all-interface bind in the runtime environment. Windows forwarding/firewall settings determine host exposure. The bundled example token is not installation-specific entropy. An explicitly requested Linux sample config retains its explicit keystore setting; the CLI’s Linux file-mode adjustment applies to the implicitly discovered repo sample.

Field reference

Missing optional nested fields use their serde defaults; this does not mean a TOML file can omit every top-level section. See CA and trust for managed paths and API contract for token behavior.

Implementation map

Follow Request path for the pipeline order and JavaScript runtime for the embedded bundle. The generated target/ and JS dist/ directories are build outputs, not hand-edited source.