agentsh

macOS note: Native macOS enforcement via ESF (Endpoint Security Framework) + NE (Network Extension) is in Alpha. It works end-to-end — file, process, and network events flow through the system extension to the Go policy engine — but expect rough edges and breaking changes between releases. For production use today, we recommend Linux.

Windows note: We are working to get the minifilter drivers signed. Until then, only Windows WSL2 mode is fully supported for production use.

Secure, policy-enforced execution gateway for AI agents.

agentsh sits under your agent/tooling—intercepting file, network, process, and signal activity (including subprocess trees), enforcing the policy you define, and emitting structured audit events.

Platform note: Linux provides full enforcement (100% security score). macOS ESF+NE (90% score) is in Alpha — functional but not production-ready. Windows WSL2 provides full Linux-equivalent enforcement (100% score); native Windows via minifilter driver + AppContainer (85% score) is pending driver signing. See the Platform Comparison Matrix for details.

---

What is agentsh?

• Drop-in shell/exec endpoint that turns every command (and its subprocesses) into auditable events.
• Per-operation policy engine: allow, deny, approve (human OK), soft_delete, or redirect.
• Full I/O visibility:
  • file open/read/write/delete
  • network connect + DNS
  • process start/exit
  • PTY activity
  • LLM API requests with DLP and usage tracking
  • Postgres-family database traffic through declared db_services
  • signal send/block (Linux enforced, macOS/Windows audit)
  • database queries via the embedded PostgreSQL proxy — per-statement classification and policy
  • Route outbound HTTP API calls through declared services (http_services) with per-method, per-path rules, approval gating, and fail-closed host enforcement
• Two output modes:
  • human-friendly shell output
  • compact JSON responses for agents/tools

---

Why agentsh?

Agent workflows eventually run arbitrary code (pip install, make test, python script.py). Traditional "ask for approval before running a command" controls stop at the tool boundary and can't see what happens inside that command.

agentsh enforces policy at runtime, so hidden work done by subprocesses is still governed, logged, and (when required) approved.

---

Meaningful blocks: deny → redirect (the "steering" superpower)

Most systems can deny an action. agentsh can also redirect it.

That means when an agent tries the wrong approach (or brute-force workarounds), policy can steer it to the right path by swapping the command and returning guidance—keeping the agent on the paved road and reducing wasted retries.

Example: redirect curl to an audited wrapper

command_rules:
  - name: redirect-curl
    commands: [curl, wget]
    decision: redirect
    message: "Downloads routed through audited fetch"
    redirect_to:
      command: agentsh-fetch
      args: ["--audit"]

Example: redirect writes outside workspace back inside

file_rules:
  - name: redirect-outside-writes
    paths: ["/home/**", "/tmp/**"]
    operations: [write, create]
    decision: redirect
    redirect_to: "/workspace/.scratch"
    message: "Writes outside workspace redirected to /workspace/.scratch"

The agent sees a successful operation (not an error), but you control where things actually land.

---

Containers + agentsh: better together

Containers isolate the host surface; agentsh adds in-container runtime visibility and policy.

• Per-operation audit (files, network, commands) shows what happened during installs/builds/tests.
• Approvals and rules persist across long-lived shells and subprocess trees—not just the first command.
• Path-level controls on mounted workspaces/caches/creds; containers don't natively give that granularity.
• Same behavior on host and in containers, so CI and local dev see the same policy outcomes.

---

Quick start

Install

macOS (Homebrew)

brew tap canyonroad/tap
brew install --cask agentsh

This installs the AgentSH app bundle with the ESF+NE system extension. After installation you'll be prompted to approve the system extension in System Settings > General > Login Items & Extensions.

Linux (from a GitHub Release)

Download the .deb, .rpm, or .apk for your platform from the releases page.

# Example for Debian/Ubuntu
sudo dpkg -i agentsh_<VERSION>_linux_amd64.deb

From source (Linux)

make build
sudo install -m 0755 bin/agentsh bin/agentsh-shell-shim /usr/local/bin

From source (macOS)

# ESF+NE mode (full enforcement — Alpha, requires Xcode 15+)
make build-macos-enterprise

See macOS Build Guide for detailed macOS build instructions.

---

Run locally

# Start the server (optional if using autostart)
./bin/agentsh server --config configs/server-config.yaml

# Create a session and run a command (shell output)
SID=$(./bin/agentsh session create --workspace . --json | jq -r .id)
./bin/agentsh exec "$SID" -- ls -la

# Structured output for agents
./bin/agentsh exec --output json --events summary "$SID" -- curl https://example.com

---

Check what gets enforced

agentsh detect probes the host and reports which enforcement primitives are actually available — seccomp, Landlock, FUSE, eBPF, ptrace, cgroups — grouped into per-domain protection scores plus the selected security mode. On restricted hosts (Daytona, E2B, Firecracker-class) where the seccomp user-notify listener can't install, it reports the mode that will actually enforce rather than what the kernel merely supports.

agentsh detect              # human-readable protection report
agentsh detect config       # emit a config tuned for this host

See Security Modes for the mode matrix and tuning knobs.

---

Tell your agent to use it (AGENTS.md / CLAUDE.md snippet)

## Shell access

- Run commands via agentsh, not directly in bash/zsh.
- Use: `agentsh exec $SID -- <your-command-here>`
- For structured output: `agentsh exec --output json --events summary $SID -- <your-command-here>`
- Get session ID first: `SID=$(agentsh session create --workspace . --json | jq -r .id)`

---

Autostart (no manual daemon step)

You do not need to start agentsh server yourself.

• The first agentsh exec (or any shimmed /bin/sh//bin/bash) will automatically launch a local server using configs/server-config.yaml (or AGENTSH_CONFIG if set).
• That server keeps the FUSE layer and policy engine alive for the session lifetime; subsequent commands reuse it.
• Set AGENTSH_NO_AUTO=1 if you want to manage the server lifecycle manually.

---

Use in Docker (with the shell shim)

See Dockerfile.example for a minimal Debian-based image.

Inside the image, install a release package (or copy your build), then activate the shim:

agentsh shim install-shell \
  --root / \
  --shim /usr/bin/agentsh-shell-shim \
  --bash \
  --i-understand-this-modifies-the-host

Point the shim at your server (sidecar or host):

ENV AGENTSH_SERVER=http://127.0.0.1:18080

Now any /bin/sh -c ... or /bin/bash -lc ... in the container routes through agentsh.

Non-interactive enforcement

By default, the shim bypasses policy when stdin is not a TTY (preserving binary data for piped commands). On platforms where commands are always non-interactive but still need enforcement (e.g., exe.dev, sandbox APIs), add --force: