---
title: Comenzar con Claude Managed Agents autoalojado
url: https://platform.claude.com/docs/es/managed-agents/self-hosted/quickstart
description: Inicia Claude Managed Agents autoalojado en una sola máquina con Docker Compose y ejecuta una primera sesión en un contenedor de sandbox.
---

<Note>
  Para solicitar acceso a Claude Managed Agents autoalojado, ponte en contacto con el equipo de tu cuenta de Anthropic.
</Note>

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](https://platform.claude.com/docs/es/managed-agents/self-hosted/console).

<Warning>
  El stack de Compose es para el desarrollo, no para producción. Sirve HTTP sin cifrar y, de forma predeterminada, publica el puerto 8400 solo en la dirección de loopback del host de Docker, `127.0.0.1`. Con algunas versiones de Docker Engine anteriores a la 28.3.3, las máquinas de la red local del host también pueden acceder a ese puerto. Las herramientas del agente se ejecutan en contenedores en ese host, así que usa una máquina que no contenga nada que necesites proteger.
</Warning>

Para producción, Anthropic recomienda los dos charts de Helm de la versión. Consulta [Implementar en Kubernetes](https://platform.claude.com/docs/es/managed-agents/self-hosted/kubernetes).

Deja que Claude Code ejecute esta guía de inicio rápido por ti

```text
Configura Claude Managed Agents autoalojado en esta máquina siguiendo https://platform.claude.com/docs/en/managed-agents/self-hosted/quickstart.md. Ya descargué el archivo de la versión.
```

Si eres un agente que ejecuta estos pasos para una persona:

* **Archivo de la versión:** Pregúntale a la persona dónde está el archivo. Solo ella puede descargarlo.
* **Clave de API de Claude:** Pide a la persona que edite `.env` por sí misma. No le pidas la clave y no imprimas `.env`.
* **Variables:** Si tu shell no conserva las variables entre comandos, vuelve a establecer `ANTHROPIC_BASE_URL` y `ANTHROPIC_API_KEY` en cada comando `ant`. Sin ellas, `ant` llama al servicio alojado.
* **Compose:** Pon `env -u ANTHROPIC_BASE_URL -u ANTHROPIC_API_KEY -u ANTHROPIC_AUTH_TOKEN` delante de cada comando `docker compose`, para que los valores de tu shell no lleguen al servidor.
* **Chat:** `ant beta:sessions connect` necesita una terminal interactiva. Sin una, envía el mensaje con `ant beta:sessions:events send` y lee la respuesta con `ant beta:sessions:events list`. [Enviar eventos](https://platform.claude.com/docs/es/managed-agents/events-and-streaming#send-events) y [Enumerar eventos pasados](https://platform.claude.com/docs/es/managed-agents/events-and-streaming#list-past-events) tienen ejemplos.
* **Consola:** Realiza la sección “Probar la consola en tu servidor” solo si la persona lo pide. Si tu shell no conserva las variables entre comandos, pon también `COMPOSE_FILE=docker-compose.yml:docker-compose.oidc.yml` delante de cada comando `docker compose` a partir de esa sección.

## 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](https://platform.claude.com/settings/keys).
* **Docker:** La [versión más reciente de Docker Engine](https://docs.docker.com/engine/install/) 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`](https://platform.claude.com/docs/es/cli-sdks-libraries/cli/quickstart#installation).

## Iniciar el stack

<Steps>
  <Step title="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`.

    ```bash
    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.
  </Step>

  <Step title="Crear el archivo .env">
    Compose lee los secretos del stack desde un archivo `.env` junto a `docker-compose.yml`. Crea el archivo:

    ```bash
    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.
  </Step>

  <Step title="Iniciar los contenedores">
    Compila e inicia el stack y luego sigue el registro del servidor:

    ```bash
    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.
  </Step>

  <Step title="Comprobar que el servidor está listo">
    ```bash
    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](https://platform.claude.com/docs/es/managed-agents/self-hosted/quickstart#troubleshooting).
  </Step>
</Steps>

## Ejecutar tu primera sesión

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

<Steps>
  <Step title="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](https://platform.claude.com/docs/es/managed-agents/self-hosted/call-the-api):

    ```bash
    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.
  </Step>

  <Step title="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.

    <CodeGroup>
      <CodeGroupItem>
        ```bash CLI
        ant apply --yes quickstart-agent.md
        ```

        <File filename="quickstart-agent.md">
          ```markdown
          ---
          name: Quickstart agent
          model: claude-opus-5-5
          tools:
            - type: agent_toolset_20260401
          ---

          You are a helpful assistant.
          ```
        </File>
      </CodeGroupItem>
    </CodeGroup>

    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.
  </Step>

  <Step title="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`.

    ```bash
    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)
    ```
  </Step>

  <Step title="Pedirle al agente que ejecute un comando">
    Conecta tu terminal a la sesión:

    ```bash
    ant beta:sessions connect "$SESSION_ID"
    ```

    El comando abre una [vista de chat](https://platform.claude.com/docs/es/cli-sdks-libraries/cli/sessions-connect) de la sesión. Envía este mensaje:

    ```text wrap
    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.
  </Step>

  <Step title="Encontrar el contenedor de sandbox">
    Deja el chat abierto. En la primera terminal, enumera los contenedores de sandbox:

    ```bash
    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.
  </Step>
</Steps>

## 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.

<Warning>
  Usa el proveedor simulado solo con datos desechables. Le da un token de administrador a cualquiera que acceda a él. En Docker Desktop, eso incluye los contenedores de sandbox. Con algunas versiones de Docker Engine anteriores a la 28.3.3, incluye las máquinas de tu red.
</Warning>

<Steps>
  <Step title="Reiniciar el stack con el proveedor de inicio de sesión simulado">
    Ejecuta estos comandos en la primera terminal:

    ```bash
    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`.
  </Step>

  <Step title="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.
  </Step>
</Steps>

Para crear agentes e iniciar sesiones también en la consola, consulta [Ejecutar un agente desde la consola](https://platform.claude.com/docs/es/managed-agents/self-hosted/console#run-an-agent-from-the-console).

## Detener el stack

En la primera terminal, ejecuta este comando:

```bash
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](https://platform.claude.com/docs/es/managed-agents/self-hosted/upgrade).

* **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

<CardGroup cols={2}>
  <Card title="Llamar a la API" icon="code-brackets" href="https://platform.claude.com/docs/es/managed-agents/self-hosted/call-the-api">
    Apunta el SDK y la CLI `ant` a tu servidor.
  </Card>

  <Card title="Diferencias con el servicio alojado" icon="arrows-left-right" href="https://platform.claude.com/docs/es/managed-agents/self-hosted/differences">
    Comprueba qué funciones se comportan de forma diferente o no están disponibles.
  </Card>

  <Card title="Consola de tu servidor" icon="browser" href="https://platform.claude.com/docs/es/managed-agents/self-hosted/console">
    Configura el inicio de sesión, y crea agentes y ejecuta sesiones en un navegador.
  </Card>
</CardGroup>