FAQ
Common questions about procage: production readiness, sandbox-exec, Docker and microVMs, Linux tiers, running inside an AI agent, Windows, and how to report an escape.
Short answers, linking to the rest of the documentation. For anything security-relevant, the threat model is the reference.
Can I use procage in production?
As one layer, knowing its limits. procage is pre-1.0, so the API may change, and an OS sandbox reduces risk rather than removing it: the threat model lists what it contains, the open variants and when to use a microVM instead.
Who is it for?
Rust programs that run commands on someone else’s behalf: coding agents and their tool calls, MCP servers, build orchestrators, CI-like runners. The adversary is code inside the child running with your user id, such as a model following injected instructions or a malicious build script.
Why not just call sandbox-exec on macOS?
/usr/bin/sandbox-exec is deprecated and offers no lifetime control, descriptor hygiene or typed policy. procage applies Seatbelt directly through libsandbox in the forked child, with system calls only, and reports a missing interface as an error instead of running uncaged.
Is depending on a private libsandbox interface safe?
It is a stated risk. Apple does not document or support those functions and may change them. procage resolves them at run time and probes the apply method before the first spawn; anything missing or different is an Unsupported error naming the macOS build, never a fallback to no sandbox.
How does it compare with Docker or a microVM?
Containers and microVMs isolate a whole environment; procage confines one command on the host, with your tools and files as they are, and adds far less start-up latency. A microVM gives a hypervisor boundary that an OS sandbox cannot: when a kernel escape is unacceptable, use one, optionally with procage inside it for finer-grained policy.
Which Linux tier will I get?
The strongest the host allows. Tier T1 (namespaces, mounts, Landlock, seccomp) needs unprivileged user namespaces; tier T2 (Landlock and seccomp) is what a Docker container with default settings or a host restricting user namespaces gets. Both need Landlock ABI 1 (Linux 5.13) or later. procage::linux::probe() tells you.
Why does my policy fail with capability gaps on Linux?
Some constructs cannot be enforced on every tier or kernel: protecting a path inside a writable tree on T2, loopback networking, signal scoping below Landlock ABI 6. procage refuses rather than run a weaker sandbox. Use Cage::fit to accept named relaxations, or LowerOptions::accept_spawn_snapshot() for approximations taken at spawn.
My command failed with "Operation not permitted". What did the sandbox deny?
Build the cage with CageOptions::with_violations() and read Child::violations() after the child exits: on macOS it lists each denied operation with the process, the target and the kind of rule behind it (not granted, hidden, protected, a hard-deny class). On Linux it lists every system call the seccomp filter refused (ptrace, an IP socket without network, …); file and network denials by Landlock are not reported. See Violations.
Why does it fail inside my AI agent's terminal?
Many agent harnesses run their shell inside a Seatbelt sandbox. A second profile fails or is ignored by the kernel, so procage refuses with AlreadySandboxed. Run the program, and the kernel facts, from a plain terminal.
Can a caged child read my SSH keys?
Not in the cases the tests cover: the secrets hard-deny class denies ~/.ssh, ~/.aws, ~/.gnupg and other credential paths in every policy, even one that reads your whole home, and a spawn is refused while such a file has a second name (a hard link) elsewhere. On Linux, where a rule reaches those paths, tier T1 relies on masks taken at spawn, an approximation you accept. See Hard-deny classes.
Does it support Windows?
No. Windows is a non-goal, as are App Sandbox, entitlements, Endpoint Security and eBPF security modules, which need code signing, Apple approval or root.
How do I report a sandbox escape?
Privately, through GitHub’s private vulnerability reporting. Include the OS and version, the procage version, and the smallest policy and program that show the problem.