Getting Started - agentsh

agentsh ("agent shell") provides execution-layer security for AI agents. Intercept file, network, process, and Postgres-family database activity at runtime—enforce policy, emit audit events, steer actions to approved alternatives.
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, database, and signal activity (including subprocess trees), enforcing the policy you define, and emitting structured audit events. Learn more about execution-layer security →
Turns every command (and its subprocesses) into auditable events.
Per-operation decisions: allow, deny, approve, redirect, or soft_delete.
File I/O, network, DNS, process lifecycle, PTY activity, and LLM requests.
Human-friendly shell output or compact JSON for agents/tools.
Swap commands or file paths to keep agents on the paved road.
Intercept API requests, redact PII, and track token usage.
Enforce connection and statement policy on declared Postgres services.
Snapshot workspace state and rollback destructive operations.
Linux, macOS, and Windows with native enforcement mechanisms.
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.
Run a command that spawns subprocesses and touches the filesystem and network to see agentsh in action.
What you'll see in the JSON output:
Download the .deb, .rpm, Arch package, or tarball for your platform from the releases page.
agentsh selects the best configured security mode based on available kernel features. Set security.mode: auto (the default) and agentsh detects available primitives at startup. Ptrace enforcement is an opt-in backend configured under sandbox.ptrace, not a security.mode value.
Run agentsh detect to see a weighted protection score (0–100) grouped by domain—File Protection, Command Control, Network, Resource Limits, and Isolation—with actionable tips for missing capabilities. See Detecting Capabilities.
When Landlock is available, configure filesystem and network restrictions:
*Relies on dropped CAP_KILL to prevent signaling external processes. **Requires kernel 6.7+ (Landlock ABI v4).
agentsh works standalone. When you need fleet-wide visibility and central management, it integrates with the Canyon Road platform:
Learn more at canyonroad.ai/how-it-works.
See the GitHub repository for more examples, the full spec, and to report issues.