agentsh: a policy-enforced exec gateway for AI agents, reviewed from the repository

The gap agentsh targets: approval prompts stop at the tool boundary

The README states the problem directly. Agent workflows eventually run arbitrary code such as pip install, make test or python script.py, and traditional ask-before-you-run controls stop at the tool boundary and cannot see what happens inside that command. A subprocess spawned three levels down still reads files, opens sockets and writes to disk, and none of that passes back through the approval prompt that authorised the parent command. agentsh positions itself under the agent and its tooling, intercepting file, network, process and signal activity including subprocess trees, enforcing a policy and emitting structured audit events. The intended audience is anyone shipping an agent that gets shell access: platform teams running coding agents, CI pipelines that execute model-authored code, and operators who need a record of what a long-lived shell actually did. The README also frames containers as complementary rather than competing, arguing that containers isolate the host surface while agentsh adds in-container runtime visibility and path-level controls on mounted workspaces, caches and credentials. That framing is honest about scope. agentsh is not a sandbox that contains an escape; it is a policy layer that observes and rules on each operation inside whatever boundary you already have.

How enforcement works: a shim, a session, and five possible decisions

The architecture visible in the README is a drop-in shell and exec endpoint plus a policy engine. Commands are run through agentsh exec against a session id, and the README notes that any shimmed /bin/sh or /bin/bash also routes through it, so an agent that shells out indirectly is still captured. Each operation is classified and matched against rules that return one of five decisions: allow, deny, approve (human OK), soft_delete, or redirect. The redirect decision is the part worth pausing on. When policy returns redirect, the command is swapped for another and a message is returned to the caller. The README's own curl example sends curl and wget to a wrapper called agentsh-fetch with an --audit argument, and a file example sends writes to /home and /tmp into /workspace/.scratch. The README is explicit about the consequence: the agent sees a successful operation, not an error, but the operator controls where things actually land. That is a deliberate design choice with a real trade-off. Steering an agent away from a blocked path reduces retry loops, but it also means the agent's model of the filesystem diverges from reality, and any logic that later reads back what it wrote needs to tolerate the mismatch. Coverage spans file open, read, write and delete, network connect and DNS, process start and exit, PTY activity, LLM API requests with DLP and usage tracking, Postgres-family traffic through declared db_services, and signal send and block. Signals are enforced on Linux and only audited on macOS and Windows, per the README. Outbound HTTP can be routed through declared http_services with per-method and per-path rules, approval gating and fail-closed host enforcement.

Getting it running: detect, then session, then exec

On macOS the documented path is Homebrew: brew tap canyonroad/tap followed by brew install --cask agentsh, which installs the app bundle with the ESF+NE system extension and then requires approval under System Settings, General, Login Items and Extensions. On Linux the README points at .deb, .rpm or .apk artifacts from the releases page, with sudo dpkg -i agentsh_<VERSION>_linux_amd64.deb as the Debian example. Building from source on Linux is make build followed by installing bin/agentsh and bin/agentsh-shell-shim into /usr/local/bin. The macOS source path is make build-macos-enterprise and the README requires Xcode 15 or newer. Running it means starting the server with ./bin/agentsh server --config configs/server-config.yaml, creating a session with SID=$(./bin/agentsh session create --workspace . --json | jq -r .id), and then executing through it with ./bin/agentsh exec "$SID" -- ls -la. Structured output for agent consumption uses ./bin/agentsh exec --output json --events summary "$SID" -- curl https://example.com. The step I would not skip is agentsh detect, which probes the host for seccomp, Landlock, FUSE, eBPF, ptrace and cgroups and reports per-domain protection scores plus the selected security mode. agentsh detect config emits a config tuned for that host. The README states that on restricted hosts such as Daytona, E2B and Firecracker-class environments, where the seccomp user-notify listener cannot install, detect reports the mode that will actually enforce rather than what the kernel merely supports. That distinction is the difference between a policy engine and a policy suggestion. Autostart is on by default: the first agentsh exec or shimmed shell launches a local server using configs/server-config.yaml or AGENTSH_CONFIG if set, and AGENTSH_NO_AUTO=1 disables that if you want to manage the daemon yourself.

The platform matrix is the real constraint, and it is self-declared

