Flocks reads typed configuration from a TOML file. Each binary (flocks dev, flocks gateway, flocks roost) accepts --config and falls back to a sensible default for the mode.

​
Gateway

gateway.toml
bind = "0.0.0.0:7700"
data_dir = "./data/gateway"

[auth]
adapter = "local"   # local | mtls | oidc
local_token = "desktop-gateway"

[transport]
adapter = "tailscale"   # tailscale | wireguard | none

[tls]
cert = "/etc/flocks/certs/gateway.pem"
key  = "/etc/flocks/certs/gateway.key"
The local auth adapter accepts any non-empty token and is only valid on a loopback bind (127.0.0.1 / ::1). Starting a gateway with local on a non-loopback bind is a startup error — Flocks fails closed.

​
Roost

roost.toml
bind = "100.64.0.1:7878"
gateway_url = "https://gateway.flocks.local"
join_token = "<base64>"

[isolation]
class = "process"   # process | jail | microvm

[drivers]
enabled = ["claude", "codex", "gemini", "shell"]

​
Environment variables

VariableDefaultWhat it does
FLOCKS_BIND127.0.0.1:7700Override the gateway/roost bind.
FLOCKS_DATA_DIR./dataCoordinator + audit storage.
FLOCKS_LOGinfotracing filter (e.g. flocks=debug,axum=warn).
FLOCKS_REGISTRYhttps://download.flocks.shWhere flocks-publish ships releases.

​
Where things live

PathContents
~/.local/bin/flocksThe CLI binary (installed by install.sh).
~/.config/flocks/User-scoped TOML config + persisted gateway URL.
./data/gateway/Coordinator state, hash-chained audit log.
./data/roost/Run journals, capability cache, last grants.