El plano de control era el factor decisivo. Muchas empresas querían agentes Claude trabajando en código interno durante horas seguidas, y otras tantas se negaban a dejar que un proveedor guardara el registro de sesión, las credenciales y el ciclo del agente mientras ese trabajo se ejecutaba. Claude Managed Agents autohospedado, abierto en beta privada el 12 de noviembre, es la respuesta de Anthropic a esa negativa. Tú ejecutas el servicio. Claude mismo aún se ejecuta en un proveedor que tú eliges.
Esa división da forma a cada paso abajo. Nuestro reporte de noticias sobre el lanzamiento cubrió lo que se movió a casa y lo que no. Este tutorial hace la instalación en el orden que la documentación de Anthropic establece, y señala los límites antes de que gastes una tarde en una configuración que tu carga de trabajo no puede usar.
Lo que vas a construir o aprender
Terminarás con una pila de desarrollo ejecutándose en una computadora y una sesión de agente que ejecutó un comando de shell dentro de su propio contenedor sandbox. La pila tiene tres partes que tú operas. El servidor, llamado cma-server, sirve la API de Managed Agents, ejecuta el ciclo del agente y guarda agentes, sesiones e historial de sesiones. Los trabajadores toman trabajo del servidor y ejecutan herramientas de shell y archivos dentro de tus sandboxes. El servidor mismo nunca ejecuta esas herramientas.
También aprenderás dónde está realmente el límite. Para cada llamada al modelo, el servidor envía la conversación hasta ahora, entradas de herramientas y resultados de herramientas incluidos, a tu proveedor de inferencia. Anthropic dice que no tiene acceso remoto a tu servidor ni a sus registros. El registro y las llaves se quedan en casa. Las instrucciones aún viajan, y el Paso 9 es donde decides a dónde viajan.
Antes de empezar
Lee primero las brechas, porque son del tipo que termina proyectos amablemente en la segunda semana. Nada se copia desde el servicio alojado, historial de sesiones incluido. Recreás agentes, habilidades, credenciales de bóveda y almacenes de memoria en tu propio servidor. Solo existen entornos self_hosted, y una solicitud de un entorno en la nube devuelve un error 400. El servidor no sirve la API Messages ni la API Models, y las llamadas a /v1/messages y /v1/models devuelven 404.
La lista de faltantes es más larga. Los recursos de sesión de archivos y la Files API no existen, aunque los recursos memory_store funcionan. El servidor rechaza credenciales de bóveda mcp_oauth, porque no tiene flujo OAuth para refrescar un token, así que guardas tokens como credenciales static_bearer y los rotas tú mismo. Rechaza agentes que declaran las habilidades precompiladas docx, pdf, pptx y xlsx, así que subes esas habilidades como habilidades personalizadas en cambio. Los despliegues programados, los sueños y los webhooks no tienen rutas en absoluto. La búsqueda web y la obtención web empiezan desactivadas, y lo que puedes activar depende del proveedor que elijas en el Paso 9.
Una nota de alcance sobre honestidad. El acceso a esta beta está controlado, así que este tutorial se verificó línea por línea contra la documentación de Anthropic y no se ejecutó en una computadora de prueba. Cada comando abajo viene de la guía rápida, la página de proveedor de inferencia o la página de diferencias, todas nombradas en Fuentes. Donde la documentación muestra un valor secreto, este tutorial muestra un marcador.
Tres credenciales ejecutan toda la configuración, y confundirlas causa la mayor parte de la confusión temprana:
| Credencial | Quién la tiene | Lo que hace |
|---|---|---|
| Clave de API del servidor | Tus aplicaciones, la CLI ant y la CLI de administración | Autentica solicitudes a tu servidor. La configuración la genera. Juega el rol que una clave de API de Claude juega con el servicio alojado |
| Credencial de inferencia | Solo el servidor | Autentica las llamadas al modelo del servidor a tu proveedor, como una clave de API de Claude o una credencial en la nube |
| Clave de entorno | Tus trabajadores | Permite a un trabajador consultar una cola de trabajo de entorno y llegar a las sesiones de ese entorno |
Paso 1: Obtén el archivo y desempácalo
Acción: contacta a tu equipo de cuenta de Anthropic y solicita acceso a Claude Managed Agents autohospedado. No hay descarga pública ni registro de autoservicio en la documentación. Cuando el equipo envíe el archivo de lanzamiento, desempácalo y trabaja desde su directorio compose. Reemplaza <archive> con el nombre del archivo, sin .tar.gz.
tar -xzf <archive>.tar.gz && cd <archive>/compose
Resultado esperado: estás dentro del directorio compose, junto a docker-compose.yml. Si tu umask es más estricto que 022, los binarios pierden permiso de ejecución para otros usuarios y el contenedor del servidor no puede iniciarlos. En ese caso, define el umask en 022 y desempaca el archivo de nuevo. Cada archivo de lanzamiento también incluye un archivo operator-guide.md. La documentación sugiere que Claude lea ese archivo, para que Claude pueda ayudarte a configurar el servidor para ese lanzamiento exacto.
Paso 2: Crea el archivo .env
Acción: crea el archivo .env junto a docker-compose.yml, con el bloque de la guía rápida. Compose lee los secretos de la pila desde este archivo. El bloque define cuatro valores. Dos son contraseñas y claves generadas para la propia pila, uno es la clave que cifra los secretos guardados del servidor, y uno es tu clave de API de Claude, que agregas a mano.
CMA_PG_PASSWORD=<generated value from the quickstart block>
ANTHROPIC_API_KEY=sk-ant-...
CMA_SERVER__API_KEY=<generated value from the quickstart block>
CMA_STORE__CREDENTIALS_ENCRYPTION_KEY=$(openssl rand -base64 32)
chmod 600 .env
Resultado esperado: el archivo existe con permisos ajustados, el marcador sk-ant-... ahora contiene tu clave real de API de Claude, y los otros tres valores contienen los valores generados del bloque de la guía rápida. Abre el archivo en un editor para hacer ese único reemplazo, y no imprimas el archivo en un registro de terminal compartido después.
Paso 3: Inicia la pila
Acción: compila e inicia la pila, y luego sigue el registro del servidor. Quédate en esta terminal para cada comando docker compose en todo el tutorial. La razón de esa disciplina llega en el Paso 5.
docker compose up --build -d
docker compose logs -f cma-server
Resultado esperado: el registro muestra una línea con msg="cma-server listening". Presiona Ctrl+C para dejar de seguir el registro. La pila ahora ejecuta el servidor, su base de datos PostgreSQL y un conjunto de trabajadores, con un contenedor sandbox por sesión una vez que las sesiones empiecen.
Paso 4: Revisa que el servidor está listo
Acción: pídele al servidor su estado de preparación.
curl -s http://127.0.0.1:8400/cma-server/readyz
Resultado esperado: un servidor listo responde con "status":"ready". Justo después de un inicio, puede responder "status":"degraded" durante unos segundos mientras se ejecutan sus primeras revisiones. Si se queda degradado, o responde "status":"not_ready", ve a Solución de problemas antes de crear nada.
Paso 5: Apunta la CLI a tu servidor
Acción: abre una segunda terminal en el mismo directorio y consérvala para trabajo con ant. Define la URL base en tu servidor, y define la clave de API en tu clave de API del servidor del archivo .env. Ese valor no es tu clave de API de Claude, y la documentación dedica una página entera a esa distinción.
export ANTHROPIC_BASE_URL=http://127.0.0.1:8400
export ANTHROPIC_API_KEY=<your server API key from .env>
Resultado esperado: los comandos ant en esta terminal ahora hablan con tu servidor en lugar del servicio alojado. Mantenlos aquí. Si ejecutas docker compose up en esta terminal, Compose pasa estas variables al servidor, y el servidor se llama a sí mismo en lugar de a la API de Claude. Esa única confusión explica una gran parte de las primeras ejecuciones fallidas.
Paso 6: Crea un agente
Acción: guarda un archivo llamado quickstart-agent.md con el contenido abajo, y luego aplícalo. El archivo le da al agente el conjunto de herramientas integrado y le permite ejecutar esas herramientas sin preguntarte primero. El nombre del modelo es un ID de API de Claude, y se mantiene válido incluso si cambias de proveedores en el Paso 9, porque el servidor traduce el ID para el proveedor que sirve ese modelo.
---
name: Quickstart agent
model: claude-opus-5-5
tools:
- type: agent_toolset_20260401
---
You are a helpful assistant.
ant apply --yes quickstart-agent.md
Resultado esperado: el comando primero imprime una advertencia de que could not determine the organization and workspace, con un error 404, y luego crea el agente. La documentación dice que esa advertencia es esperada en tu propio servidor. No la persigas.
Paso 7: Inicia una sesión
Acción: encuentra el agente y el entorno de la pila, y luego inicia una sesión y conserva su ID. La pila Compose nombra su entorno compose-sandbox.
AGENT_ID=$(ant beta:agents list --format raw --transform 'data.#(name=="Quickstart agent").id' --raw-output)
ENVIRONMENT_ID=$(ant beta:environments list --format raw --transform 'data.#(name=="compose-sandbox").id' --raw-output)
SESSION_ID=$(ant beta:sessions create --agent "$AGENT_ID" --environment-id "$ENVIRONMENT_ID" --transform id --raw-output)
Resultado esperado: SESSION_ID contiene un valor, y la sesión existe en tu servidor, en tu base de datos, sin copia en el servicio alojado. Una sesión toma un trabajador libre cuando la creas, y la pila inicia diez trabajadores. Una sesión que nunca recibe un mensaje puede conservar su trabajador hasta por una hora, un dato que importa en Solución de problemas.
Paso 8: Pídele al agente que ejecute un comando
Acción: conecta tu terminal a la sesión, y luego envía el mensaje exacto abajo.
ant beta:sessions connect "$SESSION_ID"
Run `hostname` with the bash tool and tell me the output.
Resultado esperado: el agente responde con un nombre de host que empieza con cma-sandbox-. Ese nombre es el contenedor sandbox que ejecutó el comando, lo que confirma que la herramienta se ejecutó dentro de un sandbox y no en tu computadora. Deja el chat abierto, vuelve a la terminal uno y enumera los contenedores sandbox para ver el mismo nombre en la salida de Docker.
docker ps --filter label=cma-server.sandbox
El contenedor sale cerca de un minuto después de que termina un turno, y el mensaje siguiente inicia uno nuevo. Si la lista está vacía, pídele al agente que ejecute hostname de nuevo y enumera los contenedores mientras responde. Para salir del chat, presiona Ctrl+C en su terminal. La sesión sigue ejecutándose sin ti.
Una cámara por sesión, una torre sobre todas. El servidor dirige el trabajo, y los trabajadores ejecutan las herramientas. Ilustración: Dirty Static
Paso 9: Elige a dónde van las llamadas al modelo
Acción: decide el proveedor de inferencia ahora, mientras la configuración aún es pequeña. El ajuste inference.provider en el archivo de ajustes del servidor toma cinco valores. anthropic es el predeterminado y envía llamadas a la API de Claude. bedrock las envía a Amazon Bedrock. vertex las envía a Claude Models en Google Cloud. foundry las envía a Microsoft Foundry. gateway las envía a una puerta de modelo que tú mismo ejecutas. Bajo cada valor excepto anthropic, el servidor no necesita clave de API de Claude.
Esta muestra enruta llamadas a Bedrock. Ponla en el archivo de ajustes del servidor, dale al servidor la credencial del proveedor como describe la página de proveedor de inferencia para tu instalación, y reinicia el servidor. En Compose, si cambiaste .env o docker-compose.yml para pasar esa credencial, ejecuta docker compose up -d en cambio, porque un reinicio simple no vuelve a leer esos archivos.
inference:
provider: bedrock
region: us-east-1
#model_id_prefix: global.anthropic.
#model_id_overrides:
# claude-opus-5-5: us.anthropic.claude-opus-5-5
Resultado esperado: el servidor firma sus llamadas con lo que la cadena de credenciales predeterminada del SDK de AWS encuentre en el host, y antepone a cada ID de modelo us.anthropic. por defecto, que nombra un perfil de inferencia entre regiones. La identidad de AWS con la que firma el servidor necesita bedrock:InvokeModel y bedrock:InvokeModelWithResponseStream en los modelos y perfiles que uses, más bedrock:ListFoundationModels y bedrock:ListInferenceProfiles en el recurso *. Inicia una sesión nueva después del reinicio y confirma que el agente aún responde. Nuestra revisión de investigación de la beta sopesa esta elección de proveedor en su totalidad, porque es la decisión que decide lo que la palabra privado significa en tu despliegue.
Verificación
Ejecuta estas comprobaciones antes de dar la configuración por terminada:
- La llamada de preparación en el Paso 4 responde
"status":"ready". - El agente en el Paso 8 informa un nombre de host que empieza con
cma-sandbox-, ydocker psen la terminal uno muestra ese contenedor mientras se ejecuta el turno. - La sesión y su historial viven en tu servidor. Detén la pila desde la terminal uno con el comando abajo, iníciala de nuevo y confirma que el registro de sesión sobrevivió, porque la base de datos lo guarda.
docker compose down --remove-orphans
docker compose up -d
Ese comando de detención elimina los contenedores y conserva la base de datos. Agrégale -v solo cuando quieras que la base de datos, con cada agente, sesión e historial de sesión en ella, también se elimine. Esa es una elección destructiva, así que trátala como tal.
- Si cambiaste el proveedor en el Paso 9, una sesión nueva responde después del reinicio, y tu consola de proveedor o registro de puerta muestra la llamada al modelo llegando en la ruta que elegiste.
Antes de llamarlo producción
La pila Compose demuestra la forma. No la endurece. Para producción, Anthropic recomienda los dos charts Helm en el archivo de lanzamiento, llamados cma-server y cma-sandboxes, en un clúster Kubernetes en versión 1.30 o posterior. Esa ruta necesita el controlador Agent Sandbox, nodos que ejecuten gVisor, un plugin de red que imponga NetworkPolicy, una base de datos PostgreSQL 16 o posterior fuera de ambos charts, un registro del que el clúster pueda descargar, y derechos de administrador del clúster para la instalación.
El servidor también habla HTTP simple en el puerto 8400 en esa ruta, así que TLS pertenece frente a él antes de que cualquier cliente fuera del clúster se conecte. La página de Kubernetes define los términos para esa puerta principal. Las rutas pasan sin cambios, los cuerpos de solicitud de hasta 32 MiB pasan, las respuestas pasan sin búfer, y el proxy nunca reenvía un POST ni almacena en caché una respuesta. Lee esa página en su totalidad antes de instalar nada, y trata un despliegue por nivel de confianza como la regla. La documentación es contundente en ese punto, porque la clave de API del servidor llega a cada entorno en un despliegue.
Solución de problemas
| Problema | Causa probable | Solución |
|---|---|---|
Tu archivo no tiene directorio compose | El archivo contiene un lanzamiento anterior, y los comandos de la guía rápida no coinciden con él | Pídele a tu equipo de cuenta de Anthropic el lanzamiento actual. Para un despliegue en ejecución, sigue la página de actualización en la documentación |
| El servidor nunca se levanta | El contenedor único migrate falló, así que las tablas de la base de datos nunca se crearon | Ejecuta docker compose logs migrate. Debe salir con estado 0 antes de que el servidor inicie |
La preparación se queda en degraded, o cada turno falla | Ejecutaste docker compose up en la terminal donde ANTHROPIC_BASE_URL apunta a tu propio servidor, así que el servidor se llama a sí mismo | Ejecuta docker compose up -d de nuevo en la terminal uno, donde esa variable no está definida. Luego lee el registro del servidor con docker compose logs -f cma-server |
La preparación responde not_ready y la revisión fallida es upstream | La API de Claude rechazó tu clave de API de Claude | Corrige ANTHROPIC_API_KEY en .env, ejecuta unset ANTHROPIC_API_KEY en la shell si define su propio valor, y luego ejecuta docker compose up -d de nuevo en la terminal uno |
La preparación responde not_ready y la revisión fallida es database | La base de datos rechazó el inicio de sesión del servidor, o una conexión a la base de datos se rompió | Lee el registro del servidor con docker compose logs -f cma-server para ver cuál de las dos fue, y luego corrige la contraseña o la conexión |
| El agente responde, pero su llamada a herramienta nunca termina | Ningún trabajador está consultando el entorno, o un trabajador no puede llegar al socket del daemon de Docker | Revisa los trabajadores con docker compose logs sandbox. Si el registro nombra CMA_DOCKER_SOCKET, define esa variable en .env en tu ruta de socket del daemon, y luego ejecuta docker compose up -d de nuevo en la terminal uno |
| Los trabajadores se ejecutan, pero una llamada a herramienta aún espera | Los diez trabajadores están ocupados por sesiones que nunca recibieron un mensaje, y cada una conserva su trabajador hasta por una hora | Enumera las sesiones detrás de los contenedores con docker ps --filter label=cma-server.sandbox --format '{{.Label "cma-server.session"}}', sal del chat con Ctrl+C y archiva cada sesión sin usar con ant beta:sessions archive --session-id <session-id> en la terminal dos. Luego conéctate a tu sesión de nuevo |
| Un agente que funcionaba en el servicio alojado falla aquí | Usa una función que el servidor autohospedado no tiene, como un entorno en la nube, un recurso de archivo o una habilidad de documento precompilada | Lee la página de diferencias en Fuentes y reconstruye esa parte a la manera autohospedada. Nada migra, así que espera trabajo de reconstrucción, no trabajo de importación |
Próximos pasos
Toma después la lectura de producción. Trabaja la página Deploy on Kubernetes en la documentación con tu equipo de plataforma, y calcula el costo real de propiedad mientras lees. Tú instalas cada lanzamiento, tú respaldas una base de datos que guarda cada conversación, y la licencia del servidor, en la cobertura de lanzamiento de su texto, te da ocho horas para revertir después de un aviso de seguridad y un día laborable para aplicar una actualización de seguridad. El control es el producto aquí, y las operaciones son su precio.
Luego ejecuta un trabajo real acotado antes de ampliar nada. Elige una tarea de backlog con un resultado que puedas revisar a mano, observa el registro de sesión que deja atrás y prueba los modos de falla a propósito. Reinicia el servidor y confirma que el historial sobrevivió. Revoca una credencial y confirma que el agente falla de forma segura. Apunta el agente a un host que nunca listaste y confirma que el sandbox no puede llegar a él. Un agente que has visto fallar bien es uno en el que puedes empezar a confiar para trabajo que importa.
Datos, comandos y ajustes verificados contra la documentación de Anthropic el 13 de noviembre de 2026. La disponibilidad es beta privada y puede cambiar. Este procedimiento se verificó contra esos documentos y no se presentó como una ejecución de prueba personal, porque el acceso al lanzamiento corre mediante un equipo de cuenta de Anthropic.
Fuentes
- Anthropic Docs, Self hosted Claude Managed Agents, overview, credentials and what runs where: https://platform.claude.com/docs/en/managed-agents/self-hosted
- Anthropic Docs, Get started with self hosted Claude Managed Agents, the Compose quickstart this tutorial follows: https://platform.claude.com/docs/en/managed-agents/self-hosted/quickstart
- Anthropic Docs, Differences from the hosted service: https://platform.claude.com/docs/en/managed-agents/self-hosted/differences
- Anthropic Docs, Inference provider: https://platform.claude.com/docs/en/managed-agents/self-hosted/inference-provider
- Anthropic Docs, Deploy on Kubernetes: https://platform.claude.com/docs/en/managed-agents/self-hosted/kubernetes
- Anthropic, Claude Platform release notes, November 12, 2026 launch entry: https://platform.claude.com/docs/en/release-notes/overview
- Anthropic, Operate Claude Managed Agents inside your security perimeter, November 12, 2026: https://claude.com/resources/articles/self-hosted-claude-managed-agents
- Diagrama: Anthropic, del anuncio y la documentación autohospedados
- Ilustraciones del héroe y la cámara sandbox: Dirty Static
FIN DE LA TRANSMISIÓN
Mantén la curiosidad. Cuestiónalo todo.
