CLI Reference
This file is auto-generated by
can-docgen. Do not edit manually.
can
Canister: a lightweight sandbox for running untrusted code safely
Usage: can [OPTIONS] <COMMAND>
Commands:
up Run a named sandbox from canister.toml
run Run a command inside the sandbox
check Check available kernel capabilities for sandboxing
setup Install or manage the security policy (AppArmor/SELinux) for filesystem isolation
lock Pin the recipes canister.toml's sandboxes compose (ADR-0026)
keygen Generate an Ed25519 key for --events-sign-key (ADR-0021)
pubkey Print the public key of an --events-sign-key seed file
recipe Manage and inspect recipes
init Download community recipes to the local config directory
update Update community recipes from the remote repository
help Print this message or the help of the given subcommand(s)
Options:
-v, --verbose Enable verbose (debug) logging
-h, --help Print help
-V, --version Print version
can run
Run a command inside the sandbox
Usage: can run [OPTIONS] <COMMAND>...
Arguments:
<COMMAND>...
The command to execute
Options:
-r, --recipe <RECIPE>
Recipe name or path. Can be repeated for composition.
If the argument contains `/` or ends with `.toml`, it is treated as a file path. Otherwise it is looked up by name across the recipe search path (e.g., `-r nix` resolves to `nix.toml`).
Multiple recipes are merged left-to-right.
-v, --verbose
Enable verbose (debug) logging
-m, --monitor
Run in monitor mode: log access attempts without enforcing
-s, --strict
Strict mode: fail hard on all setup failures. Seccomp uses KILL_PROCESS, filesystem isolation failures are fatal. Intended for CI / production use
-p, --port <PORTS>
Publish a container port to the host.
Syntax: [ip:]hostPort:containerPort[/protocol] Examples: -p 8080:80, -p 127.0.0.1:8443:443/tcp, -p 5000:5000/udp Can be repeated. Implies filtered network mode.
--canaries-file <PATH>
JSON file of externally supplied, tagged canaries to watch for on egress (ADR-0012). Same shape as `[[network.dlp.external_canaries]]`
--events-socket <PATH>
Stream structured run events to a Unix socket (SOCK_STREAM).
`can` connects as a client; the consumer listens. One connection per emitting process. Schema: docs/events-schema-v1.json.
--events-file <PATH>
Append structured run events to a file as JSON lines
--run-id <ID>
Run identifier stamped on every event. Defaults to a generated id
--capture-exchanges
Emit an `exchange` event per HTTP exchange through the proxy: request and response headers, bodies and timings (ADR-0011).
Credential headers and configured secrets are always redacted.
--capture-max-bytes <BYTES>
Per-body capture cap in bytes. Larger bodies are truncated and flagged with `truncated: true`
[default: 1048576]
--capture-readable-encodings
Offer upstreams only encodings that zlib decodes (gzip, deflate, identity), so captured responses stay readable to any consumer (ADR-0023). The captured request keeps what the workload asked for
--stats-interval-ms <MS>
How often the proxy emits a cumulative `stats` event, in milliseconds (ADR-0015). `0` disables periodic stats; a final snapshot is still emitted when the run ends
[default: 5000]
--events-sign-key <PATH>
Sign each stream's closing seal with this Ed25519 key, so a consumer can tell the bytes `can` wrote from bytes produced afterwards (ADR-0016).
The file holds 32 raw bytes or 64 hex characters; `can keygen` writes one and `can pubkey` prints the public key a consumer trusts (ADR-0021). The sandboxed workload never sees it: it is read before the namespace is entered and never enters the child's environment.
--print-policy
Print the resolved policy this run would enforce, with the `policy_sha256` its `policy_resolved` event would carry, as one line of JSON, and exit without starting a sandbox (ADR-0033)
-h, --help
Print help (see a summary with '-h')
-V, --version
Print version
can up
Run a named sandbox from canister.toml.
Discovers canister.toml by walking up from the current directory, resolves the named sandbox (or the first-defined one), composes its recipes, and runs the command.
Usage: can up [OPTIONS] [NAME]
Arguments:
[NAME]
Sandbox name to run (defaults to the first defined in canister.toml)
Options:
--recipe <PATH>
Extra recipe to merge on top of the sandbox definition.
Repeatable, merged after the manifest so it wins. For policy a caller generates per run — routing a declared host to a local mock, say. Like any recipe that is not pinned by checksum, it cannot grant credential scope; that belongs in canister.toml.
-v, --verbose
Enable verbose (debug) logging
--dry-run
Preview the resolved policy without running the sandbox
-m, --monitor
Run in monitor mode: log access attempts without enforcing
-s, --strict
Override strict mode from the CLI
-p, --port <PORTS>
Publish a container port to the host.
Syntax: [ip:]hostPort:containerPort[/protocol] Can be repeated. Implies filtered network mode.
--canaries-file <PATH>
JSON file of externally supplied, tagged canaries to watch for on egress (ADR-0012). Same shape as `[[network.dlp.external_canaries]]`
--events-socket <PATH>
Stream structured run events to a Unix socket (SOCK_STREAM).
`can` connects as a client; the consumer listens. One connection per emitting process. Schema: docs/events-schema-v1.json.
--events-file <PATH>
Append structured run events to a file as JSON lines
--run-id <ID>
Run identifier stamped on every event. Defaults to a generated id
--capture-exchanges
Emit an `exchange` event per HTTP exchange through the proxy: request and response headers, bodies and timings (ADR-0011).
Credential headers and configured secrets are always redacted.
--capture-max-bytes <BYTES>
Per-body capture cap in bytes. Larger bodies are truncated and flagged with `truncated: true`
[default: 1048576]
--capture-readable-encodings
Offer upstreams only encodings that zlib decodes (gzip, deflate, identity), so captured responses stay readable to any consumer (ADR-0023). The captured request keeps what the workload asked for
--stats-interval-ms <MS>
How often the proxy emits a cumulative `stats` event, in milliseconds (ADR-0015). `0` disables periodic stats; a final snapshot is still emitted when the run ends
[default: 5000]
--events-sign-key <PATH>
Sign each stream's closing seal with this Ed25519 key, so a consumer can tell the bytes `can` wrote from bytes produced afterwards (ADR-0016).
The file holds 32 raw bytes or 64 hex characters; `can keygen` writes one and `can pubkey` prints the public key a consumer trusts (ADR-0021). The sandboxed workload never sees it: it is read before the namespace is entered and never enters the child's environment.
--print-policy
Print the resolved policy this run would enforce, with the `policy_sha256` its `policy_resolved` event would carry, as one line of JSON, and exit without starting a sandbox (ADR-0033)
-h, --help
Print help (see a summary with '-h')
-V, --version
Print version
can check
Check available kernel capabilities for sandboxing
Usage: can check [OPTIONS]
Options:
-v, --verbose Enable verbose (debug) logging
-h, --help Print help
-V, --version Print version
can setup
Install or manage the security policy (AppArmor/SELinux) for filesystem isolation
Usage: can setup [OPTIONS]
Options:
--remove
Remove the security policy instead of installing it
-v, --verbose
Enable verbose (debug) logging
-f, --force
Force reinstall even if the policy is already installed. Useful after upgrading canister to pick up policy changes
--pasta-path <PASTA_PATH>
Explicit path to the pasta binary for non-standard installations.
When pasta is installed via Nix, Homebrew, or custom builds, sudo may not find it in PATH. Use this to generate correct AppArmor rules: sudo can setup --pasta-path $(which pasta)
-h, --help
Print help (see a summary with '-h')
-V, --version
Print version
can recipe
Manage and inspect recipes
Usage: can recipe [OPTIONS] <COMMAND>
Commands:
list List available recipes and the default baseline syscall counts
show Show the fully resolved recipe as TOML
explain Explain what a recipe does in human-readable form
suggest Suggest recipes for a command
help Print this message or the help of the given subcommand(s)
Options:
-v, --verbose Enable verbose (debug) logging
-h, --help Print help
-V, --version Print version
can init
Download community recipes to the local config directory.
Clones the canister GitHub repository (shallow) and copies recipe .toml files into $XDG_CONFIG_HOME/canister/recipes/. Requires git. Prints manual instructions if git is unavailable.
Usage: can init [OPTIONS]
Options:
--repo <REPO>
GitHub repository (owner/repo) to fetch from
-v, --verbose
Enable verbose (debug) logging
--branch <BRANCH>
Branch to fetch
--no-verify
Skip SHA-256 checksum verification of recipe files. Required when using custom/forked repositories
-h, --help
Print help (see a summary with '-h')
-V, --version
Print version
can update
Update community recipes from the remote repository.
Re-downloads and overwrites all recipes. Equivalent to `can init`.
Usage: can update [OPTIONS]
Options:
--repo <REPO>
GitHub repository (owner/repo) to fetch from
-v, --verbose
Enable verbose (debug) logging
--branch <BRANCH>
Branch to fetch
--no-verify
Skip SHA-256 checksum verification of recipe files. Required when using custom/forked repositories
-h, --help
Print help (see a summary with '-h')
-V, --version
Print version
can keygen
Generate an Ed25519 key for --events-sign-key (ADR-0021).
Writes a fresh 32-byte seed to PATH as 64 hex characters, with mode 0600, and prints its public key — the value a consumer adds to its trusted keys. The seed is never printed: stdout ends up in terminal scrollback and CI logs, the places a key must not reach.
Usage: can keygen [OPTIONS] <PATH>
Arguments:
<PATH>
File to write the seed to
Options:
--force
Replace an existing file. Seals signed with the old key will no longer match the new public key
-v, --verbose
Enable verbose (debug) logging
-h, --help
Print help (see a summary with '-h')
-V, --version
Print version
can pubkey
Print the public key of an --events-sign-key seed file.
Prints 64 lowercase hex characters, exactly as a `stream_seal` event carries it in `public_key`. Accepts the same files as --events-sign-key: 32 raw bytes or 64 hex characters.
Usage: can pubkey [OPTIONS] <PATH>
Arguments:
<PATH>
Seed file (from `can keygen` or `openssl rand -hex 32`)
Options:
-v, --verbose
Enable verbose (debug) logging
-h, --help
Print help (see a summary with '-h')
-V, --version
Print version
can recipe list
List available recipes and the default baseline syscall counts
Usage: can recipe list [OPTIONS]
Options:
-v, --verbose Enable verbose (debug) logging
-h, --help Print help
-V, --version Print version
can recipe show
Show the fully resolved recipe as TOML.
Merges base.toml, auto-detected recipes, and explicit --recipe arguments, expands environment variables, then prints the final effective policy. The output is valid TOML that can be saved as a standalone recipe file.
Usage: can recipe show [OPTIONS] [COMMAND]...
Arguments:
[COMMAND]...
Optional command to resolve (enables auto-detection of recipes).
The command is NOT executed — it is only used to determine which recipes would be auto-detected based on `match_prefix`.
Options:
-r, --recipe <RECIPE>
Recipe name or path. Can be repeated for composition
-v, --verbose
Enable verbose (debug) logging
-h, --help
Print help (see a summary with '-h')
-V, --version
Print version