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, launch agents, your service manager and container engines 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.
• 🧭 Explain and diff. Cage::explain names the rule that allows or denies reading, writing or executing a path and the narrowest change that would allow it; explain::diff shows what a policy change allows. The kernel checks every answer on every CI lane.
• 🧾 Receipts. Every finished run says how it was caged: policy digest, backend and tier, and everything accepted short of the policy.
• 🔎 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

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.

⏱️ Performance

Median overhead of a caged spawn over a plain one (just bench):

On macOS a new policy costs 11.6 ms once, to compile its profile. Details: benchmarks.

🎯 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

Licensed under either of Apache License, Version 2.0 or MIT license at your option.