Features - agentsh

Execution-layer capabilities of agentsh — traffic control, data protection, deterministic enforcement, and operational tools.
Most systems can deny an action. agentsh can also steer it to an approved alternative.
When an agent tries the wrong approach (or brute-force workarounds), policy can steer it to the right path—keeping the agent productive and reducing wasted retries. The technical action is called redirect in policy files.
Instead of blocking destructive commands outright, steer the agent away with guidance:
The agent sees a successful operation (not an error), receives the guidance message, and moves on without wasting retries.
Steer agents away from shortcuts that bypass proper code review and merge workflows:
The agent receives guidance to use the proper workflow instead of attempting workarounds.
For transparent network-level routing without application changes, agentsh intercepts DNS resolution and TCP connections at the syscall level. This enables scenarios like routing API calls through internal proxies or gateways.
DNS and connect redirects only affect processes running under agentsh—not the entire system. This makes it safe to run alongside other applications.
Intercept DNS resolution and return alternative IP addresses based on hostname patterns.
Intercept TCP connections and route them to different destinations. Supports TLS/SNI rewriting for MITM proxy scenarios.
When routing through a MITM proxy that presents its own certificate, use SNI rewriting:
Route Anthropic API calls through a Vertex AI proxy with DNS and connect redirects working together:
DNS and connect redirect enforcement depends on the active backend:
Process-level network access control lists provide fine-grained control over which processes can make which network connections. ACL rules are evaluated per-process based on the executable name.
The network-acl command is also available as nacl or pnacl for convenience.
An agent that bootstraps a Tor client can tunnel straight around agentsh's carefully-built egress allowlist. Tor encrypts traffic to its relays, so once a process is on the Tor network its real destinations — any .onion service, any clearnet host — are buried inside the encrypted stream and invisible to every IP, DNS, and host control agentsh enforces. Tor is therefore treated as a category to be denied by default: near-zero legitimate use inside an agent workload, high evasion value.
The top-level tor: block is a coordinating macro — one intent (deny, audit, or allow) expands into consistent enforcement across the five ways a sandboxed process can reach Tor:
Deny-by-default holds with no external network fetch: the four cheap doors plus the built-in directory-authority seed are enough to break Tor bootstrap. audit mode emits tor_control events without blocking, for a safe rollout. When Tor is deliberately permitted (allow mode), an optional SOCKS-aware onion gateway applies per-.onion onion_rules so you can allow specific hidden services while denying the rest.
A deployment with no tor: block begins denying all five vectors the moment it upgrades to a build that ships this feature. Set tor.mode: audit or tor.enabled: false beforehand for a gentler rollout. See Policy Reference → Tor Access Control for the full schema.
agentsh includes an embedded proxy that intercepts all LLM API requests from agents.
Control how fast agents can call LLM APIs with token-bucket rate limiters for both request count and token consumption.
Requests that exceed the rate limit receive an HTTP 429 Too Many Requests response. Token consumption is tracked post-response — the actual token count from the provider response is deducted from the budget. A concurrency limiter (max 4 in-flight requests when TPM is enabled) bounds worst-case overspend.
agentsh proxies an agent's HTTP traffic to third-party APIs through a local gateway that enforces path-level and method-level access rules, substitutes credentials on the wire, and prevents credential exfiltration. Declare a service in your policy, and agentsh handles routing, filtering, and secret management in a single configuration block.
For the full schema, credential substitution model, and worked examples, see Policy Reference → HTTP Services.
How the agent's traffic reaches the gateway depends on whether the service's SDK supports a custom base URL.
A cooperative service is any API whose SDK or CLI lets you override the base URL via an environment variable, constructor parameter, or config file. agentsh sets the appropriate variable automatically (e.g., GITHUB_API_URL=http://127.0.0.1:<port>/svc/github/), so the SDK routes all traffic through the gateway without code changes. This is the cleanest integration path.
For services that do not support a base URL override, agentsh uses fail-closed network enforcement. When a service is declared in http_services: with allow_direct: false (the default), agentsh blocks any direct connection to the upstream host at the network monitor level. The agent receives a 403 with a message directing it to use the gateway URL.
For SDKs that cannot change their base URL, keep direct access blocked and use a small adapter or wrapper that calls the gateway URL exposed for the service (for example STRIPE_API_URL=http://127.0.0.1:<port>/svc/stripe). DNS and connect redirects can steer TCP to such an adapter, but http_services itself expects requests on the /svc/<name>/... gateway path.
agentsh can route declared Postgres-family database traffic through a per-session proxy. The proxy evaluates connection policy during startup, classifies SQL statements into effects, enforces strict per-object statement rules, applies optional require_where guards for scoped mutations, and emits database audit events.
Current runtime support is Postgres-family only: PostgreSQL and Aurora Postgres are the supported targets; Redshift and CockroachDB use the same path with beta coverage. Statement rules require terminate-mode TLS. Passthrough services can still us