Securely Deploying AI Agents

A guide to securing Autohand Code and Agent SDK deployments with isolation, credential management, and network controls.

← Back to Hosting

This guide covers threat models, built-in security features, security principles, isolation technologies, credential management, and filesystem configuration for secure Agent SDK deployments.

Threat Model

Understanding the threat model is essential for securing Agent SDK deployments. Consider the following attack vectors:

  • Prompt injection: Malicious inputs attempting to manipulate agent behavior
  • Tool abuse: Agents using tools to access unauthorized resources
  • Credential exposure: API keys or secrets being leaked
  • Data exfiltration: Sensitive data being extracted through agent outputs
  • Sandbox escape: Breaking out of isolated environments

Refer to the model card for detailed information about model capabilities and limitations.

Built-in Security Features

Permissions System

Every tool and bash command can be configured to allow, block, or prompt the user for approval. Use glob patterns to create rules like "allow all npm commands" or "block any command with sudo". Organizations can set policies that apply across all users. See permissions for details.

Static Analysis

Before executing bash commands, the SDK runs static analysis to identify potentially risky operations. Commands that modify system files or access sensitive directories are flagged and require explicit user approval.

Web Search Summarization

Search results are summarized rather than passing raw content directly into the context, reducing the risk of prompt injection from malicious web content.

Sandbox Mode

Bash commands can run in a sandboxed environment that restricts filesystem and network access. See the sandboxing documentation for details.

Security Principles

Security Boundaries

Establish clear security boundaries between the agent and your systems:

  • Separate agent execution from production infrastructure
  • Use network segmentation to limit agent access
  • Implement filesystem isolation for code and data
  • Apply least privilege to all agent operations

Least Privilege

Grant agents only the minimum permissions needed to complete their tasks:

  • Restrict tool access to only necessary tools
  • Limit filesystem access to specific directories
  • Use role-based access control for different agent types
  • Regularly audit and remove unnecessary permissions

Defense in Depth

Implement multiple layers of security controls:

  • Container isolation
  • Network restrictions
  • Filesystem controls
  • Request validation at a proxy

Isolation Technologies

Sandbox Runtime

The sandbox runtime provides OS-level isolation for agent execution:

Filesystem

Uses OS primitives (bubblewrap on Linux, sandbox-exec on macOS) to restrict read/write access to configured paths.

Network

Removes network namespace (Linux) or uses Seatbelt profiles (macOS) to route network traffic through a built-in proxy.

Configuration

JSON-based allowlists for domains and filesystem paths.

Limitations
  • Same-host kernel: Unlike VMs, sandboxed processes share the host kernel. A kernel vulnerability could theoretically enable escape. For some threat models this is acceptable, but if you need kernel-level isolation, use gVisor or a separate VM.
  • No TLS inspection: The proxy allowlists domains but doesn't inspect encrypted traffic. If the agent has permissive credentials for an allowed domain, ensure it isn't possible to use that domain to trigger other network requests or to exfiltrate data.

Containers

Docker containers provide additional isolation layers:

Recommended Docker Configuration
Security Flags Explained
  • --cap-drop ALL: Drop all Linux capabilities (except NET_ADMIN and SYS_ADMIN which are needed for networking)
  • --security-opt no-new-privileges: Prevent processes from gaining additional privileges
  • --security-opt seccomp=...: Apply seccomp profile to restrict system calls
  • --read-only: Make container filesystem read-only (use tmpfs for writable directories)
  • --tmpfs /tmp:...: Create in-memory filesystem for temporary files
  • --network none: Disable networking (use proxy socket for controlled access)
  • --memory 2g: Limit memory usage
  • --pids-limit 100: Limit number of processes
  • --user 1000:1000: Run as non-root user
  • -v ...:/workspace:ro: Mount code as read-only (prevents agent from modifying code)
  • -v .../proxy.sock:...: Mount proxy socket for controlled network access
Additional Security Measures
  • Avoid mounting sensitive directories like ~/.ssh, ~/.aws, ~/.config
  • Use --userns-remap for user namespace remapping
  • Use --ipc private for IPC namespace isolation

gVisor

gVisor provides user-space kernel for stronger isolation:

Virtual Machines

For the strongest isolation, use virtual machines. Consider:

  • AWS Nitro Enclaves
  • Google Confidential Computing
  • Azure Confidential Computing
  • Firecracker microVMs

VMs provide kernel-level isolation and are suitable for high-security deployments.

Cloud Deployments

For cloud deployments, follow these security practices:

  1. Run agent containers in a private subnet with no internet gateway
  2. Configure cloud firewall rules (AWS Security Groups, GCP VPC firewall) to block all egress except to your proxy
  3. Run a proxy (such as Envoy with its credential_injector filter) that validates requests, enforces domain allowlists, injects credentials, and forwards to external APIs
  4. Assign minimal IAM permissions to the agent's service account, routing sensitive access through the proxy where possible
  5. Log all traffic at the proxy for audit purposes

Credential Management

The Proxy Pattern

The proxy pattern centralizes credential management:

Benefits
  1. The agent never sees the actual credentials
  2. The proxy can enforce an allowlist of permitted endpoints
  3. The proxy can log all requests for auditing
  4. Credentials are stored in one secure location rather than distributed to each agent

Configuring the SDK to Use a Proxy

For API Requests
For All Traffic

Implementing a Proxy

Recommended Proxy Solutions
  • Envoy Proxy: Production-grade proxy with credential_injector filter for adding auth headers
  • mitmproxy: TLS-terminating proxy for inspecting and modifying HTTPS traffic
  • Squid: Caching proxy with access control lists
  • LiteLLM: LLM gateway with credential injection and rate limiting

Credentials for Other Services

Custom Tools
  • No TLS interception: The external service makes authenticated requests directly
  • Credentials stay outside: The agent only sees the tool interface, not the underlying credentials
Traffic Forwarding

To intercept all traffic (including from tools):

  1. Running the proxy outside the agent's container
  2. Installing the proxy's CA certificate in the agent's trust store (so the agent trusts the proxy's certificates)
  3. Configuring HTTP_PROXY/HTTPS_PROXY to route traffic through the proxy

For Node.js, use NODE_USE_ENV_PROXY=1 to ensure fetch() respects proxy settings. Alternatively, use tools like proxychains.

Filesystem Configuration

Read-Only Code Mounting

Mount code as read-only to prevent agents from modifying it:

Files to Exclude

Ensure your .dockerignore excludes sensitive files:

Writable Locations

Use tmpfs for writable directories that don't need persistence:

Benefits of tmpfs
  • Data is stored in memory, not on disk
  • No persistence between container restarts
  • Can set size limits to prevent resource exhaustion
  • Can disable execution with noexec

Next Steps

🚀 Hosting

Learn about different hosting options for your Agent SDK applications.

Hosting Guide →

📚 Tutorials

Explore more tutorials for building with the Agent SDK.

View Tutorials →

📖 API Reference

Check the API reference for detailed documentation.

API Reference →