The README does not hide this. Linux is described as full enforcement with a 100% security score. Windows WSL2 is also 100%, because it is Linux underneath. Native macOS via ESF and NE is Alpha at 90%, described as functional but not production-ready, with the top-of-file note warning of rough edges and breaking changes between releases. Native Windows via a minifilter driver plus AppContainer is 85% and blocked on driver signing, so only WSL2 mode is described as fully supported for production. Signal handling is enforced on Linux but only audited on macOS and Windows. Read together, that means the same policy file can produce different outcomes depending on the host, and one of the three platforms cannot currently block a signal at all. If your fleet is mixed, the policy you write is only as strong as its weakest host. The scores themselves come from the project's own platform comparison document, so treat them as the maintainers' assessment rather than an independent measurement. There is a second limitation worth naming: redirect decisions return success to the agent, as described above, which is a usability feature and an observability hazard at the same time. A team that monitors for failed commands will not see a redirected write as a failure. The audit stream is where you would have to catch it.

Where a plain sandbox or a container is the better answer

If your only goal is to stop an agent from damaging the host, a container or microVM already does that, and it does it with a smaller trusted computing base than a policy engine that must classify every syscall-level operation. The README concedes the relationship, describing containers as isolating the host surface while agentsh adds runtime visibility and policy inside. The practical difference is direction of effort. A container boundary answers whether the agent can reach the host; agentsh answers what the agent did inside the boundary and whether each operation was permitted. If you never need the second question, adding agentsh adds a daemon, a FUSE layer, a session lifecycle and a policy file to maintain for no benefit. The same applies if your agent only calls a fixed set of typed tools with no shell access at all. agentsh is built for the case where arbitrary code execution is the point. A narrower alternative for the redirect behaviour specifically is to wrap the individual tools yourself, for example replacing curl with an audited fetch script in the agent's PATH. That gets you steering without a kernel-level component, but it does not follow subprocess trees and it does not produce a unified audit event stream, which is exactly the gap the README opens with.

Maintenance cost, versioning and the licence

The release cadence visible in the supplied material is rapid. v0.20.5 landed on 2026-06-23, preceded by a release candidate the same day and by v0.20.4 on 2026-06-08, and the repository's last push is dated 2026-08-06. A pre-1.0 project shipping point releases this frequently means you should expect the macOS extension and the policy schema to move under you, and the README already warns of breaking changes between releases on that platform. Budget time for reading release notes before upgrading, and pin the version you install rather than tracking latest. There is also an operational cost specific to this design: the autostart server holds the FUSE layer and policy engine alive for the session lifetime, so a stale daemon or a session that is never cleaned up is a resource you are now responsible for. Setting AGENTSH_NO_AUTO=1 moves that responsibility to your own supervisor, which is usually the right call in CI. The licence is Apache-2.0, which permits commercial use and modification and includes an express patent grant. It also requires that you preserve copyright and licence notices and state significant changes, and it provides no trademark rights. That is a summary of the licence text, not legal advice; have counsel review it if you are redistributing a modified build.

Who should adopt it, and the first thing to check

The fit is a team running agents that execute shell commands, on Linux or Windows WSL2, that needs a per-operation record of file, network and process activity and wants policy decisions beyond a binary allow or deny. The mismatch is a team on native macOS or native Windows that needs enforcement today, or a team whose agents never touch a shell. The first thing to verify is not a feature list but the host itself: install the binary, run agentsh detect, and read the protection report and the selected security mode for the exact environment you intend to use. The README states plainly that on restricted hosts the tool reports the mode that will actually enforce rather than what the kernel merely supports, which means the report is the honest answer to whether this will work where you run it. If detect reports a mode weaker than you assumed, the policy file will not save you, and that is the finding to act on before anything else.

Editorial conclusion

Adopt agentsh if your agents run arbitrary shell commands and you need per-operation policy rather than a single approval prompt at the tool boundary, and if you are on Linux or Windows WSL2, which the README describes as full enforcement. Do not adopt it as a production control on native macOS, where ESF+NE is labelled Alpha, or on native Windows, where the minifilter driver is not yet signed. Before committing, run agentsh detect on the exact host you plan to use and read its protection report, because the README states the tool reports the mode that will actually enforce rather than what the kernel merely supports.

Official sources

1. canyonroad/agentsh on GitHub
2. License: Apache-2.0
3. Project website
4. README
5. Releases