---
title: "Securely Deploying AI Agents Code"
source: https://docs.autohand.ai/agent-sdk/deployments/securely-deploying-ai-agents
---

# Securely Deploying AI Agents

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

[← Back to Hosting](hosting-the-agent-sdk.html)

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](https://www.anthropic.com/claude-opus-4-6-system-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](../observability/permissions.html) 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](../tools/custom-tools.html) 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](https://www.envoyproxy.io/) 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](https://github.com/haad/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 →](hosting-the-agent-sdk.html)

### 📚 Tutorials

Explore more tutorials for building with the Agent SDK.

[View Tutorials →](../tutorials/100-code-reviewer-agent.html)

### 📖 API Reference

Check the API reference for detailed documentation.

[API Reference →](../typescript-api.html)