All projects
06SentinelBoxAI agent sandbox2026Open source

Isolate AI‑written code at the kernel, and tell the agent why it failed.

SentinelBox isolates execution with Linux namespaces, OverlayFS, seccomp USER_NOTIF and cgroup v2. Every blocked syscall is turned by a Rust monitor into feedback the agent can act on, and exposed over the Model Context Protocol.

  • Model Context Protocol
  • Rootless · Linux 5.15+
  • C · Rust · TypeScript
sentinelbox — strict

$ bash scripts/run.sh -- /bin/sh -c "nc -w1 example.com 80"

[sentinelbox] profile=strict rootfs=./rootfs/busybox

[sentinelbox] clone child: user·pid·mnt·net·uts·ipc·cgroup

[monitor] policy loaded rules=28 db=WAL

[sentinelbox] seccomp listener ready → notify_fd via SCM_RIGHTS

socket(AF_INET, SOCK_STREAM, 0) ⟶ USER_NOTIF

[SEMANTIC] 安全違規:嘗試在 profile「strict」內建立 socket(family=2)。

HINT → 改用沙盒外預先準備好的資料;本 profile 禁止任何網路連線。

nc: socket: Operation not permitted

[monitor] summary: mem_peak=… KiB cpu_total=… ms

Illustrative replay: message formats come from the source; the monitor prints the Chinese strings from mappings/syscall_feedback.json. PIDs and timings omitted.
namespaces from a single clone()
7
namespaces from a single clone()
seccomp actions: ALLOW · ERRNO · NOTIFY · KILL
4
seccomp actions: ALLOW · ERRNO · NOTIFY · KILL
cgroup v2 sampling interval
100 ms
cgroup v2 sampling interval
dangerous capabilities dropped, incl. bounding set
13
dangerous capabilities dropped, incl. bounding set

01

A plain sandbox returns an error code. The agent is left guessing.

“Operation not permitted” or “Killed” tells an LLM almost nothing: a bug, a missing permission, or a policy decision? SentinelBox knows the exact syscall and rule at the moment of interception, so it can answer why and what to change, closing the execute → fail → feedback → repair loop.

  • NOTIFYsocket(AF_INET, …)
    nc: socket: Operation not permitted

    Security Violation: Attempt to create a socket (family=2) under profile 'strict'.

    HINT Use data prepared outside the sandbox; this profile forbids any network connection.

  • KILLmount("proc", …)
    Killed            exit 137

    Action Denied: Filesystem/namespace mutation (mount) is forbidden.

    HINT The sandbox rootfs is a read-only overlay; remounting is neither needed nor allowed.

  • KILLmemory.max exceeded
    Killed            exit 137

    Resource exhausted: the process exceeded its memory limit and was killed by the kernel (cgroup memory.max violation).

    HINT Check for memory leaks, or raise memory.max in the profile.

02

Four processes, each guarding one layer in the language that suits it.

C handles kernel-facing isolation, Rust makes security decisions and keeps the audit trail, TypeScript hands results to the AI, and the web tier provides observability. Hover or select a component, or play through one complete run.

call / data flowfallback pathisolation boundary
AI CLIENTHOST · USER SPACEOBSERVABILITYLINUX KERNELSANDBOXuser · pid · mnt · net · uts · ipc · cgrouptarget processexecvp() · uid 0 ↦ host uidOverlayFS rootlower: busyboxupper: tmpfspivot_rootHardeningno_new_privs−13 capsdumpable = 0seccomp filterAI AgentClaude · any MCP clientMCP ServerTypeScript · stdiotranslate_errorsuggest_repairsentinelboxC · orchestratorprofile → cgroup → clone()sentinelbox-monitorRust · security sentinelpoll(notify_fd) → RECVpolicy.lookup(syscall)feedback map → zh/en/hinttelemetry thread · 100 msSQLite · WALexecutionssyscall_eventsresource_samplesBridgeExpress · Socket.ioDashboardReactlive CPU / memoryevents · kill switchnamespaces7 × CLONE_NEW*uid_map · gid_mapseccomp-BPFALLOW · ERRNO → decided in-kernelNOTIFY · KILL → listener fdcgroup v2memory.max · cpu.maxpids.max · memory.eventsprocfs/proc/stat · /proc/meminfofallback, no delegation1fork+exec2clone()3notify_fd4syscall5USER_NOTIF ⇄ reply6audit7100 ms7fallback[SEMANTIC] + HINT8MCP · stdio8poll9Socket.io9

← Swipe to see the whole diagram →

03

One run, from clone() to rmdir.

The order is part of the security design: uid_map is written before the child continues, privileges drop before seccomp is installed, and execvp comes last. Each step maps to an actual call in the source.

  1. 01Setup

    1. Parent

      Load the profile, create the sentinelbox.<pid> cgroup and write memory.max, cpu.max and pids.max.

    2. Parent → Monitor

      Create a socketpair and fork-exec the monitor; the socket is dup2’d to fd 3, cgroup path and profile go in env vars.

    3. Parent → Child

      clone() creates the user, pid, mount, net, uts, ipc and cgroup namespaces in one call.

    4. Parent → Kernel

      The parent writes setgroups=deny, uid_map and gid_map, then adds the child to cgroup.procs.

    5. Parent → Child

      Send the child’s host PID over the sync pipe, releasing the child.

  2. 02Isolate

    1. Child

      Become uid 0 inside (an unprivileged user on the host) and disable core dumps.

    2. Child → Kernel

      Mount tmpfs and overlay, pivot_root and detach the old root, then mount /proc (rbind when nested).

    3. Child

      Set the hostname and PR_SET_NO_NEW_PRIVS, then drop 13 capabilities from effective, permitted, inheritable and bounding sets.

    4. Child → Kernel

      Install the profile’s seccomp filter and obtain the USER_NOTIF listener fd.

    5. Child → Monitor

      Pass notify_fd plus "PID:<pid>|CMD:<argv>" to the monitor with sendmsg(SCM_RIGHTS).

    6. Child

      execvp() the target; every later syscall goes through the filter.

  3. 03Supervise

    1. Kernel → Monitor

      A syscall matching a NOTIFY / KILL rule is parked and delivered to the monitor.

    2. Monitor → Kernel

      Reply per policy (CONTINUE or −EPERM, plus SIGKILL for KILL rules) and write the audit record.

    3. Monitor

      The telemetry thread reads memory.current and cpu.stat every 100 ms into resource_samples.

  4. 04Teardown

    1. Kernel → Parent

      The child exits; wait4() returns status and rusage together (the fallback when cgroup stats are unavailable).

    2. Kernel → Monitor

      notify_fd reports POLLHUP; the monitor records the end and checks memory.events for an OOM kill.

    3. Parent

      Wait for the monitor, print the resource summary and remove the cgroup.

04

The same syscall takes a different path under each profile.

