Setup & Integration - agentsh

Platform support, container setup, and integrating agentsh execution-layer security with your development environment.
agentsh supports Linux, macOS, and Windows with varying levels of enforcement capability.
AI sandbox platforms vary widely in kernel feature exposure. Sprites, E2B, Daytona, and Blaxel support full mode with all enforcement layers. Others restrict FUSE mounts or seccomp user-notify, limiting enforcement to landlock or minimal modes. See the AI sandbox platforms table below for per-platform details, or run agentsh detect inside the sandbox.
100% Score Full enforcement with all features.
Linux provides the most complete security coverage:
Root or CAP_SYS_ADMIN for namespaces. eBPF requires kernel 5.x+ for full features.
Linux security capabilities depend on kernel version and runtime environment. Features are automatically detected at startup.
*Run agentsh detect to check actual capabilities in your environment. ***Firecracker supports FUSE via the new mount API (fsopen/fsmount), which does not require fusermount3.
Capabilities for hosted AI sandbox providers. Each row reflects the platform’s current kernel configuration.
*FUSE is available via deferred activation (requires chmod 666 /dev/fuse at runtime). v0 = basic Landlock (no network restrictions). Run agentsh detect inside the sandbox to verify.
Binary availability and enforcement summary by architecture and libc variant. Download the appropriate archive from the releases page.
agentsh ships native ARM64 binaries for Linux with full feature parity — LSM hooks, cgroup v2, ptrace mode, and all enforcement backends work identically to the amd64 build.
Download the arm64 tarball from the releases page, then:
Use this build on: AWS Graviton, Ampere Altra, Raspberry Pi 4/5 running 64-bit OS, Apple Silicon under Linux VMs, and any other arm64 Linux host.
Kernel feature support. The same kernel-feature requirements that apply to amd64 apply to arm64 — cgroup v2 (kernel 4.5+, recommended 5.0+ with unified hierarchy), Landlock (5.13+), eBPF/LSM (5.7+), and seccomp user-notify (5.0+). Run agentsh detect after installation to confirm available enforcement backends.
agentsh also ships statically linked musl binaries that run on Alpine Linux and other minimal distributions without glibc. The musl build has the same enforcement features as the glibc build — the difference is purely in the libc the binary links against.
Download the musl amd64 tarball from the releases page, then:
Download the musl arm64 tarball from the releases page, then:
Alpine ships BusyBox versions of standard Unix utilities (ps, find, tar, cp, etc.) that accept different flags than the GNU coreutils equivalents. This is not an agentsh limitation — it affects any policy that depends on specific flag behavior. If your policies use command_rules that match on specific argv patterns, test them against BusyBox before deploying to Alpine.
macOS supports three deployment options:
Uses Endpoint Security Framework for file monitoring and Network Extension for traffic interception.
For full Linux-equivalent isolation on macOS, run agentsh and your AI agent harness entirely inside a Lima VM.
Trade-offs: File I/O to macOS filesystem via virtiofs (15-30% overhead), VM uses ~200-500MB RAM, interact via SSH/shell into VM.
Uses mini filter driver with AppContainer sandbox isolation.
Full Linux features in Windows Subsystem for Linux.
agentsh detect probes your kernel and reports a weighted protection score (0–100) grouped into five domains:
Each backend is detected via real kernel probes, not by checking installed packages:
When a domain scores 0, actionable tips explain what is missing and the point impact (e.g., "Fine-grained filesystem control disabled (+25 pts)").
The JSON output includes per-domain active backends and a capabilities map so you can see which filesystem, network, command, resource, and isolation primitives are available.
The database proxy starts only for policies that declare db_services and set policies.db.unavoidability to observe or enforce. It is Linux-only today: non-Linux builds keep the policy parser but do not run the Postgres proxy.
For network eBPF enforcement, sandbox.cgroups.enabled: true is no longer required unless you also need memory, CPU, or PID limits. With sandbox.network.ebpf.enabled: true and resource-limit cgroups disabled, agentsh looks for an attach-only cgroup path and attaches the cgroup/connect program there. Set sandbox.network.ebpf.required: true to fail closed if neither normal nor attach-only cgroup setup works.
Use agentsh detect config to generate a configuration snippet optimized for your environment:
The generated config includes security:, platform-specific sandbox sections such as landlock:, and capabilities: entries optimized for detected features and your kernel's available backends.
In full security mode, agentsh intercepts all execve/execveat syscalls via seccomp user-notify. This provides complete execution coverage—every binary execution goes through policy, including nested commands like sh -c "curl ..." that would bypass shell-level checks.
Execve interception requires seccomp with user-notify support (Linux kernel 5.9+) and is only available in full security mode.
Command rules support a context field that enables different policies for direct (user-typed, depth 0) vs nested (script-spawned, depth 1+) commands:
All executable paths are resolved through EvalSymlinks before policy evaluation. This prevents symlink-based bypass attacks where an attacker creates a symlink (e.g., /tmp/safe → /usr/bin/wget) to circumvent command rules.
Introduced in v0.20.1, policies.symlink_escape controls FUSE-layer workspace symlinks whose targets resolve outside the workspace root. The default, evaluate, resolves the target and evaluates the resolved outside path against normal file_rules. This keeps common layouts such as Python virtualenv links to /usr/bin/python3 usable when those real paths are allowed.
Set symlink_escape: "