Despliegue seguro de agentes de IA

Claude Code y el Agent SDK son herramientas poderosas que pueden ejecutar código, acceder a archivos e interactuar con servicios externos en su nombre. Como cualquier herramienta con estas capacidades, desplegarlas cuidadosamente garantiza que obtenga los beneficios mientras mantiene controles apropiados. A diferencia del software tradicional que sigue rutas de código predeterminadas, estas herramientas generan sus acciones dinámicamente basándose en el contexto y los objetivos. Esta flexibilidad es lo que las hace útiles, pero también significa que su comportamiento puede ser influenciado por el contenido que procesan: archivos, páginas web o entrada del usuario. Esto a veces se llama inyección de indicaciones. Por ejemplo, si el README de un repositorio contiene instrucciones inusuales, Claude Code podría incorporar esas instrucciones en sus acciones de formas que el operador no anticipó. Esta guía cubre formas prácticas de reducir este riesgo. La buena noticia es que asegurar un despliegue de agentes no requiere infraestructura exótica. Los mismos principios que se aplican a ejecutar cualquier código semi-confiable se aplican aquí: aislamiento, privilegio mínimo y defensa en profundidad. Claude Code incluye varias características de seguridad que ayudan con preocupaciones comunes, y esta guía recorre estas junto con opciones de endurecimiento adicionales para quienes las necesiten. No todos los despliegues necesitan seguridad máxima. Un desarrollador ejecutando Claude Code en su portátil tiene requisitos diferentes que una empresa procesando datos de clientes en un entorno multiinquilino. Esta guía presenta opciones que van desde las características de seguridad integradas de Claude Code hasta arquitecturas de producción endurecidas, para que pueda elegir lo que se ajuste a su situación.

Modelo de amenaza

Los agentes pueden tomar acciones no intencionadas debido a inyección de indicaciones (instrucciones incrustadas en el contenido que procesan) o error del modelo. Los modelos Claude están diseñados para resistir esto; consulte la descripción general del modelo y la tarjeta del sistema para el modelo que despliega para obtener detalles de evaluación. La defensa en profundidad sigue siendo una buena práctica. Por ejemplo, si un agente procesa un archivo malicioso que le instruye enviar datos de clientes a un servidor externo, los controles de red pueden bloquear esa solicitud completamente.

Características de seguridad integradas

Claude Code incluye varias características de seguridad que abordan preocupaciones comunes. Consulte la documentación de seguridad para obtener detalles completos.

Sistema de permisos: Cada herramienta y comando bash se puede configurar para permitir, bloquear o solicitar aprobación del usuario. Use patrones glob para crear reglas como “permitir todos los comandos npm” o “bloquear cualquier comando con sudo”. Las organizaciones pueden establecer políticas que se apliquen a todos los usuarios. Consulte permisos.
Análisis de comandos para permisos: Antes de ejecutar comandos bash, Claude Code los analiza en un AST y compara el resultado con sus reglas de permisos. Los comandos que no se pueden analizar limpiamente, o que no coinciden con una regla de permiso, requieren aprobación explícita. Un pequeño conjunto de construcciones como eval siempre requieren aprobación independientemente de las reglas de permiso. Esta es una puerta de permiso, no un sandbox; no deduce si un comando es peligroso a partir de su ruta de destino o efectos.
Resumen de búsqueda web: Los resultados de búsqueda se resumen en lugar de pasar contenido sin procesar directamente al contexto, reduciendo el riesgo de inyección de indicaciones de contenido web malicioso.
Modo sandbox: Los comandos bash pueden ejecutarse en un entorno aislado que restringe el acceso al sistema de archivos y la red. Consulte la documentación de sandboxing para obtener detalles.

Principios de seguridad

Para despliegues que requieren endurecimiento adicional más allá de los valores predeterminados de Claude Code, estos principios guían las opciones disponibles.

Límites de seguridad

