The sandbox intercepts agent-issued commands to shield sensitive files (like ~/.ssh/id_rsa) by enforcing platform-native isolation: sandbox-exec on macOS, bubblewrap on Linux, and Windows with WFP-based filtering.

Origin traces to Solon AI documentation and the 4.1.x sandbox module, with the Claude Code sandbox-runtime serving as the TypeScript origin for the system.

Guiding principles include opt-in writes and opt-out reads, the network being more volatile than the filesystem, and a fail-closed, fail-visibly stance to avoid unsandboxed fallbacks.

Network policy uses a local forward-proxy model (HTTP and SOCKS5) with allow/deny lists and live updates via SandboxManager.updateConfig(...), evaluating requests per connection for immediate policy changes without restarts.

The module operates without requiring a container runtime, keeping agents within the project directory while granting external access only through controlled proxies and bindings.

Two practical gotchas: ensure dependencies are present at startup (bubblewrap/socat on Linux, srt-win.exe on Windows; macOS generally needs nothing extra) and run cleanupAfterCommand() to remove placeholder bwrap files after execution.

API entry point is SandboxManager, a final class with static methods; initialize with SandboxManager.initialize(config, askCallback) and wrap commands using SandboxManager.wrapWithSandbox(...).

OS-level enforcement underpins the sandbox boundary (Seatbelt on macOS, bubblewrap on Linux, and Windows WFP), while a lightweight Java API provides a uniform cross-platform interface.

Solon AI introduces solon-ai-sandbox, a Java port of Claude Code’s sandbox-runtime, delivering filesystem and network isolation for AI agents across macOS, Linux, and Windows.

Filesystem policy is deny-by-default for writes (with a precise allowlist) and deny-then-allow for reads to protect sensitive paths, including restrictions like avoiding writes to .git directories.

Observability is proactive: violations are categorized (file_read, file_write, network) and recorded in SandboxViolationStore to signal anomalies, not just logged events.

Platform-specific wrapping varies by OS, with Windows needing wrapWithSandboxArgv and careful environment handling, while macOS and Linux use shell-wrapped commands without such Windows-specific steps.