pixie / docs
SOURCE GUIDE GitHub ↗
User guide

Choose a format. Keep the same settings.

Pixie accepts YAML, TOML, and JSON. Pick the format you prefer; the file extension tells Pixie how to read it, and the option names stay the same.

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?

  1. If PIXIE_CONFIG is nonempty, Pixie uses that path.
  2. Otherwise, it looks for config-pixie.yml, config-pixie.yaml, config-pixie.toml, then config-pixie.json in the working directory.
  3. Then it checks the same names under /etc/pixie/.
  4. Without a file, compiled defaults apply.

Web root lookup

  1. An existing directory selected by PIXIE_WEB_ROOT.
  2. web/ at the source manifest path, if present.
  3. /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.

Pixie documentation Built from the source. Updated with the features.