Un límite de seguridad separa componentes con diferentes niveles de confianza. Para despliegues de alta seguridad, puede colocar recursos sensibles (como credenciales) fuera del límite que contiene el agente. Si algo sale mal en el entorno del agente, los recursos fuera de ese límite permanecen protegidos. Por ejemplo, en lugar de dar a un agente acceso directo a una clave API, podría ejecutar un proxy fuera del entorno del agente que inyecte la clave en las solicitudes. El agente puede hacer llamadas API, pero nunca ve la credencial en sí. Este patrón es útil para despliegues multiinquilino o cuando se procesa contenido no confiable.

Privilegio mínimo

Cuando sea necesario, puede restringir el agente solo a las capacidades requeridas para su tarea específica:

Recurso	Opciones de restricción
Sistema de archivos	Montar solo directorios necesarios, preferir solo lectura
Red	Restringir a puntos finales específicos a través de proxy
Credenciales	Inyectar a través de proxy en lugar de exponer directamente
Capacidades del sistema	Descartar capacidades de Linux en contenedores

Defensa en profundidad

Para entornos de alta seguridad, superponer múltiples controles proporciona protección adicional. Las opciones incluyen:

Aislamiento de contenedores
Restricciones de red
Controles del sistema de archivos
Validación de solicitudes en un proxy

La combinación correcta depende de su modelo de amenaza y requisitos operacionales.

Tecnologías de aislamiento

Las diferentes tecnologías de aislamiento ofrecen diferentes compensaciones entre fortaleza de seguridad, rendimiento y complejidad operacional.

En todas estas configuraciones, Claude Code (o su aplicación Agent SDK) se ejecuta dentro del límite de aislamiento (el sandbox, contenedor o VM). Los controles de seguridad descritos a continuación restringen lo que el agente puede acceder desde dentro de ese límite.

Tecnología	Fortaleza de aislamiento	Sobrecarga de rendimiento	Complejidad
Sandbox runtime	Buena (valores predeterminados seguros)	Muy baja	Baja
Contenedores (Docker)	Depende de la configuración	Baja	Media
gVisor	Excelente (con configuración correcta)	Media/Alta	Media
VMs (Firecracker, QEMU)	Excelente (con configuración correcta)	Alta	Media/Alta

Sandbox runtime

Para aislamiento ligero sin contenedores, sandbox-runtime aplica restricciones de sistema de archivos y red a nivel del SO. La principal ventaja es la simplicidad: no se requiere configuración de Docker, imágenes de contenedor o configuración de red. El proxy y las restricciones del sistema de archivos están integrados. Proporciona un archivo de configuración especificando dominios y rutas permitidas. Cómo funciona:

Sistema de archivos: Utiliza primitivos del SO (bubblewrap en Linux, sandbox-exec en macOS) para restringir el acceso de lectura/escritura a rutas configuradas
Red: Elimina el espacio de nombres de red (Linux) o utiliza perfiles Seatbelt (macOS) para enrutar el tráfico de red a través de un proxy integrado
Configuración: Listas de permitidos basadas en JSON para dominios y rutas del sistema de archivos

Configuración:

npm install @anthropic-ai/sandbox-runtime

Luego cree un archivo de configuración especificando rutas y dominios permitidos. Consideraciones de seguridad:

Kernel del mismo host: A diferencia de las VMs, los procesos aislados comparten el kernel del host. Una vulnerabilidad del kernel podría teóricamente permitir escape. Para algunos modelos de amenaza esto es aceptable, pero si necesita aislamiento a nivel de kernel, use gVisor o una VM separada.
Sin inspección TLS: El proxy lista permitidos dominios basándose en el nombre de host suministrado por el cliente y no termina ni inspecciona tráfico encriptado. El código que se ejecuta dentro del sandbox puede potencialmente usar domain fronting u técnicas similares para alcanzar hosts fuera de la lista de permitidos. Si su modelo de amenaza requiere garantías más fuertes, configure un proxy que termina TLS. Consulte las limitaciones de seguridad del sandboxing para obtener más detalles. Por separado, si el agente tiene credenciales permisivas para un dominio permitido, asegúrese de que no pueda usar ese dominio para desencadenar otras solicitudes de red o para exfiltrar datos.

Para muchos casos de uso de desarrollador único y CI/CD, sandbox-runtime eleva significativamente la barra con configuración mínima. Las secciones a continuación cubren contenedores y VMs para despliegues que requieren aislamiento más fuerte.

Contenedores

Los contenedores proporcionan aislamiento a través de espacios de nombres de Linux. Cada contenedor tiene su propia vista del sistema de archivos, árbol de procesos y pila de red, mientras comparte el kernel del host. Una configuración de contenedor endurecida por seguridad podría verse así:

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

Aquí está lo que hace cada opción:

Opción	Propósito
`--cap-drop ALL`	Elimina capacidades de Linux como `NET_ADMIN` y `SYS_ADMIN` que podrían permitir escalada de privilegios
`--security-opt no-new-privileges`	Previene que los procesos ganen privilegios a través de binarios setuid
`--security-opt seccomp=...`	Restringe las llamadas del sistema disponibles; el valor predeterminado de Docker bloquea ~44, los perfiles personalizados pueden bloquear más
`--read-only`	Hace el sistema de archivos raíz del contenedor inmutable, previniendo que el agente persista cambios
`--tmpfs /tmp:...`	Proporciona un directorio temporal escribible que se borra cuando el contenedor se detiene
`--network none`	Elimina todas las interfaces de red; el agente se comunica a través del socket Unix montado a continuación
`--memory 2g`	Limita el uso de memoria para prevenir agotamiento de recursos
`--pids-limit 100`	Limita el recuento de procesos para prevenir fork bombs
`--user 1000:1000`	Se ejecuta como un usuario no root
`-v ...:/workspace:ro`	Monta código solo lectura para que el agente pueda analizarlo pero no modificarlo. Evite montar directorios de host sensibles como `~/.ssh`, `~/.aws`, o `~/.config`
`-v .../proxy.sock:...`	Monta un socket Unix conectado a un proxy ejecutándose fuera del contenedor (ver a continuación)

Arquitectura de socket Unix: Con --network none, el contenedor no tiene interfaces de red en absoluto. La única forma para que el agente alcance el mundo exterior es a través del socket Unix montado, que se conecta a un proxy ejecutándose en el host. Este proxy puede aplicar listas de permitidos de dominios, inyectar credenciales y registrar todo el tráfico. Esta es la misma arquitectura utilizada por sandbox-runtime. Incluso si el agente se ve comprometido a través de inyección de indicaciones, no puede exfiltrar datos a servidores arbitrarios. Solo puede comunicarse a través del proxy, que controla qué dominios son alcanzables. Para más detalles, consulte la publicación del blog de sandboxing de Claude Code. Opciones de endurecimiento adicionales:

Opción	Propósito
`--userns-remap`	Asigna root del contenedor a usuario host sin privilegios; requiere configuración del daemon pero limita el daño del escape del contenedor
`--ipc private`	Aísla la comunicación entre procesos para prevenir ataques entre contenedores

gVisor

Los contenedores estándar comparten el kernel del host: cuando el código dentro de un contenedor hace una llamada del sistema, va directamente al mismo kernel que ejecuta el host. Esto significa que una vulnerabilidad del kernel podría permitir escape del contenedor. gVisor aborda esto interceptando llamadas del sistema en el espacio de usuario antes de que lleguen al kernel del host, implementando su propia capa de compatibilidad que maneja la mayoría de syscalls sin involucrar el kernel real. Si un agente ejecuta código malicioso (quizás debido a inyección de indicaciones), ese código se ejecuta en el contenedor y podría intentar exploits del kernel. Con gVisor, la superficie de ataque es mucho más pequeña: el código malicioso necesitaría explotar primero la implementación del espacio de usuario de gVisor y tendría acceso limitado al kernel real. Para usar gVisor con Docker, instale el runtime runsc y configure el daemon:

// /etc/docker/daemon.json
{
  "runtimes": {
    "runsc": {
      "path": "/usr/local/bin/runsc"
    }
  }
}

Luego ejecute contenedores con:

docker run --runtime=runsc agent-image

Consideraciones de rendimiento:

Carga de trabajo	Sobrecarga
Computación vinculada a CPU	~0% (sin intercepción de syscall)
Syscalls simples	~2× más lento
Intensivo en E/S de archivos	Hasta 10-200× más lento para patrones pesados de apertura/cierre

Para entornos multiinquilino o cuando se procesa contenido no confiable, el aislamiento adicional a menudo vale la sobrecarga.

Máquinas virtuales

Las VMs proporcionan aislamiento a nivel de hardware a través de extensiones de virtualización de CPU. Cada VM ejecuta su propio kernel, creando un límite fuerte. Una vulnerabilidad en el kernel invitado no compromete directamente el host. Sin embargo, las VMs no son automáticamente “más seguras” que alternativas como gVisor. La seguridad de las VMs depende en gran medida del hipervisor y del código de emulación de dispositivos. Firecracker está diseñado para aislamiento ligero de microVM. Puede arrancar VMs en menos de 125ms con menos de 5 MiB de sobrecarga de memoria, eliminando emulación de dispositivos innecesaria para reducir la superficie de ataque. Con este enfoque, la VM del agente no tiene interfaz de red externa. En su lugar, se comunica a través de vsock (sockets virtuales). Todo el tráfico se enruta a través de vsock a un proxy en el host, que aplica listas de permitidos e inyecta credenciales antes de reenviar solicitudes.

Despliegues en la nube

Para despliegues en la nube, puede combinar cualquiera de las tecnologías de aislamiento anteriores con controles de red nativos de la nube:

Ejecute contenedores de agentes en una subred privada sin puerta de enlace de internet
Configure reglas de firewall en la nube (AWS Security Groups, firewall de VPC de GCP) para bloquear todo el tráfico de salida excepto a su proxy
Ejecute un proxy (como Envoy con su filtro credential_injector) que valide solicitudes, aplique listas de permitidos de dominios, inyecte credenciales y reenvíe a APIs externas
Asigne permisos IAM mínimos a la cuenta de servicio del agente, enrutando acceso sensible a través del proxy cuando sea posible
Registre todo el tráfico en el proxy para propósitos de auditoría

Gestión de credenciales

Los agentes a menudo necesitan credenciales para llamar a APIs, acceder a repositorios o interactuar con servicios en la nube. El desafío es proporcionar este acceso sin exponer las credenciales en sí.

El patrón de proxy

El enfoque recomendado es ejecutar un proxy fuera del límite de seguridad del agente que inyecte credenciales en solicitudes salientes. El agente envía solicitudes sin credenciales, el proxy las agrega y reenvía la solicitud a su destino. Este patrón tiene varios beneficios:

El agente nunca ve las credenciales reales
El proxy puede aplicar una lista de permitidos de puntos finales permitidos
El proxy puede registrar todas las solicitudes para auditoría
Las credenciales se almacenan en una ubicación segura en lugar de distribuirse a cada agente

Configurar Claude Code para usar un proxy

Claude Code admite dos métodos para enrutar solicitudes de muestreo a través de un proxy: Opción 1: ANTHROPIC_BASE_URL (simple pero solo para solicitudes de API de muestreo)

export ANTHROPIC_BASE_URL="http://localhost:8080"

Esto le dice a Claude Code y al Agent SDK que envíen solicitudes de muestreo a su proxy en lugar de directamente a la API de Claude. Su proxy recibe solicitudes HTTP en texto plano, puede inspeccionarlas y modificarlas (incluyendo inyectar credenciales), luego reenvía a la API real. Opción 2: HTTP_PROXY / HTTPS_PROXY (en todo el sistema)

export HTTP_PROXY="http://localhost:8080"
export HTTPS_PROXY="http://localhost:8080"

Claude Code y el Agent SDK respetan estas variables de entorno estándar, enrutando todo el tráfico HTTP a través del proxy. Para HTTPS, el proxy crea un túnel CONNECT encriptado: no puede ver o modificar contenidos de solicitudes sin intercepción TLS.

Implementar un proxy

Puede construir su propio proxy o usar uno existente:

Envoy Proxy: proxy de grado de producción con filtro credential_injector para agregar encabezados de autenticación
mitmproxy: proxy que termina TLS para inspeccionar y modificar tráfico HTTPS
Squid: proxy de caché con listas de control de acceso
LiteLLM: puerta de enlace LLM con inyección de credenciales y limitación de velocidad

Credenciales para otros servicios

Más allá del muestreo de la API de Claude, los agentes a menudo necesitan acceso autenticado a otros servicios, como repositorios git, bases de datos y APIs internas. Hay dos enfoques principales:

Herramientas personalizadas

Proporcione acceso a través de un servidor MCP o herramienta personalizada que enrute solicitudes a un servicio ejecutándose fuera del límite de seguridad del agente. El agente llama a la herramienta, pero la solicitud autenticada real ocurre fuera. Las llamadas de herramienta van a un proxy que inyecta las credenciales. Por ejemplo, un servidor MCP de git podría aceptar comandos del agente pero reenviarlos a un proxy de git ejecutándose en el host, que agrega autenticación antes de contactar al repositorio remoto. El agente nunca ve las credenciales. Ventajas:

Sin intercepción TLS: El servicio externo hace solicitudes autenticadas directamente
Las credenciales permanecen fuera: El agente solo ve la interfaz de herramienta, no las credenciales subyacentes

Reenvío de tráfico

Para llamadas de API de Claude, ANTHROPIC_BASE_URL le permite enrutar solicitudes a un proxy que puede inspeccionarlas y modificarlas en texto plano. Pero para otros servicios HTTPS (GitHub, registros npm, APIs internas), el tráfico a menudo está encriptado de extremo a extremo. Incluso si lo enruta a través de un proxy a través de HTTP_PROXY, el proxy solo ve un túnel TLS opaco y no puede inyectar credenciales. Para modificar tráfico HTTPS a servicios arbitrarios, sin usar una herramienta personalizada, necesita un proxy que termina TLS que desencripte tráfico, lo inspeccione o modifique, luego lo reencripte antes de reenviarlo. Esto requiere:

Ejecutar el proxy fuera del contenedor del agente
Instalar el certificado CA del proxy en el almacén de confianza del agente (para que el agente confíe en los certificados del proxy)
Configurar HTTP_PROXY/HTTPS_PROXY para enrutar tráfico a través del proxy

Este enfoque maneja cualquier servicio basado en HTTP sin escribir herramientas personalizadas, pero agrega complejidad alrededor de la gestión de certificados. Tenga en cuenta que no todos los programas respetan HTTP_PROXY/HTTPS_PROXY. La mayoría de herramientas (curl, pip, npm, git) lo hacen, pero algunas pueden omitir estas variables y conectarse directamente. Por ejemplo, fetch() de Node.js ignora estas variables por defecto; en Node 24+ puede establecer NODE_USE_ENV_PROXY=1 para habilitar soporte. Para cobertura completa, puede usar proxychains para interceptar llamadas de red, o configurar iptables para redirigir tráfico saliente a un proxy transparente.

Un proxy transparente intercepta tráfico a nivel de red, por lo que el cliente no necesita ser configurado para usarlo. Los proxies regulares requieren que los clientes se conecten explícitamente y hablen HTTP CONNECT o SOCKS. Los proxies transparentes (como Squid o mitmproxy en modo transparente) pueden manejar conexiones TCP sin procesar redirigidas.

Ambos enfoques aún requieren el proxy que termina TLS y certificado CA confiable. Solo aseguran que el tráfico realmente alcance el proxy.

Configuración del sistema de archivos

Los controles del sistema de archivos determinan qué archivos el agente puede leer y escribir.

