GitHub - bugthesystem/agentjail: Minimal Linux sandboxes for running untrusted code. Built for AI agents, build systems, and any scenario where you need to execute code you didn't write.

Minimal Linux sandboxes for running untrusted code.

Why

Model-generated code, npm install on a fresh repo, a PR's test suite, an MCP tool the agent picked — all run as you, on your kernel. They can read ~/.ssh, fork-bomb the host, dial any IP, spawn a reverse shell. Docker isn't a sandbox. nobody isn't a sandbox. agentjail is.

One jail is one child process inside fresh Linux namespaces, pivot-rooted into a minimal rootfs, seccomp-filtered, cgroup-limited, egress-allowlisted. No VM. No daemon. No setuid helper.

Beta. Core crate (crates/agentjail) is the load-bearing piece, covered by make test-rust-privileged. Control plane, SDKs, web UI, gateway are useful but APIs may move before 1.0.

Isolation

• Namespaces — mount, network, IPC, PID; user optional.
• Filesystem — pivot_root to a 128-bit-random tmp root; old root umount2(MNT_DETACH)-ed. Bind /bin /lib /usr ro. tmpfs /etc with the bare minimum for dynamic linking + DNS. Landlock on Linux ≥ 5.13 (hard-fail if requested on older kernels).
• Network — None, Loopback, or Allowlist(domains). Allowlist routes through an in-process HTTP CONNECT proxy: resolves the host once, rejects private/link-local/loopback/CGNAT, dials the IP not the hostname (closes DNS rebinding). Veth via netlink, no ip binary.
• Syscalls — seccomp-BPF blocklist (Standard/Strict). Blocks namespace, mount, module, keyring, BPF, perf, io_uring, chroot, name_to_handle_at, ptrace, personality, clone3, mount_setattr, memfd_create, fanotify_init, quotactl, syslog. Arg-filters ioctl(*, TIOCSTI, …) and socket(AF_NETLINK|AF_PACKET|AF_VSOCK, …).
• Privileges — PR_SET_NO_NEW_PRIVS, close_range(3, ~0, CLOEXEC) before exec, full bounding-set drop, SECBIT_NOROOT_LOCKED | SECBIT_NO_SETUID_FIXUP_LOCKED, capset zeroing every effective / permitted / inheritable cap in the grandchild after /proc is remounted in the new PID namespace.
• Resources — memory, CPU, PIDs, disk I/O via cgroup v2. Barrier pipe: child blocks until the parent has assigned the cgroup, so there's no unconstrained startup window.

Requirements

• Linux ≥ 5.13, cgroup v2, user namespaces.
• Rust 1.85+ (edition 2024).
• CAP_NET_ADMIN — Allowlist mode only (veth + netlink).

Use

[dependencies]
agentjail = "0.1"
tokio = { version = "1", features = ["rt", "macros"] }

use agentjail::{Jail, preset_build};

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let jail = Jail::new(preset_build("./src", "./out"))?;
    let out  = jail.run("npm", &["run", "build"]).await?;
    println!("exit={} oom={}", out.exit_code, out.oom_killed);
    Ok(())
}

Presets

preset_install requires explicit domains:

preset_install("./src", "./out", vec![
    "registry.npmjs.org".into(),
    "registry.yarnpkg.com".into(),
])

Config

use agentjail::{Jail, JailConfig, Network, SeccompLevel};

let jail = Jail::new(JailConfig {
    source:        "/code".into(),       // ro at /workspace
    output:        "/artifacts".into(),  // rw at /output
    network:       Network::None,
    seccomp:       SeccompLevel::Standard,
    memory_mb:     512,
    cpu_percent:   100,                  // 100 = 1 core
    max_pids:      64,
    io_read_mbps:  100,
    io_write_mbps: 50,
    timeout_secs:  300,
    ..Default::default()
})?;

Network

Network::Allowlist(vec![
    "api.anthropic.com".into(),
    "registry.npmjs.org".into(),
    "*.mcp.example.com".into(),
])

Hostname checked against the allowlist, resolved, every private/loopback/link-local/CGNAT/test-net IP filtered, connect to what's left. TLS passes through (HTTPS, SSE, WebSocket).

GPU

Trusted workloads only — exposes the NVIDIA kernel-driver attack surface.

JailConfig { gpu: GpuConfig { enabled: true, devices: vec![0] },
             ..Default::default() }

Resource monitoring

let handle = jail.spawn("npm", &["run", "build"])?;
if let Some(s) = handle.stats() {
    println!("mem {} / peak {} MB  pids {}",
        s.memory_current_bytes / 1_048_576,
        s.memory_peak_bytes    / 1_048_576,
        s.pids_current);
}
let out = handle.wait().await?;
if out.oom_killed { eprintln!("OOM"); }

Events

let (_handle, mut rx) = jail.spawn_with_events("npm", &["run", "build"])?;
while let Some(ev) = rx.recv().await {
    match ev {
        JailEvent::Stdout(l)        => println!("{l}"),
        JailEvent::Stderr(l)        => eprintln!("{l}"),
        JailEvent::OomKilled        => eprintln!("OOM"),
        JailEvent::Completed { .. } => break,
        _ => {}
    }
}

Snapshots and live forks

Save the output dir, restart from it later. Or branch a running jail without pausing it — useful for running N variants of an agent off one warm state.

let snap = Snapshot::create(&output, &snapshot_dir)?;
snap.restore()?;

