agentsh Documentation

agentsh ("agent shell") provides execution-layer security for AI agents. Intercept file, network, and process activity at runtime—enforce policy, emit audit events, steer actions to approved alternatives.

Execution-Layer Security (ELS)#

Execution-Layer Security is a runtime enforcement model for AI agents. Instead of relying on prompts, tool descriptions, or model alignment to constrain behavior, ELS intercepts the actual system calls—file I/O, network connections, process spawning, signals—and enforces policy at the kernel level. The agent never sees the enforcement; it simply cannot perform operations that policy does not permit.

agentsh is the reference implementation of ELS. It 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. Learn more about execution-layer security →

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.

Quick Start#

Run a command that spawns subprocesses and touches the filesystem and network to see agentsh in action.

# 1) Create a session in your repo/workspace
SID=$(agentsh session create --workspace . | jq -r .id)

# 2) Run something simple (human-friendly output)
agentsh exec "$SID" -- uname -a

# 3) Run something that hits the network (JSON output + event summary)
agentsh exec --output json --events summary "$SID" -- curl -s https://example.com

# 4) Trigger a policy decision - try to delete something
agentsh exec "$SID" -- rm -rf ./tmp

# 5) See what happened (structured audit trail)
agentsh exec --output json --events all "$SID" -- ls

What you'll see in the JSON output:

• exit_code: the command's exit status
• stdout / stderr: captured output
• events[]: every file/network/process operation with policy decisions
• policy.decision: allow, deny, approve, or redirect

Installation#

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)

# Requires Xcode 15+
make build-macos-enterprise

Security Modes#

agentsh selects the best security mode based on available kernel features. Set security.mode: auto (the default) and agentsh detects available primitives at startup.

Security configuration

security:
  mode: auto              # auto | full | landlock | landlock-only | ptrace | minimal
  strict: false           # Fail if mode requirements not met
  minimum_mode: ""        # Fail if auto-detect picks worse than this
  warn_degraded: true     # Log warnings when running in degraded mode

Landlock configuration (Linux 5.13+)

When Landlock is available, configure filesystem and network restrictions:

landlock:
  enabled: true

  # Directories where command execution is allowed
  allow_execute:
    - /usr/bin
    - /bin
    - /usr/local/bin

  # Directories where reading is allowed
  allow_read:
    - /etc/ssl/certs
    - /lib
    - /usr/lib

  # Paths explicitly denied (container escape vectors)
  deny_paths:
    - /var/run/docker.sock
    - /run/containerd/containerd.sock
    - /var/run/secrets/kubernetes.io

  # Network restrictions (requires kernel 6.7+ / Landlock ABI v4)
  network:
    allow_connect_tcp: true   # Allow outbound TCP
    allow_bind_tcp: false     # Allow listening on TCP ports

Feature matrix by mode

*Relies on dropped CAP_KILL to prevent signaling external processes. **Requires kernel 6.7+ (Landlock ABI v4).

Scaling with Canyon Road#

agentsh works standalone. When you need fleet-wide visibility and central management, it integrates with the Canyon Road platform:

• Beacon — Monitors AI desktop tools (Claude, Cursor, ChatGPT) on your endpoints. Different from agentsh: Beacon watches what apps do at the OS level, while agentsh wraps agents you run directly.
• Watchtower — The control plane for both. Centralized policies, approval routing (Slack, email, SMS), SIEM export, and a kill switch when things go wrong.

Learn more at canyonroad.ai/how-it-works.