Montaje de código solo lectura

Cuando el agente necesita analizar código pero no modificarlo, monte el directorio solo lectura:

docker run -v /path/to/code:/workspace:ro agent-image

Incluso el acceso solo lectura a un directorio de código puede exponer credenciales. Archivos comunes a excluir o sanitizar antes de montar:

Archivo	Riesgo
`.env`, `.env.local`	Claves API, contraseñas de base de datos, secretos
`~/.git-credentials`	Contraseñas/tokens de Git en texto plano
`~/.aws/credentials`	Claves de acceso de AWS
`~/.config/gcloud/application_default_credentials.json`	Tokens ADC de Google Cloud
`~/.azure/`	Credenciales de CLI de Azure
`~/.docker/config.json`	Tokens de autenticación de registro de Docker
`~/.kube/config`	Credenciales de clúster de Kubernetes
`.npmrc`, `.pypirc`	Tokens de registro de paquetes
`*-service-account.json`	Claves de cuenta de servicio de GCP
`.pem`, `.key`	Claves privadas

Considere copiar solo los archivos de origen necesarios, o usar filtrado de estilo .dockerignore.

Ubicaciones escribibles

Si el agente necesita escribir archivos, tiene algunas opciones dependiendo de si desea que los cambios persistan: Para espacios de trabajo efímeros en contenedores, use montajes tmpfs que existen solo en memoria y se borran cuando el contenedor se detiene:

docker run \
  --read-only \
  --tmpfs /tmp:rw,noexec,nosuid,size=100m \
  --tmpfs /workspace:rw,noexec,size=500m \
  agent-image

Si desea revisar cambios antes de persistirlos, un sistema de archivos de superposición permite que el agente escriba sin modificar archivos subyacentes. Los cambios se almacenan en una capa separada que puede inspeccionar, aplicar o descartar. Para salida completamente persistente, monte un volumen dedicado pero manténgalo separado de directorios sensibles.

SDK de Agent

Conceptos fundamentales

Entrada y salida

Extender con herramientas

Personalizar comportamiento

Control y observabilidad

Implementación

Referencias de SDK

Despliegue seguro de agentes de IA

Modelo de amenaza

Características de seguridad integradas

Principios de seguridad

Límites de seguridad

Privilegio mínimo

Defensa en profundidad

Tecnologías de aislamiento

Sandbox runtime

Contenedores

gVisor

Máquinas virtuales

Despliegues en la nube

Gestión de credenciales

El patrón de proxy

Configurar Claude Code para usar un proxy

Implementar un proxy

Credenciales para otros servicios

Herramientas personalizadas

Reenvío de tráfico

Configuración del sistema de archivos

Montaje de código solo lectura

Ubicaciones escribibles

Lectura adicional

​Modelo de amenaza

​Características de seguridad integradas

​Principios de seguridad

​Límites de seguridad

​Privilegio mínimo

​Defensa en profundidad

​Tecnologías de aislamiento

​Sandbox runtime

​Contenedores

​gVisor

​Máquinas virtuales

​Despliegues en la nube

​Gestión de credenciales

​El patrón de proxy

​Configurar Claude Code para usar un proxy

​Implementar un proxy

​Credenciales para otros servicios

​Herramientas personalizadas

​Reenvío de tráfico

​Configuración del sistema de archivos

​Montaje de código solo lectura

​Ubicaciones escribibles

​Lectura adicional

Modelo de amenaza

Características de seguridad integradas

Principios de seguridad

Límites de seguridad

Privilegio mínimo

Defensa en profundidad

Tecnologías de aislamiento

Sandbox runtime

Contenedores

gVisor

Máquinas virtuales

Despliegues en la nube

Gestión de credenciales

El patrón de proxy

Configurar Claude Code para usar un proxy

Implementar un proxy

Credenciales para otros servicios

Herramientas personalizadas

Reenvío de tráfico

Configuración del sistema de archivos

Montaje de código solo lectura

Ubicaciones escribibles

Lectura adicional