safesurf

safesurf is a lightweight userspace sandbox for coding agents and command-line tools. It adds a reviewable policy layer for file, network, and exec access without moving the workflow into a VM, container, or kernel sandbox.

How it works

safesurf launches the target command with a preloaded shared library: LD_PRELOAD on Linux, DYLD_INSERT_LIBRARIES on macOS. The preload library wraps selected libc calls and asks a supervisor process whether each operation should continue.

Current enforcement surface:

• Filesystem: open, openat, unlink, unlinkat, rename, renameat.
• Network: IPv4/IPv6 connect, sendto, sendmsg, Linux sendmmsg, bind, listen.
• Exec: execve, execv, execvp, posix_spawn, posix_spawnp.

Warning

safesurf is a guardrail, not a security boundary. A program can bypass libc/preload enforcement with raw syscalls, unhooked APIs, static binaries, or preload environment tampering. It is meant to make coding-agent runs more predictable and reviewable, not to contain untrusted code.

Why safesurf

• Lightweight: no VM, container, daemon, kernel policy setup, or filesystem image.
• Expandable during a run: unknown access can be granted for the current session without restarting the command. One-shot OS sandboxes such as Seatbelt or Landlock generally require changing policy and rerunning.
• Reviewable: prompts and session metadata are recorded as audit logs.
• Low overhead: cached policy decisions stay close to baseline syscall cost.

Example benchmark from this repository, running on MacBook Air M1:

Both scenarios run the same open + read(1 byte) + close helper loop. baseline runs it directly; safesurf runs it through safesurf --silent run --no-audit with an all-allow policy. Helper startup is amortized over 50,000 iterations.

cargo bench -p safesurf-cli --bench io_syscall

safesurf I/O syscall benchmark
iterations=50000 repeats=7 warmups=2 op=open+read(1 byte)+close
note: each sample includes one helper process startup, amortized over iterations

scenario                                  min ns/op   median ns/op     mean ns/op   median ops/s       lat/base
baseline                                    13802.9        14865.8        14966.1          67268          1.00x
safesurf                                    14454.3        16455.7        16870.3          60769          1.11x

Example

Build the CLI and run a command with read/write access to the current repository:

cargo build --release -p safesurf-cli
./target/release/safesurf run --allow . -- cargo test

Always put -- before the command you want safesurf to run.

Documentation

• Usage guide: commands, capability flags, prompt behavior, audit logs, and macOS notes.
• Policy reference: TOML policy format and file, network, and exec rule syntax.
• Limitations: known security and platform limits.

Acknowledgements

Inspired by nono.