Secure Deployment for Claude Agent SDK Applications

## Overview

Claude Code and the Agent SDK can execute code, access files, and call external
services. Because they generate actions dynamically based on the content they
process, their behavior can be influenced by files, web pages, or user input
(prompt injection). Securing a deployment uses familiar principles: isolation,
least privilege, and defense in depth.

Not every deployment needs maximum security. A laptop differs from a multi-tenant
service processing customer data. Choose controls that fit your threat model.

## Built-in features

Claude Code includes a permissions system (allow/block/prompt per tool and bash
command, with org policies), AST-based command parsing for permission matching,
web-search summarization (reduces injection from web content), and a sandbox mode
that restricts filesystem and network access.

## Isolation options

| Technology | Isolation | Overhead | Complexity |
| --- | --- | --- | --- |
| Sandbox runtime | Good defaults | Very low | Low |
| Containers (Docker) | Setup dependent | Low | Medium |
| gVisor | Excellent | Medium/High | Medium |
| VMs (Firecracker/QEMU) | Excellent | High | Medium/High |

The agent always runs inside the boundary. `@anthropic-ai/sandbox-runtime`
enforces filesystem and network restrictions at the OS level with minimal setup.
A hardened container drops all capabilities, runs read-only with tmpfs, runs as a
non-root user, sets `--network none`, and reaches the outside only through a
mounted Unix socket to a host proxy. gVisor intercepts syscalls in userspace for a
smaller kernel attack surface; VMs add hardware-level isolation.

## Hardened Container Example

A security-hardened container configuration might look like this:

```bash
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
```

| 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 |
| `--read-only` | Makes the container's root filesystem immutable, preventing the agent from persisting changes |
| `--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 |

## Least privilege

Restrict the agent to what its task needs: mount only required directories
(prefer read-only), restrict network to specific endpoints via a proxy, inject
credentials rather than exposing them, and drop Linux capabilities in containers.

## The credential proxy pattern

Run a proxy outside the agent boundary that injects credentials into outgoing
requests. The agent sends requests without secrets; the proxy adds them, enforces
an endpoint allowlist, and logs traffic. For Claude API calls, set
`ANTHROPIC_BASE_URL` to your proxy (plaintext, can inject) or `HTTP_PROXY` /
`HTTPS_PROXY` (system-wide; HTTPS needs a TLS-terminating proxy with a trusted CA
to modify). For other services, prefer a custom tool/MCP server that performs the
authenticated call outside the boundary.

## Filesystem controls

Mount code read-only when the agent only needs to analyze it, and exclude or
sanitize credential files (`.env`, `~/.git-credentials`, `~/.aws/credentials`,
`.npmrc`, `*.pem`) even from read-only mounts. For writable workspaces, use tmpfs
(ephemeral) or a dedicated volume kept separate from sensitive directories; an
overlay filesystem lets you review changes before persisting.

## Cloud deployments

Run agents in a private subnet with no internet gateway, block egress except to
your proxy with cloud firewall rules, validate and log requests at the proxy, and
assign minimal IAM to the agent's service account.

## Source

- Securely deploying AI agents: https://code.claude.com/docs/en/agent-sdk/secure-deployment