Agent Shell安全执行层

ESF+NE mode (full enforcement — Alpha, requires Xcode 15+)

make build-macos-enterprise ```

See macOS Build Guide for detailed macOS build instructions.

---

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.

```bash

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.

Quick start

Example for Debian/Ubuntu

sudo dpkg -i agentsh_<VERSION>_linux_amd64.deb

**From source (Linux)**

**From source (macOS)**

Example rules (trimmed)

version: 1
name: default

file_rules:
  - name: allow-workspace
    paths: ["/workspace", "/workspace/**"]
    operations: [read, open, stat, list, write, create, mkdir, chmod, rename]
    decision: allow

  - name: approve-workspace-delete
    paths: ["/workspace", "/workspace/**"]
    operations: [delete, rmdir]
    decision: approve
    message: "Delete {{.Path}}?"
    timeout: 5m

  - name: deny-ssh-keys
    paths: ["/home/**/.ssh/**", "/root/.ssh/**"]
    operations: ["*"]
    decision: deny

network_rules:
  - name: allow-api
    domains: ["api.example.com"]
    ports: [443]
    decision: allow

command_rules:
  - name: block-dangerous
    commands: ["rm", "shutdown", "reboot"]
    decision: deny

---

Use Cases

• API Gateway Routing: Route Anthropic/OpenAI calls through corporate LLM gateway
• Provider Switching: Redirect Claude API to GCP Vertex AI or Azure OpenAI
• Testing: Redirect production APIs to mock servers
• Compliance: Force all LLM traffic through audit proxies

---

Example Signal Rules

signal_rules:
  # Allow signals to self and children
  - name: allow-self
    signals: ["@all"]
    target:
      type: self
    decision: allow

  - name: allow-children
    signals: ["@all"]
    target:
      type: children
    decision: allow

  # Redirect SIGKILL to graceful SIGTERM
  - name: graceful-kill
    signals: ["SIGKILL"]
    target:
      type: children
    decision: redirect
    redirect_to: SIGTERM

  # Block fatal signals to external processes
  - name: deny-external-fatal
    signals: ["@fatal"]
    target:
      type: external
    decision: deny

AI Assistant Integration Examples

Ready-to-use snippets for configuring AI coding assistants to use agentsh:

• Claude Code - CLAUDE.md snippet for Claude Code integration
• Cursor - Cursor rules for agentsh integration
• AGENTS.md - Generic AGENTS.md snippet (works with multiple AI tools)

Note: These examples are for local development scenarios where running the AI agent inside a container isn't practical. For production or CI/CD environments, prefer running agents in containers with the shell shim installed—see Use in Docker.

---

60-second demo

The fastest way to "get it" is to run something that spawns subprocesses and touches the filesystem/network.

```bash

Start the server (optional if using autostart)

./bin/agentsh server --config configs/server-config.yaml

Environment policy quick reference

• Defaults: With no env_allow, agentsh builds a minimal env (PATH/LANG/TERM/HOME) and strips built-in secret keys.
• Overrides: Per-command env_allow/env_deny plus env_max_keys/env_max_bytes cap and filter the child env at exec time.
• Block iteration: env_block_iteration: true (global or per rule) hides env enumeration; set policies.env_shim_path to libenvshim.so so agentsh injects LD_PRELOAD + AGENTSH_ENV_BLOCK_ITERATION=1.
• Limits: Errors if limits are exceeded; env builder is applied before exec for every command.
• env_inject: Operator-trusted environment variables injected into all commands, bypassing policy filtering. Primary use: BASH_ENV to disable shell builtins that bypass seccomp. Configure in sandbox.env_inject (global) or policy-level env_inject (overrides global).
• Examples: See config.yml and policy samples under configs/.

---

Options

References

• MCP Protection Demo: agentsh-mcp-protection-demo - live demo of cross-server exfiltration detection, rug pull blocking, and policy generation
• Security & threat model: SECURITY.md - what agentsh protects against, known limitations, operator checklist
• External KMS: SECURITY.md#external-kms-integration - AWS KMS, Azure Key Vault, HashiCorp Vault, GCP Cloud KMS for audit integrity keys
• Config template: configs/server-config.yaml
• Default policy: configs/policies/default.yaml
• Example Dockerfile (with shim): Dockerfile.example
• Policy documentation: docs/operations/policies.md - policy variables, signal rules, network redirect
• Database access control: docs/agentsh-db-access-spec.md - Postgres-only database enforcement scope, policy semantics, redirect behavior, and roadmap
• Command policies cookbook: docs/cookbook/command-policies.md - how to allow a new binary, when to use wrap instead of exec, and how to debug a denial
• HTTP services cookbook: docs/cookbook/http-services.md - recipes for routing outbound HTTP API calls through declared services with rules and approval gating
• Sandbox SDK integrations cookbook: docs/cookbook/sandbox-sdk-integrations.md - shim_install config for Tensorlake / E2B / Modal / Daytona where commands run as siblings of the agentsh server
• Policy authoring skills: skills/ - AI-assistant skills for creating and editing policies in Claude Code, NanoClaw, etc.
• Platform comparison: docs/platform-comparison.md - feature support, security scores, performance by platform
• Bubblewrap vs agentsh: docs/bubblewrap-vs-agentsh-comparison.md - comparison with Bubblewrap for Linux container sandboxing
• Database access control: docs/agentsh-db-access-spec.md - PostgreSQL proxy taxonomy, effects model, database_rules, connection rules, threat model
• Security modes & detect: docs/security-modes.md - enforcement modes, protection score, and what agentsh detect reports
• seccomp: docs/seccomp.md - syscall filtering, execve interception, and socket-family blocking
• ptrace mode: docs/ptrace-support.md - PTRACE_SEIZE enforcement for restricted containers (attach_mode, seccomp prefilter)
• eBPF: docs/ebpf.md - eBPF network tracing & policy enforcement
• LLM Proxy & DLP: docs/llm-proxy.md - embedded proxy configuration, DLP patterns, usage tracking
• macOS build guide: docs/macos-build.md - ESF+NE build instructions
• macOS ESF+NE architecture: docs/macos-esf-ne-architecture.md - System Extension, XPC, and deployment details
• macOS XPC sandbox: docs/macos-xpc-sandbox.md - XPC/Mach IPC control for sandboxed processes
• Environment variables (all AGENTSH_* overrides, auto-start toggles, transport selection): docs/spec.md &sect;15.3 "Environment Variables"
• Architecture & data flow (FUSE + policy engine + API): inline comments in configs/server-config.yaml and internal/netmonitor
• CLI help: agentsh --help, agentsh exec --help, agentsh shim --help

---

Created with the help of agents for agents.