Skip to content

sandbox: sbx, a standalone sandbox any agent can run under - #12

Merged
blockmandev merged 2 commits into
mainfrom
claude/laughing-darwin-hyqkjj
Oct 20, 2026
Merged

blockmandev merged 2 commits into
mainfrom
claude/laughing-darwin-hyqkjj

Conversation

@blockmandev

Copy link
Copy Markdown
Member

What

A new workspace crate, crates/sandbox, builds the sbx binary and the incord_sandbox library. It doesn't depend on incode, so incode, Insi or any agent CLI can run a command under one policy file:

  • Filesystem:
    • writable roots;
    • deny_read for paths that must not even be read, such as a benchmark's hidden tests;
    • Linux uses Landlock: a hidden path is carved out by granting its siblings level by level. macOS uses a Seatbelt profile.
  • Network:
    • modes allow, deny, or proxy;
    • proxy runs an allowlisting HTTP/CONNECT proxy in the unconfined parent, and the kernel lets the command reach only that proxy's port;
    • the proxy resolves each name once and refuses private answers, and chains through an upstream proxy when sbx sits behind one.
  • Environment: agent-session variables (CLAUDECODE, CLAUDE_CODE_SESSION*, …) and git redirects (GIT_DIR, …) are stripped by default; credentials are kept.
  • Limits:
    • setrlimit for CPU, memory, file size and open files;
    • a wall clock that kills the whole process group;
    • signals sent to sbx are forwarded, and a supervisor kills the group if sbx is SIGKILLed.
  • Strict by default: a policy the machine can't enforce in full is refused (exit 125). sbx doctor and sbx check --json report what is enforced and how.

README: a short sbx section under "The OS sandbox". Details are in crates/sandbox/README.md. CI now runs the crate's clippy and tests.

Tested

  • 22 unit tests: policy, environment, allowlist, private addresses, Seatbelt profile, read grants.
  • 12 Linux escape tests through the real binary:
    • writes outside the root, via symlinks, hard links, renames, /proc/self/root and children;
    • reading a hidden path by six routes;
    • connect and bind under deny, and bypassing the proxy;
    • the wall limit, SIGKILL cleanup, limits and exit codes.
  • clippy is clean for x86_64-unknown-linux-gnu, x86_64-apple-darwin and x86_64-pc-windows-gnu.
  • End to end: incode -t driving claude entirely inside sbx finished a real task with cargo test green. Its attempts to read a --deny-read file and to write outside the workspace both got "Permission denied".

Not yet

  • macOS: the Seatbelt clauses for proxy and deny_read haven't run on a Mac.
  • Windows: filesystem and network confinement aren't implemented; sbx reports this and refuses in strict mode.
  • Linux UDP: Landlock doesn't cover UDP.
  • incode: it still uses its built-in sandbox.

Generated by Claude Code

crates/sandbox builds `sbx` and the `incord_sandbox` library, with no
dependency on incode, so incode, Insi or any other agent CLI can run a
command under one policy file:

- filesystem: writable roots, and `deny_read` for paths that must not even
  be read (a benchmark's hidden tests). Landlock on Linux, carving a hidden
  path out by granting its siblings level by level; Seatbelt on macOS.
- network: allow, deny, or an allowlisting HTTP/CONNECT proxy run in the
  unconfined parent. The kernel lets the command reach only the proxy's
  port. The proxy resolves each name once and refuses private answers
  unless allowed, and chains through an upstream proxy when sbx sits
  behind one.
- environment: the agent-session variables (CLAUDECODE,
  CLAUDE_CODE_SESSION*, ...) and git redirects (GIT_DIR, ...) are stripped
  by default; credentials are kept; inherit = "none" keeps only the
  essentials and what is passed.
- limits: setrlimit (cpu, memory, file size, open files) and a wall clock
  that kills the whole process group. Signals to sbx are forwarded, and a
  supervisor kills the group if sbx itself is SIGKILLed.
- a private TMPDIR per run.

Strict by default: a policy this machine cannot enforce in full is
refused (exit 125) rather than run with less. `sbx doctor` and
`sbx check --json` say what is enforced and how.

Escape tests (Linux, through the real binary) cover:
- writes outside the root, symlinks, hard links, renames,
  /proc/self/root, children;
- reading a hidden path by six routes;
- connect and bind under deny, and bypassing the proxy;
- the wall limit, SIGKILL cleanup, limits and exit codes.

clippy is clean for Linux, macOS and Windows targets. CI now runs the
crate's clippy and tests.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011DiH8n52ifWoCd5Kx2aHwT
Landlock's network rules cover TCP bind/connect only. Under `deny` and
`proxy` the helper now also installs a hand-written seccomp-bpf filter
(after Landlock, before exec) that lets socket() create only AF_UNIX,
AF_NETLINK and plain TCP (AF_INET/AF_INET6, SOCK_STREAM, protocol 0 or
IPPROTO_TCP, with SOCK_NONBLOCK/SOCK_CLOEXEC masked off); everything else
fails with EACCES. It is an allowlist rather than a UDP/raw/packet
blocklist because SCTP and MPTCP are not TCP to Landlock either.
io_uring_setup/enter/register get EPERM (io_uring creates sockets past
seccomp). x86-64 filters i386 (int 0x80, socketcall(SYS_SOCKET) refused)
and x32 too; aarch64 filters 32-bit ARM. An unknown audit arch is killed;
other build architectures install nothing and report the network as not
enforced, so strict mode refuses. AF_NETLINK stays: getaddrinfo and ip
need it, it can only read interfaces/routes without CAP_NET_ADMIN, and
nothing on it leaves the machine. No new dependency (no seccomp crate
was in Cargo.lock; ~40 BPF instructions with libc constants).

Measured on Linux 6.18 (root, x86-64), old sbx vs new, --net deny:
- UDP sendto 127.0.0.1: delivered -> EACCES (also with NONBLOCK|CLOEXEC)
- raw and AF_PACKET sockets: opened -> EACCES
- MPTCP connect to a loopback listener: connected -> EACCES
  (plain TCP was already EACCES via Landlock)
- i386 socket(AF_INET, SOCK_DGRAM) via int 0x80: fd 3 -> -EACCES
- getaddrinfo/getent example.com: resolved -> fails (EAI_AGAIN)
- AF_UNIX, netlink, --net allow UDP: unchanged
Lookups a local daemon answers over a Unix socket (nss-resolve, nscd)
still work; README says so and the DNS test skips there.

net_status, the README and lib docs now say UDP/DNS are covered. New
Linux escape tests: UDP/raw/packet refused under deny and proxy (and no
datagram arrives), UDP works under allow, DNS fails under deny (with a
control lookup). New tests/escape_macos.rs mirrors the escape tests that
apply to Seatbelt (writes, symlinks, children, read-only, deny_read by
several routes, TCP deny with a control, proxy allowlist and bypass, env,
wall limit, SIGKILL cleanup, exit codes) using only sh/bash/nc/curl/ps;
checked to compile for x86_64-apple-darwin, to run on the macOS CI job.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011DiH8n52ifWoCd5Kx2aHwT

Copy link
Copy Markdown
Member Author

CI is red on every job (fmt, and test on Ubuntu, macOS and Windows), but not because of this PR. Each job ended within 2–5 seconds with runner_id: 0: no runner was ever assigned and no step ran, so there's no log. Every ci run on main since Oct 10 (runs #3–#6) failed the same way. This points at the account's Actions settings, most likely a spending limit or billing on a private repo, rather than at the code.

Run locally on this branch's head (1b59a53):

  • cargo fmt --all -- --check passes;
  • cargo clippy -p incord-sandbox --all-targets -- -D warnings is clean for Linux, macOS and Windows targets;
  • cargo test -p incord-sandbox: 24 unit and 15 Linux escape tests pass.

Once Actions can assign runners again, a re-run will give the first real macOS run of the Seatbelt network and deny_read tests (tests/escape_macos.rs).


Generated by Claude Code

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants