Configuration Reference

This file is auto-generated by can-docgen. Do not edit manually.

Canister uses TOML recipe files with strict schema validation. Unknown fields are rejected at parse time.

Top-level fields

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.

`[filesystem]`

Field	Type	Default	Description
`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.
`write`	string[]	`[]`	Paths bind-mounted writable into the sandbox.

`[network]`

Field	Type	Default	Description
`contract_mode`	`strict` \| `relaxed` (optional)	—	Mode for hosts that have no matching `[[host]]` entry.
`egress`	`none`, `proxy` \| `direct` (optional)	—

`[network.dlp]`

Data Loss Prevention configuration for the egress proxy.

Field	Type	Default	Description
`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"`.
`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.

`[process]`

Field	Type	Default	Description
`env`	object	`{}`	Environment variables to set in the sandbox. These are evaluated after passthrough.
`env_passthrough`	string[]	`[]`	Environment variables to pass through from the host. All others are stripped.
`exec`	any (optional)	—	Which binaries the sandboxed process may `exec`.
`max_pids`	integer (optional)	—	Maximum number of child PIDs allowed.

`[proxy]`

Field	Type	Default	Description
`max_buffered_body_bytes`	integer (optional)	—	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.

`[recipe]`

Metadata section for recipe files.

Field	Type	Default	Description
`description`	string (optional)	—	One-line description of what this recipe is for.
`name`	string (optional)	—	Human-readable recipe name. Defaults to the filename stem when omitted.
`suggests`	string[]	`[]`	Other recipe names that compose naturally with this one.
`version`	string (optional)	—	Opaque version string (for humans, not parsed).

`[resources]`

Field	Type	Default	Description
`cpu_percent`	integer (optional)	—	CPU limit as a percentage (e.g., 50 = 50% of one core).
`memory_mb`	integer (optional)	—	Memory limit in megabytes.

`[syscalls]`

Syscall customization.

Field	Type	Default	Description
`allow`	string[]	`[]`	Absolute allow list — the complete set of permitted syscalls. Only valid in `default.toml`. Mutually exclusive with `allow_extra`.
`allow_extra`	string[]	`[]`	Syscalls to add to the allow list (on top of the default baseline).
`deny`	string[]	`[]`	Absolute deny list — syscalls always blocked. Only valid in `default.toml`. Mutually exclusive with `deny_extra`.
`deny_extra`	string[]	`[]`	Syscalls to add to the deny list (also removed from allow list).
`notifier`	bool (optional)	—	Enable the SECCOMP_RET_USER_NOTIF supervisor for argument-level syscall filtering (connect, clone, socket, execve).

`[unsafe]`

Field	Type	Default	Description
`expose_ports`	object[]	`[]`	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"`.

Keyboard shortcuts

Canister Documentation