Pick a profile and a syscall to see where it is decided, what the process actually receives and which feedback the AI gets. Rules and wording come straight from profiles/*.json and mappings/syscall_feedback.json.

Profile
Syscall

Dots show the action under this profile: ALLOWERRNONOTIFYKILL

socket()strictNOTIFY

listed in the profile’s syscall_rules

① seccomp-BPF filter in the kernel
Rule matched: the syscall is parked and handed to the USER_NOTIF listener.
② Rust monitor consults the policy
policy.lookup("socket") → NOTIFY; written to syscall_events (signal_name = EPERM).
③ What the process receives
gets −EPERM and can handle the error

Semantic feedback for the AI

[SEMANTIC] Security Violation: Attempt to create a socket (family=2) under profile 'strict'.

HINT → Use data prepared outside the sandbox; this profile forbids any network connection.

The monitor prints the Chinese message and hint; the English text here comes from the mapping’s en field and a translated hint.

Rules and messages are read from the main branch of mcp-sentinel-box on GitHub (refreshed hourly). profiles/ · syscall_feedback.json

05

Six stacked layers, so no single failure opens the box.

Isolation never relies on one mechanism. Even if a syscall rule is missing, the process is still inside its own namespaces, a read-only root, stripped capabilities and cgroup limits.

  • L1

    Namespaces

    • user, pid, mount, net, uts, ipc and cgroup from one clone()
    • uid 0 inside is an unprivileged host user (rootless)
    • setgroups=deny is written before gid_map

    core/src/sandbox.c

  • L2

    Filesystem

    • OverlayFS: read-only busybox lower + tmpfs upper; writes vanish with the sandbox
    • pivot_root + MNT_DETACH instead of chroot, so there is no way back out
    • Root propagation set to private so mounts never leak to the host

    core/src/overlayfs.c

  • L3

    Privileges

    • PR_SET_NO_NEW_PRIVS: setuid binaries cannot gain privileges
    • 13 dangerous capabilities dropped, including the bounding set
    • PR_SET_DUMPABLE = 0 so no core dump can leak memory

    core/src/capability.c

  • L4

    Syscalls

    • seccomp-BPF with SECCOMP_RET_USER_NOTIF instead of ptrace
    • ALLOW rules are added first so hot syscalls pass early
    • KILL compiles to NOTIFY: record first, then terminate

    core/src/seccomp.c

  • L5

    Resources

    • cgroup v2: memory.max, cpu.max, pids.max (stops fork bombs)
    • A dedicated cgroup per run, removed when it ends
    • oom_kill in memory.events becomes a semantic OOM event

    core/src/cgroup.c

  • L6

    Audit

    • Every interception is stored in SQLite with the errno symbol and semantic text
    • WAL + synchronous=NORMAL + 5 s busy_timeout
    • Executions, events and samples, all timestamped in ms

    monitor/src/db.rs

Three built-in profiles

A profile is one JSON file shared by the C core and the Rust monitor: the core installs the seccomp filter and cgroup limits from it, the monitor makes decisions from it.

strict

default

Default. Blocks network calls and kernel-sensitive syscalls; every violation is reported to the monitor.

memory.max
128 MiB
cpu.max
0.5 CPU
pids.max
32
NOTIFY × 6KILL × 19ERRNO × 3

profiles/strict.json · default_action: ALLOW

datascience

More memory and CPU; connect / bind are intercepted while local sockets stay usable.

memory.max
1 GiB
cpu.max
2 CPU
pids.max
128
NOTIFY × 2KILL × 13ERRNO × 1

profiles/datascience.json · default_action: ALLOW

web

For web agents: outbound sockets allowed by policy; inbound bind / listen / accept are intercepted.

memory.max
256 MiB
cpu.max
1 CPU
pids.max
64
NOTIFY × 4KILL × 13ERRNO × 1

profiles/web.json · default_action: ALLOW

Rules and messages are read from the main branch of mcp-sentinel-box on GitHub (refreshed hourly). profiles/ · syscall_feedback.json

06

Every interception and resource curve is left as a queryable record.

The audit store is SQLite in WAL mode, so the monitor can keep writing while the bridge, dashboard and MCP side read concurrently. Values are stored raw with millisecond timestamps; conversion happens at the edge.

syscall_events

One row per NOTIFY / KILL interception

  • exec_idFK
  • tsms
  • syscall_nrx86_64
  • syscall_name
  • actionNOTIFY | KILL
  • errno
  • signal_nameEPERM | SIGKILL
  • semantic_msg
  • remediationhint

executions

One row per sandbox run

  • idPK
  • profile
  • pidhost
  • commandargv
  • start_tsms
  • end_tsNULL = running
  • status

resource_samples

One row every 100 ms

  • exec_idFK
  • tsms
  • mem_bytesmemory.current
  • cpu_useccpu.stat
  • cpu_pctΔ / interval
100 ms
The sampler keeps memory.current and cpu.stat open and seeks back each tick instead of reopening.
cpu_pct
Computed from the usage_usec delta over the real elapsed time; can exceed 100% on several cores.
fallback
Without cgroup delegation it reads /proc/stat and /proc/meminfo; the core also fills totals from wait4() rusage.
OOM
At exit it reads oom_kill from memory.events and records a semantic event if the kernel OOM-killed the run.

Last five intercepted syscalls

SELECT datetime(e.ts / 1000, 'unixepoch') AS at,
       x.profile, e.syscall_name, e.action,
       e.signal_name, e.semantic_msg
FROM   syscall_events e
JOIN   executions x ON x.id = e.exec_id
ORDER  BY e.id DESC
LIMIT  5;

PRAGMAs: journal_mode=WAL, synchronous=NORMAL, busy_timeout=5000. The monitor and sampler share one connection behind Arc<Mutex> so writers never contend.

07

Plug into any agent that speaks MCP.

The MCP server runs over stdio and exposes two tools. After a failed run the agent calls them for the cause and a repair direction, rewrites its code and retries, without a human in the loop.

translate_error

Turns low-level signals (signal / errno / syscall / path) into an explanation an AI can use.

  • signal?
  • errno?
  • syscall?
  • path?
  • details?

suggest_repair

Suggests how to change the code, given the blocked syscall and the active profile.

  • syscall
  • original_code
  • profile?

claude_desktop_config.json

{
  "mcpServers": {
    "sentinelbox": {
      "command": "node",
      "args": ["/path/to/mcp-sentinel-box/mcp-server/dist/index.js"]
    }
  }
}
Example: two tool calls after a failure
→ tools/call translate_error
{ "errno": "EPERM", "syscall": "socket" }
← Security Violation: Operation not permitted. You are trying
to access a restricted resource. The violation occurred
during the `socket` system call.
→ tools/call suggest_repair
{ "syscall": "connect", "profile": "strict",
"original_code": "requests.get(url)" }
← Based on the blocked syscall 'connect', here is the repair
strategy: The code attempts to access the network. In the
'strict' profile, networking is disabled.
Repair Suggestion: Replace network requests with local mock
data or read from a pre-mounted dataset in the workspace.
…

08

Why it is built this way, and not the obvious way.

Each trade-off below is documented in the source comments, and together they are what separates SentinelBox from “just wrap it in Docker”.

SECCOMP_RET_USER_NOTIF

over ptrace / SECCOMP_RET_TRACE

No tracer sits on every syscall: ALLOW is decided inside the kernel’s BPF program and only matching calls reach the monitor through a single fd.

core/src/seccomp.c

clone(CLONE_NEW* …)

over unshare()

The child is born inside every namespace: one fewer transition and no window where it runs before isolation.

core/src/sandbox.c

pivot_root + MNT_DETACH

over chroot

chroot can be escaped; pivot_root swaps the whole root and detaches the old one, so no path back to the host exists.

core/src/overlayfs.c

tmpfs upper layer

over disk-backed writes

All writes land in memory; resetting the sandbox means discarding the tmpfs, with no persistent cleanup.

core/src/overlayfs.c

wait4()

over waitpid()

Exit status and rusage (CPU time, max RSS) in one call: cheapest for short-lived AI code runs.

core/src/sandbox.c

poll() → NOTIF_RECV

over blocking ioctl

If the sandbox exits without ever triggering NOTIFY, a blocking RECV may never wake; polling first lets POLLHUP end the loop cleanly.

monitor/src/main.rs

sendmsg left unfiltered

over blocking every socket call

notify_fd itself is sent with sendmsg(SCM_RIGHTS); filtering it would deadlock the child on its own filter. Blocking socket() / connect() already cuts the network.

profiles/strict.json

C core + Rust monitor

over one process

Kernel-facing setup is most direct in C; the decision loop that handles raw fds and ioctls gets Rust’s borrow checker. They share only inherited fds and env vars.

monitor/Cargo.toml

09

Three commands to run it on your own Linux box.

Inside Docker, VS Code Dev Containers or some WSL2 setups, cgroups cannot be delegated and telemetry degrades to host-wide sampling; the sandbox still runs. For exact per-sandbox limits, run scripts/setup_cgroup.sh on native Linux.

  1. 1

    Clone and provision

    Installs dependencies, builds the C core and Rust monitor, and creates the busybox rootfs.

    git clone https://github.com/Ming874/mcp-sentinel-box.git
    cd mcp-sentinel-box
    bash scripts/provision.sh
  2. 2

    Start the dashboard

    The bridge listens on 3001 and the dashboard on 3000, attached to sentinelbox.db.

    ./scripts/start_monitoring.sh
    # open http://localhost:3000
  3. 3

    Run code in the sandbox

    In another terminal; switch profiles with an environment variable.

    bash scripts/run.sh -- /bin/sh -c "echo hello from sandbox"
    bash scripts/run.sh -- /bin/sh -c "nc -w1 example.com 80"
    SENTINELBOX_PROFILE=datascience bash scripts/run.sh -- /bin/sh -c "free -m"

See it run

From blocking a network call to live resource charts and an agent correcting itself.

Status & roadmap

  • Phase 1 · Container primitives: namespaces, pivot_root, OverlayFS, cgroup v2, libcap
  • Phase 2 · Security sentinel: Rust, seccomp USER_NOTIF, SCM_RIGHTS
  • Phase 3 · Telemetry & database: cgroup v2 sampling, SQLite WAL audit
  • Phase 4 · MCP integration: TypeScript SDK, self-repair loop
  • Phase 5 · Management UI: React, Tailwind, Socket.io
  • eBPF probes (aya, execve tracepoint, cgroup_skb); monitor/src/ebpf is a placeholder today
  • veth plus an egress allow-list so the web / datascience network policy takes effect
  • Read path arguments via /proc/<pid>/mem to fill syscall_events.path
  • MCP tools that query the audit database and share syscall_feedback.json
  • Syscall tables beyond x86_64 (aarch64)