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.

Field	Type	Default	Description
`allow`	string[]	`[]`	Paths the sandboxed process is allowed to access (read-only).
`allow_write`	string[]	`[]`	Paths bind-mounted writable into the sandbox.
`deny`	string[]	`[]`	Paths explicitly denied (checked before allow and allow_write).
`mask`	string[]	—	Paths to mask inside the sandbox (bind `/dev/null` over them).

Field	Type	Default	Description
`allow_host_loopback`	bool	`false`	Allow the sandbox to reach host loopback services through the egress proxy via the magic alias `host.canister.local`.
`allow_ips`	string[]	`[]`	Allowed IP addresses or CIDR ranges. IP-literal egress is a separate concept from FQDN egress (no service identity, no per-route shape gates apply), so it stays here rather than folding into the `[[host]]` table.
`contract_mode`	`strict` \| `relaxed` (optional)	—	Mode for hosts that have no matching `[[host]]` entry.
`egress`	`"none"`, `"proxy-only"`, `"direct"` (optional)	—
`ports`	object[]	`[]`	Port forwarding rules: map host ports to sandbox ports.

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"`.
`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.

Field	Type	Default	Description
`allow_execve`	string[]	`[]`	Paths to executables the sandboxed process may exec.
`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.
`max_pids`	integer (optional)	—	Maximum number of child PIDs allowed.

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.

Metadata section for recipe files.

Field	Type	Default	Description
`description`	string (optional)	—	One-line description of what this recipe is for.
`match_prefix`	string[]	`[]`	Path prefixes that trigger auto-detection of this recipe.
`name`	string (optional)	—	Human-readable recipe name. Defaults to the filename stem when omitted.
`version`	string (optional)	—	Opaque version string (for humans, not parsed).

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.

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).
`seccomp_mode`	`allow-list` \| `deny-list` (optional)	—	Seccomp enforcement mode.