Comenzar con Claude Managed Agents autoalojado

En esta guía de inicio rápido, inicias Claude Managed Agents autoalojado en una sola máquina con Docker Compose. El stack de Compose consta del servidor, su base de datos PostgreSQL y un conjunto de workers que ejecutan cada sesión en su propio contenedor de sandbox. Después, chateas con un agente desde tu terminal y confirmas que sus llamadas a herramientas se ejecutaron en un contenedor de sandbox. Luego puedes abrir la sesión en la consola de tu servidor.

Para producción, Anthropic recomienda los dos charts de Helm de la versión. Consulta Implementar en Kubernetes.

Requisitos previos

• El archivo de la versión: Para solicitar acceso a la descarga, contacta al equipo de tu cuenta de Anthropic.
• Una clave de API de Claude: El servidor la usa para las llamadas al modelo. Crea una en la Claude Console.
• Docker: La versión más reciente de Docker Engine con el plugin de Compose (docker compose, no el antiguo docker-compose).
• Un host con al menos dos CPU: x86-64 o Arm. En un host más pequeño, establece CMA_SANDBOX_CPUS en su número de CPU cuando crees .env.
• Acceso a la red en el primer inicio: La primera compilación descarga contenido de Docker Hub, los repositorios de paquetes de Alpine y las versiones de GitHub.
• Herramientas: En la máquina donde ejecutas Docker, necesitas openssl y la CLI ant.

Iniciar el stack

1. 1

   Extraer el archivo

   Extrae el archivo y trabaja desde su directorio compose. En el comando, reemplaza <archive> con el nombre de tu archivo, sin .tar.gz.

   tar -xzf <archive>.tar.gz && cd <archive>/compose

   

   Si tu umask es más estricto que 022, los binarios pierden su permiso de ejecución para otros usuarios y el contenedor del servidor no puede iniciarlos. En ese caso, establécelo en 022 y vuelve a extraer el archivo.

2. 2

   Crear el archivo .env

   Compose lee los secretos del stack desde un archivo .env junto a docker-compose.yml. Crea el archivo:

   cat > .env <<EOF
   CMA_PG_PASSWORD=$(openssl rand -hex 32)
   ANTHROPIC_API_KEY=sk-ant-...
   CMA_SERVER__API_KEY=$(openssl rand -hex 32)
   CMA_STORE__CREDENTIALS_ENCRYPTION_KEY=$(openssl rand -base64 32)
   EOF
   chmod 600 .env

   

   Abre .env en un editor y reemplaza sk-ant-... con tu clave de API de Claude. El bloque genera el resto: la contraseña de la base de datos, la clave de API del servidor que envían tus aplicaciones y la clave que cifra los secretos almacenados del servidor.

3. 3

   Iniciar los contenedores

   Compila e inicia el stack y luego sigue el registro del servidor:

   docker compose up --build -d
   docker compose logs -f cma-server

   

   Cuando el registro muestre una línea con msg="cma-server listening", presiona Ctrl+C para dejar de seguirlo.

4. 4

   Comprobar que el servidor está listo

   curl -s http://127.0.0.1:8400/cma-server/readyz

   

   Un servidor listo responde con "status":"ready". Justo después del inicio, puede responder "status":"degraded" durante unos segundos mientras se ejecutan sus primeras comprobaciones. Si permanece en degraded o responde "status":"not_ready", consulta Solución de problemas.

Ejecutar tu primera sesión

Crea un agente y chatea con él desde tu terminal con la CLI ant.

1. 1

   Apuntar la CLI a tu servidor

   Abre una segunda terminal en el mismo directorio y resérvala para ant. Los siguientes comandos establecen ANTHROPIC_API_KEY en la clave de API de tu servidor, no en tu clave de API de Claude, como explica Llamar a la API en un servidor autoalojado:

   export ANTHROPIC_BASE_URL=http://127.0.0.1:8400
   export ANTHROPIC_API_KEY=$(grep '^CMA_SERVER__API_KEY=' .env | cut -d= -f2)

   

   Mantén los comandos docker compose en la primera terminal. 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.

2. 2

   Crear un agente

   Guarda el archivo que sigue al comando como quickstart-agent.md y luego ejecuta el comando. El archivo le da al agente las herramientas integradas y le permite ejecutarlas sin preguntarte primero.

   CLI

   

   ant apply --yes quickstart-agent.md

   quickstart-agent.md

   

   ---
   name: Quickstart agent
   model: claude-opus-5-5
   tools:
     - type: agent_toolset_20260401
   ---
   
   You are a helpful assistant.

   El comando primero imprime una advertencia de que could not determine the organization and workspace, con un error 404, y luego crea el agente. Eso es lo esperado en tu propio servidor.

3. 3

   Iniciar una sesión

   Estos comandos encuentran el agente y el entorno del stack, inician una sesión y guardan el ID de la sesión en SESSION_ID. El stack 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)

   
4. 4

   Pedirle al agente que ejecute un comando

   Conecta tu terminal a la sesión:

   ant beta:sessions connect "$SESSION_ID"

   

   El comando abre una vista de chat de la sesión. Envía este mensaje:

   Run `hostname` with the bash tool and tell me the output.

   

   El agente responde con un nombre de host que comienza con cma-sandbox-. Ese es el nombre del contenedor de sandbox que ejecutó el comando, lo que confirma que la herramienta se ejecutó en un sandbox y no en tu máquina.

