--- title: "Securely deploying AI agents" description: "> ## Documentation Index > Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt > Use this file to discover all available pages before exploring further." type: skill canonical_url: https://claudary.paisolsolutions.com/skills/agent-sdk-secure-deployment source: "Claudary" difficulty: intermediate author: "Claude Code Knowledge Pack" date: 2026-07-10T11:07:16.905Z license: CC-BY-4.0 attribution: "Securely deploying AI agents — Claudary (https://claudary.paisolsolutions.com/skills/agent-sdk-secure-deployment)" --- # Securely deploying AI agents > ## Documentation Index > Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt > Use this file to discover all available pages before exploring further. ## Overview > ## Documentation Index > Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # Securely deploying AI agents > A guide to securing Claude Code and Agent SDK deployments with isolation, credential management, and network controls Claude Code and the Agent SDK are powerful tools that can execute code, access files, and interact with external services on your behalf. Like any tool with these capabilities, deploying them thoughtfully ensures you get the benefits while maintaining appropriate controls. Unlike traditional software that follows predetermined code paths, these tools generate their actions dynamically based on context and goals. This flexibility is what makes them useful, but it also means their behavior can be influenced by the content they process: files, webpages, or user input. This is sometimes called prompt injection. For example, if a repository's README contains unusual instructions, Claude Code might incorporate those into its actions in ways the operator didn't anticipate. This guide covers practical ways to reduce this risk. The good news is that securing an agent deployment doesn't require exotic infrastructure. The same principles that apply to running any semi-trusted code apply here: isolation, least privilege, and defense in depth. Claude Code includes several security features that help with common concerns, and this guide walks through these along with additional hardening options for those who need them. Not every deployment needs maximum security. A developer running Claude Code on their laptop has different requirements than a company processing customer data in a multi-tenant environment. This guide presents options ranging from Claude Code's built-in security features to hardened production architectures, so you can choose what fits your situation. ## Threat model Agents can take unintended actions due to prompt injection (instructions embedded in content they process) or model error. Claude models are designed to resist this; see the [model overview](https://platform.claude.com/docs/en/about-claude/models/overview) and the system card for the model you deploy for evaluation details. Defense in depth is still good practice though. For example, if an agent processes a malicious file that instructs it to send customer data to an external server, network controls can block that request entirely. ## Built-in security features Claude Code includes several security features that address common concerns. See the [security documentation](/en/security) for full details. * **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](/en/permissions). * **Command parsing for permissions**: Before executing bash commands, Claude Code parses them into an AST and matches the result against your permission rules. Commands that cannot be parsed cleanly, or that do not match an allow rule, require explicit approval. A small set of constructs such as `eval` always require approval regardless of allow rules. This is a permission gate, not a sandbox; it does not infer whether a command is dangerous from its target path or effects. * **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](/en/sandboxing) for details. ## Security principles For deployments that require additional hardening beyond Claude Code's defaults, these principles guide the available options. ### Security boundaries A security boundary separates components with different trust levels. For high-security deployments, you can place sensitive resources (like credentials) outside the boundary containing the agent. If something goes wrong in the agent's environment, resources outside that boundary remain protected. For example, rather than giving an agent direct access to an API key, you could run a proxy outside the agent's environment that injects the key into requests. The agent can make API calls, but it never sees the credential itself. This pattern is useful for multi-tenant deployments or when processing untrusted content. ### Least privilege When needed, you can restrict the agent to only the capabilities required for its specific task: | Resource | Restriction options | | ------------------- | ----------------------------------------------- | | Filesystem | Mount only needed directories, prefer read-only | | Network | Restrict to specific endpoints via proxy | | Credentials | Inject via proxy rather than exposing directly | | System capabilities | Drop Linux capabilities in containers | ### Defense in depth For high-security environments, layering multiple controls provides additional protection. Options include: * Container isolation * Network restrictions * Filesystem controls * Request validation at a proxy The right combination depends on your threat model and operational requirements. ## Isolation technologies Different isolation technologies offer different tradeoffs between security strength, performance, and operational complexity. In all of these configurations, Claude Code (or your Agent SDK application) runs inside the isolation boundary (the sandbox, container, or VM). The security controls described below restrict what the agent can access from within that boundary. | Technology | Isolation strength | Performance overhead | Complexity | | ----------------------- | ------------------------------ | -------------------- | ----------- | | Sandbox runtime | Good (secure defaults) | Very low | Low | | Containers (Docker) | Setup dependent | Low | Medium | | gVisor | Excellent (with correct setup) | Medium/High | Medium | | VMs (Firecracker, QEMU) | Excellent (with correct setup) | High | Medium/High | ### Sandbox runtime For lightweight isolation without containers, [sandbox-runtime](https://github.com/anthropic-experimental/sandbox-runtime) enforces filesystem and network restrictions at the OS level. The main advantage is simplicity: no Docker configuration, container images, or networking setup required. The proxy and filesystem restrictions are built in. You provide a settings file specifying allowed domains and paths. **How it works:** * **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 **Setup:** ```bash theme={null} npm install @anthropic-ai/sandbox-runtime ``` Then create a configuration file specifying allowed paths and domains. **Security considerations:** 1. **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. 2. **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. For many single-developer and CI/CD use cases, sandbox-runtime raises the bar significantly with minimal setup. The sections below cover containers and VMs for deployments requiring stronger isolation. ### Containers Containers provide isolation through Linux namespaces. Each container has its own view of the filesystem, process tree, and network stack, while sharing the host kernel. A security-hardened container configuration might look like this: ```bash theme={null} docker run \\ --cap-drop ALL \\ --security-opt no-new-privileges \\ --security-opt seccomp=/path/to/seccomp-profile.json \\ --read-only \\ --tmpfs /tmp:rw,noexec,nosuid,size=100m \\ --tmpfs /home/agent:rw,noexec,nosuid,size=500m \\ --network none \\ --memory 2g \\ --cpus 2 \\ --pids-limit 100 \\ --user 1000:1000 \\ -v /path/to/code:/workspace:ro \\ -v /var/run/proxy.sock:/var/run/proxy.sock:ro \\ agent-image ``` Here's what each option does: | Option | Purpose | | ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | | `--cap-drop ALL` | Removes Linux capabilities like `NET_ADMIN` and `SYS_ADMIN` that could enable privilege escalation | | `--security-opt no-new-privileges` | Prevents processes from gaining privileges through setuid binaries | | `--security-opt seccomp=...` | Restricts available syscalls; Docker's default blocks \\~44, custom profiles can block more | | `--read-only` | Makes the container's root filesystem immutable, preventing the agent from persisting changes | | `--tmpfs /tmp:...` | Provides a writable temporary directory that's cleared when the container stops | | `--network none` | Removes all network interfaces; the agent communicates through the mounted Unix socket below | | `--memory 2g` | Limits memory usage to prevent resource exhaustion | | `--pids-limit 100` | Limits process count to prevent fork bombs | | `--user 1000:1000` | Runs as a non-root user | | `-v ...:/workspace:ro` | Mounts code read-only so the agent can analyze but not modify it. **Avoid mounting sensitive host directories like `~/.ssh`, `~/.aws`, or `~/.config`** | | `-v .../proxy.sock:...` | Mounts a Unix socket connected to a proxy running outside the container (see below) | **Unix socket architecture:** With `--network none`, the container has no network interfaces at all. The only way for the agent to reach the outside world is through the mounted Unix socket, which connects to a proxy running on the host. This proxy can enforce domain allowlists, inject credentials, and log all traffic. This is the same architecture used by [sandbox-runtime](https://github.com/anthropic-experimental/sandbox-runtime). Even if the agent is compromised via prompt injection, it cannot exfiltrate data to arbitrary servers. It can only communicate through the proxy, which controls what domains are reachable. For more details, see the [Claude Code sandboxing blog post](https://www.anthropic.com/engineering/claude-code-sandboxing). **Additional hardening options:** | Option | Purpose | | ---------------- | -------------------------------------------------------------------------------------------------------------------- | | `--userns-remap` | Maps container root to unprivileged host user; requires daemon configuration but limits damage from container escape | | `--ipc private` | Isolates inter-process communication to prevent cross-container attacks | ### gVisor Standard containers share the host kernel: when code inside a container makes a system call, it goes directly to the same kernel that runs the host. This means a kernel vulnerability could allow container escape. gVisor addresses this by intercepting system calls in userspace before they reach the host kernel, implementing its own compatibility layer that handles most syscalls without involving the real kernel. If an agent runs malicious code (perhaps due to prompt injection), that code runs in the container and could attempt kernel exploits. With gVisor, the attack surface is much smaller: the malicious code would need to exploit gVisor's userspace implementation first and would have limited access to the real kernel. To use gVisor with Docker, install the `runsc` runtime and configure the daemon: ```json theme={null} // /etc/docker/daemon.json { "runtimes": { "runsc": { "path": "/usr/local/bin/runsc" } } } ``` Then run containers with: ```bash theme={null} docker run --runtime=runsc agent-image ``` **Performance considerations:** | Workload | Overhead | | --------------------- | -------------------------------------------------- | | CPU-bound computation | \\~0% (no syscall interception) | | Simple syscalls | \\~2× slower | | File I/O intensive | Up to 10-200× slower for heavy open/close patterns | For multi-tenant environments or when processing untrusted content, the additional isolation is often worth the overhead. ### Virtual machines VMs provide hardware-level isolation through CPU virtualization extensions. Each VM runs its own kernel, creating a strong boundary. A vulnerability in the guest kernel doesn't directly compromise the host. However, VMs aren't automatically "more secure" than alternatives like gVisor. VM security depends heavily on the hypervisor and device emulation code. Firecracker is designed for lightweight microVM isolation. It can boot VMs in under 125ms with less than 5 MiB memory overhead, stripping away unnecessary device emulation to reduce attack surface. With this approach, the agen --- Source: [Claudary](https://claudary.paisolsolutions.com/skills/agent-sdk-secure-deployment) · https://claudary.paisolsolutions.com