A recipe file — the only entry point for parsing policy TOML files.
Field
Type
Default
Description
host
object[]
[]
Per-destination egress contracts. See host::HostBlock and docs/adr/0007-per-destination-egress-contracts.md. Multiple blocks targeting the same domain are merged in RecipeFile::merge (vec union, max for max_request_bytes, last-Some-wins for contract_mode).
strict
bool (optional)
—
Strict mode: fail hard instead of degrading gracefully.
Tripwires: paths where an empty decoy file is placed, read-only, so that any access to it is reported as an fs_access event (ADR-0019). Meant for well-known credential locations ($HOME/.ssh/id_ed25519, $HOME/.aws/credentials). A real grant always wins: a decoy is never placed where a read or write path, or the working directory, already provides something.
deny
string[]
[]
Paths explicitly denied (checked before read and write).
mask
string[]
—
Paths to mask inside the sandbox (bind /dev/null over them).
read
string[]
[]
Paths the sandboxed process may read (bind-mounted read-only). Read access still matters: a readable secret is exactly what the DLP layer exists to stop from leaving — name it honestly.
workdir
write | read | listed (optional)
—
How the working directory is mounted into the sandbox (ADR-0024).
Mode for hosts that have no matching [[host]] entry.
egress
none, proxy | direct (optional)
—
overlay_ca_bundles
bool (optional)
—
Add the sandbox CA to the trust bundles a client reads without SSL_CERT_FILE (ADR-0028): OpenSSL’s default bundle and certifi’s, overlaid with copies that include it. Rendered in the resolved policy only when on.
transparent
bool (optional)
—
Route a workload that ignores HTTP_PROXY through the proxy anyway (ADR-0027): names resolve to the proxy, which serves ports 443 (by TLS SNI) and 80 (by Host) in the workload’s network namespace. Rendered in the resolved policy only when on.
undeclared_hosts
refuse | sink (optional)
—
Handling of a request whose host no [[host]] block declares (ADR-0018). Both modes keep the request from leaving the proxy; they differ in how much of it the proxy looks at.
Data Loss Prevention configuration for the egress proxy.
Field
Type
Default
Description
bind_credentials
bool (optional)
—
Refuse a request to a host a credential is scoped to when it carries a credential other than the fake the sandbox was given: one the workload brought itself (ADR-0030). Default: false. Any layer turning it on wins.
canary_tokens
bool (optional)
—
Inject canary tokens (fake credentials) into the sandbox environment to detect exfiltration attempts. Default: true when DLP is enabled.
decompress
bool (optional)
—
Decompress request bodies (gzip/deflate/brotli) before scanning. Default: true.
dns_entropy_threshold
number (optional)
—
Normalised per-label entropy ratio for DNS exfiltration detection. A label’s Shannon entropy is divided by log2(len) to get a value in [0.0, 1.0]; the FQDN trips when two or more labels exceed this ratio. Default: 0.92. (Pre-2026-05 configs used absolute bits — those values are now clamped to 1.0 and effectively disable the check.)
enabled
bool (optional)
—
Enable DLP scanning. Implicitly enabled in --strict mode when egress = "proxy-only".
external_canaries
object[]
[]
Canaries supplied from outside the sandbox — values an orchestrator planted in the workload’s input data, each tagged with the class of data it stands for and the destinations that are allowed to see it. Unlike generated canary tokens, these are never injected into the environment: can only learns to recognize them on egress. See ADR-0012.
fake_secrets
object[]
[]
Env-var secrets the sandbox should never see in cleartext. For each entry the sandbox is given a fake value (matching the named credential’s format); the proxy swaps it for the real host value only on egress to a host authorized for that credential ([[host]] allow_credentials / the detector’s home domains). A secret the sandbox encrypts and exfiltrates therefore only ever leaks the useless fake. See docs/refusals.md.
max_decode_depth
integer (optional)
—
Maximum encoding chain recursion depth (base64, hex, percent-encoding). Default: 32.
session_entropy_budget
integer (optional)
—
Cumulative high-entropy bytes allowed per sandbox session before requests are blocked. Default: 8192.
Maximum bytes buffered for DLP body scanning via the full whole-buffer pipeline (decode chains, decompression, unescape). Requests at or under this size get the strongest analysis. Default 8 MiB. Requests above this size up to [Self::max_streamed_body_bytes] are still scanned but via the chunked streaming path (regex only, no decode chain).
max_streamed_body_bytes
integer (optional)
—
Hard upper bound on request body size. Beyond this, the proxy returns 413. Defaults to 64 MiB. Requests between [Self::max_buffered_body_bytes] and this cap are scanned by the streaming detector: regex passes with a 256-byte overlap window, no decompression / decode chain.
upstream_request_timeout_ms
integer (optional)
—
Upstream request total timeout in milliseconds. Defaults to 30 000 ms.
upstream_scheme
string (optional)
—
Force the upstream request scheme. Accepts "http" or "h2c". When unset (the default), the scheme is inferred from the inbound request URI. Prior versions consulted a client-controlled x-canister-upstream-scheme header for this — that was a footgun (the sandboxed process picked the proxy’s egress protocol) and is no longer honoured. h2c also requires the experimental-h2c build feature; without it, setting this to "h2c" returns an upstream error.
Forward host ports into the sandbox (inbound exposure). [ip:]hostPort:containerPort[/protocol]. Was [network] ports.
extra_syscalls
string[]
[]
High-risk syscalls to add to the allow list. These widen the kernel attack surface (e.g. ptrace, bpf, mount, io_uring_*) and are rejected from [syscalls] allow_extra — they must be declared here so the cost is explicit. See [super::syscalls::DANGEROUS_SYSCALLS].
host_loopback
bool
false
Let the sandbox reach host loopback services via the host.canister.local alias — opens host-local daemons (DBs, sockets) to sandboxed code. Was [network] allow_host_loopback.
reachable_ips
string[]
[]
IP addresses / CIDRs the sandbox may reach directly. IP-literal egress carries no service identity and bypasses the per-host contract and DLP gates. Was [network] allow_ips.
seccomp_default_allow
bool
false
Flip seccomp to default-allow (deny-list): every syscall is permitted unless explicitly denied — the inverse of the secure default. Was [syscalls] seccomp_mode = "deny-list".
unfiltered_egress
bool
false
Bypass the L7 egress proxy: outbound is direct, so DLP and per-host contract gates do not run. Only the IP/policy layer applies. Was [network] egress = "direct".