YAML · config-pixie.yml
addr: 0.0.0.0:8080
workers: 4
TOML · config-pixie.toml
addr = "0.0.0.0:8080"
workers = 4
JSON · config-pixie.json
{
"addr": "0.0.0.0:8080",
"workers": 4
}
PIXIE_CONFIG=./config-pixie.toml PIXIE_WEB_ROOT=./my-site cargo run --locked
Replace the filename with the YAML or JSON file you saved. Accepted extensions are .yml, .yaml, .toml, and .json. Relative paths are resolved from the process working directory; use absolute paths in services and containers.
Configuration reference
| Setting | Default | Meaning |
|---|---|---|
addr
|
127.0.0.1:80
|
Full listen address. Takes priority over host and port. |
host
|
127.0.0.1
|
Used with port when addr is absent. |
port
|
80
|
TCP listen port. |
workers
|
4
|
Connection worker count. Zero falls back to 4. |
tls.cert_file
|
Absent | Required PEM certificate chain when tls is present. |
tls.key_file
|
Absent | Required unencrypted PEM private key. |
tls.client_ca_file
|
Absent | Trusted client CAs; setting it requires client certificates. |
http3.addr |
Absent | Optional QUIC/UDP listen address. Requires TLS; HTTP/3 support is experimental. |
address is an alias for addr; nb_worker is an alias for workers. Port 80 may require elevated privileges; prefer 8080 for local use. The shipped sample configuration uses 8080.
To enable experimental HTTP/3, configure TLS and add http3: { addr: "0.0.0.0:8443" }. Expose that port over UDP in the host firewall and deployment. See the TLS guide.
Which file is loaded?
- If
PIXIE_CONFIGis nonempty, Pixie uses that path. - Otherwise, it looks for
config-pixie.yml,config-pixie.yaml,config-pixie.toml, thenconfig-pixie.jsonin the working directory. - Then it checks the same names under
/etc/pixie/. - Without a file, compiled defaults apply.
Web root lookup
- An existing directory selected by
PIXIE_WEB_ROOT. -
web/at the source manifest path, if present. -
/usr/share/pixie/web.
An invalid PIXIE_WEB_ROOT produces a warning and uses the fallback. Set it explicitly for custom sites. Restart Pixie after changing config or TLS files; page files are read on each request.