5. 5

   Encontrar el contenedor de sandbox

   Deja el chat abierto. En la primera terminal, enumera los contenedores de sandbox:

   docker ps --filter label=cma-server.sandbox

   

   La lista muestra el contenedor que informó el agente. El contenedor termina aproximadamente un minuto después de que termine un turno, y el siguiente mensaje de la sesión inicia un contenedor nuevo. Si la lista está vacía, pídele al agente que ejecute hostname de nuevo y vuelve a enumerar los contenedores mientras responde.

   Para salir del chat, presiona Ctrl+C en su terminal. La sesión sigue ejecutándose.

Probar la consola en tu servidor

Esta sección es opcional. La consola requiere inicio de sesión único. Para probarla, reinicia el stack con el proveedor de inicio de sesión simulado de la versión. El puerto 8080 de tu máquina debe estar libre.

1. 1

   Reiniciar el stack con el proveedor de inicio de sesión simulado

   Ejecuta estos comandos en la primera terminal:

   export COMPOSE_FILE=docker-compose.yml:docker-compose.oidc.yml
   docker compose up --build -d

   

   La línea export se aplica solo a la primera terminal, así que vuelve a ejecutarla en cualquier terminal nueva que abras para docker compose. Para cambiar los ajustes del servidor en este stack, edita compose.config.oidc.yaml, no compose.config.yaml, y luego ejecuta docker compose restart cma-server.

2. 2

   Abrir la sesión

   En un navegador en la misma máquina, abre http://127.0.0.1:8400/, haz clic en Continue with SSO y selecciona alice, el administrador de demostración. En la barra lateral, selecciona Sessions y luego selecciona la sesión.

   La página se actualiza a medida que el agente trabaja, y puedes enviarle un mensaje al agente desde ella.

Para crear agentes e iniciar sesiones también en la consola, consulta Ejecutar un agente desde la consola.

Detener el stack

En la primera terminal, ejecuta este comando:

docker compose down --remove-orphans

El comando elimina los contenedores y conserva la base de datos. Para eliminar también la base de datos, con todos los agentes, sesiones e historial de las sesiones que contiene, ejecuta docker compose down --remove-orphans -v.

Solución de problemas

• Tu archivo no tiene un directorio compose: El archivo contiene una versión anterior, y los comandos de esta página no coinciden con ella. Pide la versión actual al equipo de tu cuenta de Anthropic. Para mover una implementación en ejecución a la versión actual, consulta Actualizar Claude Managed Agents autoalojado.
• El servidor nunca se inicia: Ejecuta docker compose logs migrate. El contenedor migrate de un solo uso crea las tablas de la base de datos. Debe terminar con el estado 0 antes de que se inicie el servidor.
• La comprobación de disponibilidad permanece en degraded, o todos los turnos fallan: Si ejecutaste docker compose up en una terminal donde ANTHROPIC_BASE_URL es http://127.0.0.1:8400, el servidor se llama a sí mismo en lugar de a la API de Claude. Ejecuta docker compose up -d de nuevo en la primera terminal, donde la variable no está establecida. De lo contrario, el registro del servidor muestra qué falló. Para leerlo, vuelve a ejecutar docker compose logs -f cma-server.
• La comprobación de disponibilidad responde not_ready: En la respuesta, busca la comprobación con el estado failed:
  • upstream: La API de Claude rechazó tu clave de API de Claude. Corrige ANTHROPIC_API_KEY en .env y luego ejecuta docker compose up -d de nuevo en la primera terminal. Si tu shell también establece ANTHROPIC_API_KEY, Compose usa el valor del shell, así que ejecuta primero unset ANTHROPIC_API_KEY.
  • database: O bien la base de datos rechazó el inicio de sesión del servidor, por ejemplo debido a una contraseña incorrecta, o bien se interrumpió una conexión abierta con la base de datos. Para ver cuál de los dos, vuelve a ejecutar docker compose logs -f cma-server.
• El agente responde, pero su llamada a herramienta nunca termina: Ningún worker está sondeando el entorno. Revisa el registro de los workers con docker compose logs sandbox. Un worker que no puede acceder al socket del daemon de Docker termina con un mensaje que menciona CMA_DOCKER_SOCKET. Establece esa variable en .env con la ruta del socket de tu daemon y luego ejecuta docker compose up -d de nuevo en la primera terminal.
• Los workers se están ejecutando, pero una llamada a herramienta sigue sin terminar nunca: El stack inicia 10 workers, y cada uno ejecuta el contenedor de una sola sesión a la vez. Una sesión ocupa un worker libre cuando la creas, y una sesión que nunca recibe un mensaje conserva su worker durante hasta una hora. Con los 10 ocupados, las llamadas a herramientas de cualquier otra sesión esperan a un worker. Si el comando docker ps del paso “Encontrar el contenedor de sandbox” enumera 10 contenedores, archiva las sesiones que no uses:
  1. En la primera terminal, ejecuta docker ps --filter label=cma-server.sandbox --format '{{.Label "cma-server.session"}}'. Imprime el ID de la sesión detrás de cada contenedor. La sesión que espera aún no tiene contenedor, así que no está en la lista.
  2. En la segunda terminal, presiona Ctrl+C para salir del chat y ejecuta ant beta:sessions archive --session-id <session-id> para cada sesión enumerada que no uses.
  3. Ejecuta ant beta:sessions connect "$SESSION_ID" de nuevo. La llamada a herramienta termina cuando un worker toma su sesión.

Próximos pasos