// FICLONE reflink where supported (btrfs, xfs, ext4-with-reflink);
// regular copy on tmpfs / cross-filesystem. Freezer pauses the source
// jail sub-millisecond for the duration of the clone.
let handle = jail.spawn("python", &["train.py"])?;
let (forked, _info) = jail.live_fork(Some(&handle), "/tmp/fork-out")?;

Files are content-addressed by BLAKE3 in a shared object pool; unchanged files (same size + mtime_ns) skip rehashing and reuse the prior blob. Restore strips S_ISUID/S_ISGID and rejects manifest entries with absolute or .. paths.

Threat model

Each row links to the regression test that would fail if the protection ever did. Tests live in crates/agentjail/tests/.

Limits

• Linux only. Not a VM — a kernel exploit escapes. For stronger isolation, pair with gVisor or run inside Firecracker.
• GPU mode widens the attack surface to the NVIDIA driver.
• Allowlist mode costs one veth pair per concurrent jail. Stale interfaces are reaped at agentjail-server startup.

Control plane

Optional. The library is enough for one process. The server is for when you have many: shared upstream credentials, a workspace ledger, snapshots, an SSE feed of every API call, a UI.

# token@tenant:role  — every component required, no defaults.
export AGENTJAIL_API_KEY="\
  ak_ops@platform:admin,\
  ak_acme_alice@acme:operator,\
  ak_globex_ops@globex:operator"
docker compose -f docker-compose.platform.yml up --build
# UI:  http://localhost:3000/t/<tenant>
# API: http://localhost:7000

Tenancy

Every workspace, snapshot, session, jail-row, and credential is stamped with tenant_id. Operators see their own tenant. Admins see all, with ?tenant=<id> to scope. Cross-tenant id access returns 404, never 403 — the server doesn't reveal whether a row outside scope exists. Full key format and DB shape: docs/tenancy.md.

Phantom credentials

Sandboxes never see real upstream keys. Sessions hand out phantom tokens (phm_<hex>) plus *_BASE_URL env vars pointing at the proxy; the proxy swaps the token for the real key on the way out. Per-tenant: a token minted for tenant A can't spend tenant B's credentials even if the service matches.

Flavors

Runtime "flavors" (nodejs, python, bun, …) are host directories under $state_dir/flavors/<name>/, bind-mounted ro into each jail at /opt/flavors/<name>/, with bin/ prepended to PATH. Adding deno is a mkdir, not a code change.

POST /v1/workspaces
{ "flavors": ["nodejs", "python"] }

GET /v1/flavors lists names (host paths stay admin-internal). See docs/flavors.md.

Clone-jail

git clone runs in its own short-lived jail by default — strict seccomp, network allowlist pinned to the repo host, 60 s timeout, no host access. A malicious .gitmodules or core.sshCommand can't reach anything off the target dir. Opt out on restricted container runtimes:

export AGENTJAIL_CLONE_MODE=host   # default: jail

Surface

• Identity — GET /v1/whoami · GET /v1/flavors
• Credentials (per-tenant) — POST · GET · DELETE /v1/credentials/:service (admins: ?tenant=<id>)
• Sessions — POST /v1/sessions · POST /v1/sessions/:id/exec
• Runs — POST /v1/runs · /fork · /stream
• Workspaces — POST /v1/workspaces · /fork · /exec · PATCH · POST /v1/workspaces/:id/snapshot · POST /v1/workspaces/from-snapshot (requires parent_workspace_id)
• Lists (tenant-filtered) — GET /v1/{workspaces,snapshots,sessions,jails,audit}
• Detail — GET /v1/snapshots/:id/manifest · GET /v1/jails/:id · GET /v1/config (bind-addrs + state_dir admin-only)

Web UI

React 19 + Vite + Tailwind. Pages live at /t/:tenant/... so the active tenant is bookmarkable. Pages: Dashboard, Projects, API Sessions, Integrations, Playground, Docs. Operator tools behind Advanced: Execution Ledger, Snapshots, API Audit, Accounts, System Settings.

SDKs

Node (@agentjail/sdk, zero deps, Node ≥ 18) and Python (agentjail, ≥ 3.10, depends on httpx). Symmetrical surface.

import { Agentjail } from "@agentjail/sdk";

const aj = new Agentjail({
  baseUrl: "http://localhost:7000",
  apiKey:  process.env.AGENTJAIL_API_KEY!,
});

await aj.credentials.put({ service: "openai", secret: process.env.OPENAI_API_KEY! });

for await (const ev of aj.runs.stream({ code, language: "python" })) {
  if (ev.type === "stdout") process.stdout.write(ev.line + "\n");
}

const session = await aj.sessions.create({
  services: ["openai", "github"],
  scopes:   { github: ["/repos/my-org/*"] },
  ttlSecs:  600,
});
spawn("node", ["agent.js"], { env: { ...process.env, ...session.env } });

Build and test

make test-rust                     # low-priv unit slice (Docker)
make test-rust-privileged          # full security suite (--privileged)
make test-rust-privileged-clone    # end-to-end clone-jail + workspace-exec
( cd packages/sdk-node    && npm test )
( cd packages/sdk-python  && pytest )
( cd web && npm run build )

GPU tests need an NVIDIA GPU + the Container Toolkit:

docker compose run --rm gpu cargo test --test gpu_test -- --nocapture

License

MIT. See LICENSE.