procage

🛡️ Process sandboxing for Rust. procage runs a child process in an OS sandbox on macOS (Seatbelt, without the deprecated sandbox-exec) and on Linux (Landlock, seccomp and namespaces). No helper binaries, no root.

It is built for programs that run commands on someone else's behalf: coding agents, MCP servers, build orchestrators. The code inside the child runs with your user id, whether it is an LLM following injected instructions or a project's build script.

cargo add procage

use procage::native::{Cage, Grants};
use procage::policy::{AbsPath, presets};

let workspace = AbsPath::new("/Users/me/project")?;
let cage = Cage::new(&presets::agent_readonly::v3(&workspace))?;
let status = cage
    .spawn(&mut std::process::Command::new("make"), &Grants::new())?
    .wait()?;

📖 Documentation · 🔐 Threat model · 📐 Design records · 📝 Changelog · 🚨 Report an escape

🚧 Pre-1.0. The API may change between minor versions. Read the threat model for what procage contains and where it stops.

✨ Features

🧩 One typed policy, lowered per OS. Anything a host cannot enforce is a named capability gap, never a weaker rule. Cage::fit relaxes only what you name and says what would lift each relaxation.
🔒 A hard-deny tier in every policy. Secrets, git hooks, shell startup files and launch agents are denied last and waivable only by name.
🧹 Hygiene and lifetime. Inherited descriptors are closed, secret-looking variables dropped, and every process a run started is killed when it ends, double-forked daemons included.
🔎 Violation reports. A cage can say what the sandbox denied and which rule denied it: every denial on macOS, every refused system call on Linux.
📦 Frozen presets and base profiles that let ordinary programs and developer tools start, and Cage::exec for helpers that become the caged command.

🖥️ Platforms

Platform	Mechanism	Needs
🍎 macOS	Seatbelt, applied through libsandbox	A caller that is not itself sandboxed
🐧 Linux T1	Namespaces, mounts, Landlock, seccomp	Unprivileged user namespaces, Landlock ABI 1 (Linux 5.13)
🐧 Linux T2	Landlock, seccomp	Landlock ABI 1 (Linux 5.13), e.g. Docker's defaults

procage picks the strongest tier the host allows and never runs a child unsandboxed.

Known limits: no pseudo-terminals, no Linux PID namespace, no loopback or proxy networking on Linux, and Landlock's file and network denials are not reported. Open escape variants: a hard link made before the run (R-08), and on macOS the arguments and environment of your other processes, which a caged child can read (R-25).

🎯 Threat model

procage contains adaptive code running as your user inside the child, and keeps it away from your secrets, files outside the granted paths, your terminal and session, and persistence locations. An OS sandbox reduces this risk but does not remove it: kernel and OS service bugs are out of scope, so use a microVM where such an escape is unacceptable.

The threat model lists every known escape class and its status. A class counts as handled only when caged canaries on a real kernel show the refusal. Every change is specified, threat-modelled and verified in the open: see the design records.

🛠️ Development

just ci            # every local gate: fmt, lints, tests, docs, deny, MSRV (1.99), no_std, semver
just escape        # the macOS escape suite
just linux-t1      # the Linux tests in Docker, tier T1 (`just linux` for T2)
just test-outside  # the kernel facts, from a terminal outside any sandbox

The kernel facts (crates/procage-kernel-facts) re-verify on the running kernel the OS behaviour procage relies on. Facts that apply a sandbox fail rather than skip inside another Seatbelt sandbox, such as an AI agent's.

📄 License