{"id":39310301,"url":"https://github.com/canyonroad/agentsh","last_synced_at":"2026-04-11T20:01:40.523Z","repository":{"id":329870743,"uuid":"1117787577","full_name":"canyonroad/agentsh","owner":"canyonroad","description":"Execution-Layer Security (ELS) for AI agents — policy-enforced shell with audit.","archived":false,"fork":false,"pushed_at":"2026-04-09T03:11:51.000Z","size":8669,"stargazers_count":175,"open_issues_count":3,"forks_count":5,"subscribers_count":2,"default_branch":"main","last_synced_at":"2026-04-09T03:28:04.612Z","etag":null,"topics":["agentic-ai","agents","ai","els","enforments","executionlayersecurity","policy"],"latest_commit_sha":null,"homepage":"https://www.agentsh.org","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/canyonroad.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2025-12-16T20:16:00.000Z","updated_at":"2026-04-09T03:11:38.000Z","dependencies_parsed_at":"2026-02-08T23:03:21.958Z","dependency_job_id":null,"html_url":"https://github.com/canyonroad/agentsh","commit_stats":null,"previous_names":["erans/agentsh"],"tags_count":78,"template":false,"template_full_name":null,"purl":"pkg:github/canyonroad/agentsh","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/canyonroad%2Fagentsh","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/canyonroad%2Fagentsh/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/canyonroad%2Fagentsh/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/canyonroad%2Fagentsh/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/canyonroad","download_url":"https://codeload.github.com/canyonroad/agentsh/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/canyonroad%2Fagentsh/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31693274,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-11T13:07:20.380Z","status":"ssl_error","status_checked_at":"2026-04-11T13:06:47.903Z","response_time":54,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agentic-ai","agents","ai","els","enforments","executionlayersecurity","policy"],"created_at":"2026-01-18T01:42:01.772Z","updated_at":"2026-04-11T20:01:40.516Z","avatar_url":"https://github.com/canyonroad.png","language":"Go","readme":"# agentsh\n\n\u003e **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.\n\u003e\n\u003e **Windows note:** We are working to get the minifilter drivers signed. Until then, only Windows WSL2 mode is fully supported for production use.\n\n**Secure, policy-enforced execution gateway for AI agents.**\n\nagentsh 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**.\n\n\u003e **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](docs/platform-comparison.md) for details.\n\n---\n\n## What is agentsh?\n\n- **Drop-in shell/exec endpoint** that turns every command (and its subprocesses) into auditable events.\n- **Per-operation policy engine**: `allow`, `deny`, `approve` (human OK), `soft_delete`, or `redirect`.\n- **Full I/O visibility**:\n  - file open/read/write/delete\n  - network connect + DNS\n  - process start/exit\n  - PTY activity\n  - LLM API requests with DLP and usage tracking\n  - signal send/block (Linux enforced, macOS/Windows audit)\n  - Route outbound HTTP API calls through declared services (**http_services**) with per-method, per-path rules, approval gating, and fail-closed host enforcement\n- **Two output modes**:\n  - human-friendly shell output\n  - compact JSON responses for agents/tools\n\n---\n\n## Why agentsh?\n\nAgent 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.\n\nagentsh enforces policy **at runtime**, so hidden work done by subprocesses is still governed, logged, and (when required) approved.\n\n---\n\n## Meaningful blocks: deny → redirect (the \"steering\" superpower)\n\nMost systems can *deny* an action. agentsh can also **redirect** it.\n\nThat 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.\n\n**Example: redirect curl to an audited wrapper**\n\n```yaml\ncommand_rules:\n  - name: redirect-curl\n    commands: [curl, wget]\n    decision: redirect\n    message: \"Downloads routed through audited fetch\"\n    redirect_to:\n      command: agentsh-fetch\n      args: [\"--audit\"]\n```\n\n**Example: redirect writes outside workspace back inside**\n\n```yaml\nfile_rules:\n  - name: redirect-outside-writes\n    paths: [\"/home/**\", \"/tmp/**\"]\n    operations: [write, create]\n    decision: redirect\n    redirect_to: \"/workspace/.scratch\"\n    message: \"Writes outside workspace redirected to /workspace/.scratch\"\n```\n\nThe agent sees a successful operation (not an error), but you control where things actually land.\n\n---\n\n## Containers + agentsh: better together\n\nContainers isolate the host surface; agentsh adds **in-container runtime visibility and policy**.\n\n- Per-operation audit (files, network, commands) shows what happened during installs/builds/tests.\n- Approvals and rules persist across long-lived shells and subprocess trees—not just the first command.\n- Path-level controls on mounted workspaces/caches/creds; containers don't natively give that granularity.\n- Same behavior on host and in containers, so CI and local dev see the same policy outcomes.\n\n---\n\n## Quick start\n\n### Install\n\n**macOS (Homebrew)**\n\n```bash\nbrew tap canyonroad/tap\nbrew install --cask agentsh\n```\n\nThis 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 \u003e General \u003e Login Items \u0026 Extensions**.\n\n**Linux (from a GitHub Release)**\n\nDownload the `.deb`, `.rpm`, or `.apk` for your platform from the [releases page](https://github.com/erans/agentsh/releases).\n\n```bash\n# Example for Debian/Ubuntu\nsudo dpkg -i agentsh_\u003cVERSION\u003e_linux_amd64.deb\n```\n\n**From source (Linux)**\n\n```bash\nmake build\nsudo install -m 0755 bin/agentsh bin/agentsh-shell-shim /usr/local/bin\n```\n\n**From source (macOS)**\n\n```bash\n# ESF+NE mode (full enforcement — Alpha, requires Xcode 15+)\nmake build-macos-enterprise\n```\n\nSee [macOS Build Guide](docs/macos-build.md) for detailed macOS build instructions.\n\n---\n\n### Run locally\n\n```bash\n# Start the server (optional if using autostart)\n./bin/agentsh server --config configs/server-config.yaml\n\n# Create a session and run a command (shell output)\nSID=$(./bin/agentsh session create --workspace . | jq -r .id)\n./bin/agentsh exec \"$SID\" -- ls -la\n\n# Structured output for agents\n./bin/agentsh exec --output json --events summary \"$SID\" -- curl https://example.com\n```\n\n---\n\n### Tell your agent to use it (AGENTS.md / CLAUDE.md snippet)\n\n```md\n## Shell access\n\n- Run commands via agentsh, not directly in bash/zsh.\n- Use: `agentsh exec $SID -- \u003cyour-command-here\u003e`\n- For structured output: `agentsh exec --output json --events summary $SID -- \u003cyour-command-here\u003e`\n- Get session ID first: `SID=$(agentsh session create --workspace . | jq -r .id)`\n```\n\n---\n\n### Autostart (no manual daemon step)\n\nYou do **not** need to start `agentsh server` yourself.\n\n* 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).\n* That server keeps the FUSE layer and policy engine alive for the session lifetime; subsequent commands reuse it.\n* Set `AGENTSH_NO_AUTO=1` if you want to manage the server lifecycle manually.\n\n---\n\n## Use in Docker (with the shell shim)\n\nSee `Dockerfile.example` for a minimal Debian-based image.\n\nInside the image, install a release package (or copy your build), then activate the shim:\n\n```bash\nagentsh shim install-shell \\\n  --root / \\\n  --shim /usr/bin/agentsh-shell-shim \\\n  --bash \\\n  --i-understand-this-modifies-the-host\n```\n\nPoint the shim at your server (sidecar or host):\n\n```dockerfile\nENV AGENTSH_SERVER=http://127.0.0.1:18080\n```\n\nNow any `/bin/sh -c ...` or `/bin/bash -lc ...` in the container routes through agentsh.\n\n### Non-interactive enforcement\n\nBy 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`:\n\n```bash\nagentsh shim install-shell \\\n  --root / \\\n  --shim /usr/bin/agentsh-shell-shim \\\n  --bash \\\n  --force \\\n  --i-understand-this-modifies-the-host\n```\n\nThis writes `/etc/agentsh/shim.conf` with `force=true`, which the shim reads at startup. The config file works regardless of how the shell is spawned (unlike env vars or profile scripts). `AGENTSH_SHIM_FORCE=1` in the process environment achieves the same effect per-process.\n\n**Recommended pattern:** run agentsh as a sidecar (or PID 1) in the same pod/service and share a workspace volume; the shim ensures every shell hop stays under policy.\n\n---\n\n## Policy model\n\n### Decisions\n\n* `allow`\n* `deny`\n* `approve` (human OK)\n* `redirect` (swap a command)\n* `audit` (allow + log)\n* `soft_delete` (quarantine deletes with restore)\n\n### Scopes\n\n* file operations\n* commands\n* environment vars\n* network (DNS/connect)\n* PTY/session settings\n* declared HTTP services\n\n### Evaluation\n\n* **first matching rule wins**\n\nRules live in a named policy; sessions choose a policy.\n\nDefaults:\n\n* sample config: `configs/server-config.yaml`\n* default policy: `configs/policies/default.yaml`\n* env override: set `AGENTSH_POLICY_NAME` to an **allowed** policy name (no suffix). If unset/invalid/disallowed, the default is used.\n* env policy: configure `policies.env_policy` (allow/deny, max_bytes, max_keys, block_iteration) and per-command `env_*` overrides in policy files. Empty allowlist defaults to minimal PATH/LANG/TERM/HOME with built-in secret deny list; set `block_iteration` to hide env iteration (requires env shim).\n* allowlist: configure `policies.allowed` in `config.yml`; empty means only the default is permitted.\n* optional integrity: set `policies.manifest_path` to a SHA256 manifest to verify policy files at load time.\n\n### Environment policy quick reference\n\n- **Defaults:** With no `env_allow`, agentsh builds a minimal env (PATH/LANG/TERM/HOME) and strips built-in secret keys.\n- **Overrides:** Per-command `env_allow`/`env_deny` plus `env_max_keys`/`env_max_bytes` cap and filter the child env at exec time.\n- **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`.\n- **Limits:** Errors if limits are exceeded; env builder is applied before exec for every command.\n- **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).\n- **Examples:** See `config.yml` and policy samples under `configs/`.\n\n---\n\n### Example rules (trimmed)\n\n```yaml\nversion: 1\nname: default\n\nfile_rules:\n  - name: allow-workspace\n    paths: [\"/workspace\", \"/workspace/**\"]\n    operations: [read, open, stat, list, write, create, mkdir, chmod, rename]\n    decision: allow\n\n  - name: approve-workspace-delete\n    paths: [\"/workspace\", \"/workspace/**\"]\n    operations: [delete, rmdir]\n    decision: approve\n    message: \"Delete {{.Path}}?\"\n    timeout: 5m\n\n  - name: deny-ssh-keys\n    paths: [\"/home/**/.ssh/**\", \"/root/.ssh/**\"]\n    operations: [\"*\"]\n    decision: deny\n\nnetwork_rules:\n  - name: allow-api\n    domains: [\"api.example.com\"]\n    ports: [443]\n    decision: allow\n\ncommand_rules:\n  - name: block-dangerous\n    commands: [\"rm\", \"shutdown\", \"reboot\"]\n    decision: deny\n```\n\n---\n\n### Using a policy\n\n```bash\n# Start the server with your policy\n./bin/agentsh server --config configs/server-config.yaml\n\n# Create a session pinned to a policy\nSID=$(./bin/agentsh session create --workspace /workspace --policy default | jq -r .id)\n\n# Exec commands; responses include decision + guidance when blocked/approved\n./bin/agentsh exec \"$SID\" -- rm -rf /workspace/tmp\n```\n\n### Authentication\n\nagentsh supports multiple authentication methods:\n\n| Type | Use Case |\n|------|----------|\n| `api_key` | Simple deployments with static keys |\n| `oidc` | Enterprise SSO (Okta, Azure AD, etc.) |\n| `hybrid` | Both methods accepted |\n\n**Approval modes** for human-in-the-loop verification:\n- `local_tty` - Terminal prompt (default)\n- `totp` - Authenticator app codes\n- `webauthn` - Hardware security keys (YubiKey)\n- `api` - Remote approval via REST\n\nSee [SECURITY.md](SECURITY.md) for configuration details.\n\n### MCP Security\n\n- **Tool Whitelisting**: Control which MCP tools can be invoked via allowlist/denylist policies\n- **Version Pinning**: Detect tool definition changes (rug pull protection) with configurable responses\n- **Cross-Server Detection**: Block data exfiltration patterns (read from Server A → send via Server B)\n- **Rate Limiting**: Token bucket rate limiting for MCP servers and network domains\n\nSee [SECURITY.md](SECURITY.md) for full configuration options, or run the **[MCP Protection Demo](https://github.com/canyonroad/agentsh-mcp-protection-demo)** to see these detections in action.\n\n---\n\n## 60-second demo\n\nThe fastest way to \"get it\" is to run something that spawns subprocesses and touches the filesystem/network.\n\n```bash\n# 1) Create a session in your repo/workspace\nSID=$(agentsh session create --workspace . | jq -r .id)\n\n# 2) Run something simple (human-friendly output)\nagentsh exec \"$SID\" -- uname -a\n# → prints system info, just like normal\n\n# 3) Run something that hits the network (JSON output + event summary)\nagentsh exec --output json --events summary \"$SID\" -- curl -s https://example.com\n# → JSON response includes: exit_code, stdout, and events[] showing dns_query + net_connect\n\n# 4) Trigger a policy decision - try to delete something\nagentsh exec \"$SID\" -- rm -rf ./tmp\n# → With default policy: prompts for approval or denies based on your rules\n\n# 5) See what happened (structured audit trail)\nagentsh exec --output json --events all \"$SID\" -- ls\n# → events[] shows every file operation, even from subprocesses\n```\n\n**What you'll see in the JSON output:**\n- `exit_code`: the command's exit status\n- `stdout` / `stderr`: captured output\n- `events[]`: every file/network/process operation with policy decisions\n- `policy.decision`: `allow`, `deny`, `approve`, or `redirect`\n\nTip: keep a terminal with `--output json` open when testing policies—it makes it obvious what's being touched.\n\n---\n\n### Session Reports\n\nGenerate markdown reports summarizing session activity:\n\n```bash\n# Quick summary\nagentsh report latest --level=summary\n\n# Detailed investigation\nagentsh report \u003csession-id\u003e --level=detailed --output=report.md\n```\n\nReports include:\n- Decision summary (allowed, blocked, redirected)\n- Automatic findings detection (violations, anomalies)\n- Activity breakdown by category\n- Full event timeline (detailed mode)\n\nSee [CI/CD Integration Guide](docs/cicd-integration.md) for pipeline examples.\n\n---\n\n### Workspace Checkpoints\n\nCreate snapshots of workspace state for recovery from destructive operations:\n\n```bash\n# Create a checkpoint before risky operations\nagentsh checkpoint create --session $SID --workspace /workspace --reason \"before cleanup\"\n\n# List checkpoints for a session\nagentsh checkpoint list --session $SID\n\n# Show what changed since a checkpoint\nagentsh checkpoint show \u003ccp-id\u003e --session $SID --workspace /workspace --diff\n\n# Preview what rollback would restore (dry-run)\nagentsh checkpoint rollback \u003ccp-id\u003e --session $SID --workspace /workspace --dry-run\n\n# Restore workspace to checkpoint state\nagentsh checkpoint rollback \u003ccp-id\u003e --session $SID --workspace /workspace\n\n# Clean up old checkpoints\nagentsh checkpoint purge --session $SID --older-than 24h --keep 5\n```\n\n**Auto-checkpoint:** When enabled, agentsh automatically creates checkpoints before risky commands (`rm`, `mv`, `git reset`, `git checkout`, etc.). Configure in `sessions.checkpoints.auto_checkpoint`.\n\nSee [SECURITY.md](SECURITY.md#checkpoint-and-rollback) for full configuration options.\n\n---\n\n### LLM Proxy and DLP\n\nagentsh includes an embedded proxy that intercepts all LLM API requests from agents:\n\n```bash\n# Check proxy status for a session\nagentsh proxy status \u003csession-id\u003e\n\n# View LLM-specific events\nagentsh session logs \u003csession-id\u003e --type=llm\n```\n\n**Features:**\n- **Automatic routing**: Sets `ANTHROPIC_BASE_URL` and `OPENAI_BASE_URL` so agent SDKs route through the proxy\n- **Custom providers**: Route to LiteLLM, Azure OpenAI, vLLM, or corporate gateways\n- **DLP redaction**: PII (emails, phone numbers, API keys, etc.) is redacted before reaching LLM providers\n- **Custom patterns**: Define organization-specific patterns for sensitive data\n- **Usage tracking**: Token counts extracted and logged for cost attribution\n- **Audit trail**: All requests/responses logged to session storage\n\n**Provider configuration:**\n\n```yaml\nproxy:\n  mode: embedded\n  providers:\n    anthropic: https://api.anthropic.com    # Default Anthropic API\n    openai: https://api.openai.com          # Default OpenAI API\n\n    # Or use alternative providers:\n    # openai: http://localhost:8000         # LiteLLM / vLLM\n    # openai: https://your-resource.openai.azure.com  # Azure OpenAI\n    # anthropic: https://llm.corp.example.com         # Corporate gateway\n```\n\n**DLP configuration:**\n\n```yaml\ndlp:\n  mode: redact\n  patterns:\n    email: true\n    api_keys: true\n  custom_patterns:\n    - name: customer_id\n      display: identifier\n      regex: \"CUST-[0-9]{8}\"\n```\n\nSee [LLM Proxy Documentation](docs/llm-proxy.md) for full configuration options.\n\nThe same proxy also dispatches declared `http_services` entries — named API upstreams with per-method, per-path rules. See [Declared HTTP Services](docs/llm-proxy.md#declared-http-services) and the [HTTP Services Cookbook](docs/cookbook/http-services.md) for details.\n\n---\n\n### Policy Generation\n\nGenerate restrictive policies from observed session behavior (\"profile-then-lock\" workflow):\n\n```bash\n# Generate policy from latest session\nagentsh policy generate latest --output=ci-policy.yaml\n\n# Generate with custom name and threshold\nagentsh policy generate abc123 --name=production-build --threshold=10\n\n# Quick preview to stdout\nagentsh policy generate latest\n```\n\nThe generated policy:\n- Allows only operations observed during the session\n- Groups paths into globs when many files in same directory\n- Collapses subdomains into wildcards (e.g., `*.github.com`)\n- Flags risky commands (curl, wget, rm) with arg patterns\n- Includes blocked operations as commented-out rules for review\n\n**Use cases:**\n- **CI/CD lockdown**: Profile a build/test run, lock future runs to that behavior\n- **Agent sandboxing**: Let an AI agent run a task, generate policy for future runs\n- **Container profiling**: Profile a workload, generate minimal policy for production\n\n---\n\n## Network Redirect\n\nagentsh can transparently redirect DNS and TCP connections, enabling use cases like routing API calls through corporate proxies or switching AI providers without code changes.\n\n### DNS Redirect\n\nIntercept DNS resolution and return configured IP addresses:\n\n```yaml\ndns_redirect:\n  - match: \"api.anthropic.com\"\n    redirect_ip: \"10.0.0.50\"\n    visibility: audit_only\n    on_failure: fail_closed\n\n  - match: \".*\\\\.openai\\\\.com\"    # Regex pattern\n    redirect_ip: \"10.0.0.51\"\n    visibility: warn\n```\n\n### Connect Redirect\n\nRedirect TCP connections to different destinations with optional TLS handling:\n\n```yaml\nconnect_redirect:\n  - match: \"api.anthropic.com:443\"\n    redirect_to: \"vertex-proxy.internal:8443\"\n    tls_mode: passthrough          # Forward encrypted traffic unchanged\n    visibility: silent\n\n  - match: \"api.openai.com:443\"\n    redirect_to: \"azure-proxy.internal:443\"\n    tls_mode: rewrite_sni          # Modify SNI in TLS ClientHello\n    rewrite_sni: \"azure-openai.example.com\"\n    visibility: audit_only\n```\n\n### Options\n\n| Field | Values | Description |\n|-------|--------|-------------|\n| `visibility` | `silent`, `audit_only`, `warn` | How redirects are logged/shown |\n| `on_failure` | `fail_closed`, `fail_open`, `retry_original` | What happens if redirect fails |\n| `tls_mode` | `passthrough`, `rewrite_sni` | TLS handling for connect redirect |\n\n### Platform Support\n\n| Feature | Linux | macOS | Windows |\n|---------|-------|-------|---------|\n| DNS Redirect | ✅ eBPF | ✅ pf/proxy | ✅ WinDivert |\n| Connect Redirect | ✅ eBPF | ✅ pf/proxy | ✅ WinDivert |\n| SNI Rewrite | ✅ | ✅ | ✅ |\n\n### Use Cases\n\n- **API Gateway Routing**: Route Anthropic/OpenAI calls through corporate LLM gateway\n- **Provider Switching**: Redirect Claude API to GCP Vertex AI or Azure OpenAI\n- **Testing**: Redirect production APIs to mock servers\n- **Compliance**: Force all LLM traffic through audit proxies\n\n---\n\n## Signal Filtering\n\nagentsh intercepts signals (`kill`, `SIGTERM`, etc.) sent between processes, providing policy-based control over which signals can reach which targets.\n\n### Platform Support\n\n| Platform | Blocking | Redirect | Audit |\n|----------|----------|----------|-------|\n| Linux | Yes (seccomp user-notify) | Yes | Yes |\n| macOS | No | No | Yes (ES) |\n| Windows | Partial | No | Yes (ETW) |\n\n### Example Signal Rules\n\n```yaml\nsignal_rules:\n  # Allow signals to self and children\n  - name: allow-self\n    signals: [\"@all\"]\n    target:\n      type: self\n    decision: allow\n\n  - name: allow-children\n    signals: [\"@all\"]\n    target:\n      type: children\n    decision: allow\n\n  # Redirect SIGKILL to graceful SIGTERM\n  - name: graceful-kill\n    signals: [\"SIGKILL\"]\n    target:\n      type: children\n    decision: redirect\n    redirect_to: SIGTERM\n\n  # Block fatal signals to external processes\n  - name: deny-external-fatal\n    signals: [\"@fatal\"]\n    target:\n      type: external\n    decision: deny\n```\n\n### Signal Groups\n\n- `@all` - All signals (1-31)\n- `@fatal` - SIGKILL, SIGTERM, SIGQUIT, SIGABRT\n- `@job` - SIGSTOP, SIGCONT, SIGTSTP, SIGTTIN, SIGTTOU\n- `@reload` - SIGHUP, SIGUSR1, SIGUSR2\n\n### Target Types\n\n- `self` - Process signaling itself\n- `children` - Direct child processes\n- `descendants` - All descendant processes\n- `session` - Any process in the agentsh session\n- `external` - PIDs outside the session\n- `system` - PID 1 and kernel threads\n\nSee [Policy Documentation](docs/operations/policies.md#signal-rules) for full configuration options.\n\n---\n\n## macOS File I/O Monitoring\n\nOn macOS, agentsh monitors file I/O using the Endpoint Security Framework (ESF), subscribing to both AUTH and NOTIFY events. Tracked operations include file open, create, delete, rename, write (detected via close-modified), and on macOS 26+, chmod and chown via attribute change events. Every file event is attributed to the originating session and command through PID-based resolution, providing full audit trails across subprocess trees.\n\nESF provides kernel-level allow/deny enforcement but does not support transparent file interception like Linux FUSE. Policy actions that require interception -- such as `redirect` (path rewriting) and `soft_delete` (quarantine) -- are implemented as deny + guidance: the operation is blocked at the ESF level and the agent receives instructions to retry with the correct path or to acknowledge that the file is protected. See the [macOS ESF+NE architecture doc](docs/macos-esf-ne-architecture.md) for event stream details and the [policy documentation](docs/operations/policies.md#file-rule-actions-on-macos-esf) for per-action behavior.\n\n---\n\n## Starter policy packs\n\nYou already have a default policy (`configs/policies/default.yaml`). These opinionated packs are available as separate files so teams can pick one:\n\n* **[`policies/dev-safe.yaml`](configs/policies/dev-safe.yaml)**: safe for local development\n  * allow workspace read/write\n  * approve deletes in workspace\n  * deny `~/.ssh/**`, `/root/.ssh/**`\n  * restrict network to allowlisted domains/ports\n\n* **[`policies/ci-strict.yaml`](configs/policies/ci-strict.yaml)**: safe for CI runners\n  * deny anything outside workspace\n  * deny outbound network except artifact registries\n  * deny interactive shells unless explicitly allowed\n  * audit everything (summary events)\n\n* **[`policies/agent-sandbox.yaml`](configs/policies/agent-sandbox.yaml)**: \"agent runs unknown code\" mode\n  * default deny + explicit allowlist\n  * approve any credential/path access\n  * redirect network tool usage to internal proxies/mirrors\n  * soft-delete destructive operations for easy recovery\n\n---\n\n## AI Assistant Integration Examples\n\nReady-to-use snippets for configuring AI coding assistants to use agentsh:\n\n* **[Claude Code](examples/claude/)** - CLAUDE.md snippet for Claude Code integration\n* **[Cursor](examples/cursor/)** - Cursor rules for agentsh integration\n* **[AGENTS.md](examples/agents/)** - Generic AGENTS.md snippet (works with multiple AI tools)\n\n\u003e **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](#use-in-docker-with-the-shell-shim).\n\n---\n\n## References\n\n* **MCP Protection Demo:** [`agentsh-mcp-protection-demo`](https://github.com/canyonroad/agentsh-mcp-protection-demo) - live demo of cross-server exfiltration detection, rug pull blocking, and policy generation\n* **Security \u0026 threat model:** [`SECURITY.md`](SECURITY.md) - what agentsh protects against, known limitations, operator checklist\n* **External KMS:** [`SECURITY.md#external-kms-integration`](SECURITY.md#external-kms-integration) - AWS KMS, Azure Key Vault, HashiCorp Vault, GCP Cloud KMS for audit integrity keys\n* Config template: [`configs/server-config.yaml`](configs/server-config.yaml)\n* Default policy: [`configs/policies/default.yaml`](configs/policies/default.yaml)\n* Example Dockerfile (with shim): [`Dockerfile.example`](Dockerfile.example)\n* **Policy documentation:** [`docs/operations/policies.md`](docs/operations/policies.md) - policy variables, signal rules, network redirect\n* **Command policies cookbook:** [`docs/cookbook/command-policies.md`](docs/cookbook/command-policies.md) - how to allow a new binary, when to use `wrap` instead of `exec`, and how to debug a denial\n* **HTTP services cookbook:** [`docs/cookbook/http-services.md`](docs/cookbook/http-services.md) - recipes for routing outbound HTTP API calls through declared services with rules and approval gating\n* **Policy authoring skills:** [`skills/`](skills/) - AI-assistant skills for creating and editing policies in Claude Code, NanoClaw, etc.\n* **Platform comparison:** [`docs/platform-comparison.md`](docs/platform-comparison.md) - feature support, security scores, performance by platform\n* **Bubblewrap vs agentsh:** [`docs/bubblewrap-vs-agentsh-comparison.md`](docs/bubblewrap-vs-agentsh-comparison.md) - comparison with Bubblewrap for Linux container sandboxing\n* **LLM Proxy \u0026 DLP:** [`docs/llm-proxy.md`](docs/llm-proxy.md) - embedded proxy configuration, DLP patterns, usage tracking\n* **macOS build guide:** [`docs/macos-build.md`](docs/macos-build.md) - ESF+NE build instructions\n* **macOS ESF+NE architecture:** [`docs/macos-esf-ne-architecture.md`](docs/macos-esf-ne-architecture.md) - System Extension, XPC, and deployment details\n* **macOS XPC sandbox:** [`docs/macos-xpc-sandbox.md`](docs/macos-xpc-sandbox.md) - XPC/Mach IPC control for sandboxed processes\n* Environment variables (all `AGENTSH_*` overrides, auto-start toggles, transport selection): [`docs/spec.md` \u0026sect;15.3 \"Environment Variables\"](docs/spec.md#153-environment-variables)\n* Architecture \u0026 data flow (FUSE + policy engine + API): inline comments in [`configs/server-config.yaml`](configs/server-config.yaml) and [`internal/netmonitor`](internal/netmonitor)\n* CLI help: `agentsh --help`, `agentsh exec --help`, `agentsh shim --help`\n\n---\n\nCreated with the help of agents for agents.\n","funding_links":[],"categories":["Sandboxing \u0026 Isolation"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcanyonroad%2Fagentsh","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcanyonroad%2Fagentsh","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcanyonroad%2Fagentsh/lists"}