---
title: Comece a usar o Claude Managed Agents auto-hospedado
url: https://platform.claude.com/docs/pt-BR/managed-agents/self-hosted/quickstart
description: Inicie o Claude Managed Agents auto-hospedado em uma única máquina com Docker Compose e execute uma primeira sessão em um contêiner de sandbox.
---

<Note>
  Para solicitar acesso ao Claude Managed Agents auto-hospedado, entre em contato com a equipe da sua conta na Anthropic.
</Note>

Neste guia de início rápido, você inicia o Claude Managed Agents auto-hospedado em uma única máquina com Docker Compose. A stack do Compose é composta pelo servidor, seu banco de dados PostgreSQL e um conjunto de “workers” (processos de trabalho) que executam cada sessão em um contêiner de “sandbox” (ambiente isolado) próprio. Em seguida, você conversa com um agente a partir do seu terminal e confirma que as chamadas de ferramentas dele foram executadas em um contêiner de sandbox. Depois, você pode abrir a sessão no [console do seu servidor](https://platform.claude.com/docs/pt-BR/managed-agents/self-hosted/console).

<Warning>
  A stack do Compose serve para desenvolvimento, não para produção. Ela serve HTTP simples e, por padrão, publica a porta 8400 apenas no endereço de loopback do host Docker, `127.0.0.1`. Em algumas versões do Docker Engine anteriores à 28.3.3, máquinas na rede local do host também conseguem acessar essa porta. As ferramentas do agente são executadas em contêineres nesse host, então use uma máquina que não contenha nada que você precise proteger.
</Warning>

Para produção, a Anthropic recomenda os dois Helm charts da versão. Consulte [Implantar no Kubernetes](https://platform.claude.com/docs/pt-BR/managed-agents/self-hosted/kubernetes).

Deixe o Claude Code executar este guia de início rápido para você

```text
Configure o Claude Managed Agents auto-hospedado nesta máquina seguindo https://platform.claude.com/docs/en/managed-agents/self-hosted/quickstart.md. Eu já baixei o arquivo compactado da versão.
```

Se você é um agente que executa estas etapas para uma pessoa:

* **Arquivo compactado da versão:** Pergunte à pessoa onde está o arquivo compactado. Somente ela pode baixá-lo.
* **Chave de API do Claude:** Peça à pessoa que edite o `.env` ela mesma. Não peça a chave e não exiba o conteúdo do `.env`.
* **Variáveis:** Se o seu shell não mantém variáveis entre comandos, defina `ANTHROPIC_BASE_URL` e `ANTHROPIC_API_KEY` novamente em cada comando `ant`. Sem elas, o `ant` chama o serviço hospedado.
* **Compose:** Coloque `env -u ANTHROPIC_BASE_URL -u ANTHROPIC_API_KEY -u ANTHROPIC_AUTH_TOKEN` na frente de cada comando `docker compose`, para que os valores do seu shell não cheguem ao servidor.
* **Chat:** `ant beta:sessions connect` precisa de um terminal interativo. Sem um, envie a mensagem com `ant beta:sessions:events send` e leia a resposta com `ant beta:sessions:events list`. [Enviar eventos](https://platform.claude.com/docs/pt-BR/managed-agents/events-and-streaming#send-events) e [Listar eventos anteriores](https://platform.claude.com/docs/pt-BR/managed-agents/events-and-streaming#list-past-events) têm exemplos.
* **Console:** Execute a seção “Experimente o console no seu servidor” somente se a pessoa pedir. Se o seu shell não mantém variáveis entre comandos, coloque também `COMPOSE_FILE=docker-compose.yml:docker-compose.oidc.yml` na frente de cada comando `docker compose` a partir dessa seção.

## Pré-requisitos

* **O arquivo compactado da versão:** Para solicitar acesso ao download, entre em contato com a equipe da sua conta na Anthropic.
* **Uma chave de API do Claude:** O servidor a usa para chamadas ao modelo. Crie uma no [Claude Console](https://platform.claude.com/settings/keys).
* **Docker:** A [versão mais recente do Docker Engine](https://docs.docker.com/engine/install/) com o plugin Compose (`docker compose`, não o antigo `docker-compose`).
* **Um host com pelo menos duas CPUs:** x86-64 ou Arm. Em um host menor, defina `CMA_SANDBOX_CPUS` com o número de CPUs dele ao criar o `.env`.
* **Acesso à rede na primeira inicialização:** O primeiro build baixa conteúdo do Docker Hub, dos repositórios de pacotes do Alpine e de releases do GitHub.
* **Ferramentas:** Na máquina onde você executa o Docker, você precisa do `openssl` e da [CLI `ant`](https://platform.claude.com/docs/pt-BR/cli-sdks-libraries/cli/quickstart#installation).

## Inicie a stack

<Steps>
  <Step title="Extraia o arquivo compactado">
    Extraia o arquivo compactado e trabalhe a partir do diretório `compose` dele. No comando, substitua `<archive>` pelo nome do seu arquivo compactado, sem `.tar.gz`.

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

    Se a sua umask for mais restritiva que `022`, os binários perdem a permissão de execução para outros usuários, e o contêiner do servidor não consegue iniciá-los. Nesse caso, defina-a como `022` e extraia o arquivo compactado novamente.
  </Step>

  <Step title="Crie o arquivo .env">
    O Compose lê os segredos da stack de um arquivo `.env` ao lado do `docker-compose.yml`. Crie o arquivo:

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

    Abra o `.env` em um editor e substitua `sk-ant-...` pela sua chave de API do Claude. O bloco gera o restante: a senha do banco de dados, a chave de API do servidor que suas aplicações enviam e a chave que criptografa os segredos armazenados do servidor.
  </Step>

  <Step title="Inicie os contêineres">
    Faça o build e inicie a stack e, em seguida, acompanhe o log do servidor:

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

    Quando o log mostrar uma linha com `msg="cma-server listening"`, pressione Ctrl+C para parar de acompanhá-lo.
  </Step>

  <Step title="Verifique se o servidor está pronto">
    ```bash
    curl -s http://127.0.0.1:8400/cma-server/readyz
    ```

    Um servidor pronto responde com `"status":"ready"`. Logo após a inicialização, ele pode responder `"status":"degraded"` por alguns segundos enquanto suas primeiras verificações são executadas. Se ele permanecer `degraded` ou responder `"status":"not_ready"`, consulte [Solução de problemas](https://platform.claude.com/docs/pt-BR/managed-agents/self-hosted/quickstart#troubleshooting).
  </Step>
</Steps>

## Execute sua primeira sessão

Crie um agente e converse com ele a partir do seu terminal com a CLI `ant`.

<Steps>
  <Step title="Aponte a CLI para o seu servidor">
    Abra um segundo terminal no mesmo diretório e reserve-o para o `ant`. Os comandos a seguir definem `ANTHROPIC_API_KEY` com a chave de API do seu servidor, não com a sua chave de API do Claude, como explica [Chamar a API em um servidor auto-hospedado](https://platform.claude.com/docs/pt-BR/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)
    ```

    Mantenha os comandos `docker compose` no primeiro terminal. Se você executar `docker compose up` neste terminal, o Compose passa essas variáveis para o servidor, e o servidor chama a si mesmo em vez da API do Claude.
  </Step>

  <Step title="Crie um agente">
    Salve o arquivo que vem depois do comando como `quickstart-agent.md` e, em seguida, execute o comando. O arquivo dá ao agente as ferramentas integradas e permite que ele as execute sem perguntar a você primeiro.

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

    O comando primeiro exibe um aviso de que `could not determine the organization and workspace`, com um erro `404`, e depois cria o agente. Isso é esperado no seu próprio servidor.
  </Step>

  <Step title="Inicie uma sessão">
    Estes comandos encontram o agente e o ambiente da stack, iniciam uma sessão e guardam o ID da sessão em `SESSION_ID`. A stack chama seu ambiente de `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="Peça ao agente para executar um comando">
    Conecte seu terminal à sessão:

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

    O comando abre uma [visualização de chat](https://platform.claude.com/docs/pt-BR/cli-sdks-libraries/cli/sessions-connect) da sessão. Envie esta mensagem:

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

    O agente responde com um hostname que começa com `cma-sandbox-`. Esse é o nome do contêiner de sandbox que executou o comando, o que confirma que a ferramenta foi executada em um sandbox e não na sua máquina.
  </Step>

  <Step title="Encontre o contêiner de sandbox">
    Deixe o chat aberto. No primeiro terminal, liste os contêineres de sandbox:

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

    A lista mostra o contêiner que o agente informou. O contêiner é encerrado cerca de um minuto depois que um turno termina, e a próxima mensagem da sessão inicia um novo contêiner. Se a lista estiver vazia, peça ao agente para executar `hostname` novamente e liste os contêineres outra vez enquanto ele responde.

    Para sair do chat, pressione Ctrl+C no terminal dele. A sessão continua em execução.
  </Step>
</Steps>

## Experimente o console no seu servidor

Esta seção é opcional. O console exige single sign-on. Para experimentá-lo, reinicie a stack com o provedor de login simulado da versão. A porta 8080 da sua máquina precisa estar livre.

<Warning>
  Use o provedor simulado apenas com dados descartáveis. Ele fornece um token de administrador a qualquer um que o acesse. No Docker Desktop, isso inclui os contêineres de sandbox. Em algumas versões do Docker Engine anteriores à 28.3.3, isso inclui máquinas na sua rede.
</Warning>

<Steps>
  <Step title="Reinicie a stack com o provedor de login simulado">
    Execute estes comandos no primeiro terminal:

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

    A linha `export` vale apenas para o primeiro terminal, então execute-a novamente em qualquer novo terminal que você abrir para o `docker compose`. Para alterar as configurações do servidor nesta stack, edite `compose.config.oidc.yaml`, não `compose.config.yaml`, e depois execute `docker compose restart cma-server`.
  </Step>

  <Step title="Abra a sessão">
    Em um navegador na mesma máquina, abra `http://127.0.0.1:8400/`, clique em **Continue with SSO** e selecione **alice**, a administradora de demonstração. Na barra lateral, selecione **Sessions** e, em seguida, selecione a sessão.

    A página é atualizada à medida que o agente trabalha, e você pode enviar uma mensagem ao agente a partir dela.
  </Step>
</Steps>

Para também criar agentes e iniciar sessões no console, consulte [Executar um agente a partir do console](https://platform.claude.com/docs/pt-BR/managed-agents/self-hosted/console#run-an-agent-from-the-console).

## Pare a stack

No primeiro terminal, execute este comando:

```bash
docker compose down --remove-orphans
```

O comando exclui os contêineres e mantém o banco de dados. Para excluir também o banco de dados, com todos os agentes, sessões e históricos de sessões nele, execute `docker compose down --remove-orphans -v`.

## Solução de problemas

* **Seu arquivo compactado não tem um diretório `compose`:** O arquivo compactado contém uma versão anterior, e os comandos desta página não correspondem a ela. Solicite a versão atual à equipe da sua conta na Anthropic. Para migrar uma implantação em execução para a versão atual, consulte [Atualizar o Claude Managed Agents auto-hospedado](https://platform.claude.com/docs/pt-BR/managed-agents/self-hosted/upgrade).

* **O servidor nunca fica disponível:** Execute `docker compose logs migrate`. O contêiner `migrate` de execução única cria as tabelas do banco de dados. Ele precisa encerrar com status `0` antes de o servidor ser iniciado.

* **A verificação de prontidão permanece `degraded` ou todos os turnos falham:** Se você executou `docker compose up` em um terminal em que `ANTHROPIC_BASE_URL` é `http://127.0.0.1:8400`, o servidor chama a si mesmo em vez da API do Claude. Execute `docker compose up -d` novamente no primeiro terminal, onde a variável não está definida. Caso contrário, o log do servidor mostra o que falhou. Para lê-lo, execute `docker compose logs -f cma-server` novamente.

* **A verificação de prontidão responde `not_ready`:** Na resposta, encontre a verificação com o estado `failed`:

  * **`upstream`:** A API do Claude rejeitou a sua chave de API do Claude. Corrija `ANTHROPIC_API_KEY` no `.env` e, em seguida, execute `docker compose up -d` novamente no primeiro terminal. Se o seu shell também define `ANTHROPIC_API_KEY`, o Compose usa o valor do shell, então execute `unset ANTHROPIC_API_KEY` antes.
  * **`database`:** Ou o banco de dados rejeitou o login do servidor, por exemplo por causa de uma senha errada, ou uma conexão aberta com o banco de dados foi interrompida. Para ver qual dos dois, execute `docker compose logs -f cma-server` novamente.

* **O agente responde, mas sua chamada de ferramenta nunca termina:** Nenhum worker está consultando o ambiente. Verifique o log dos workers com `docker compose logs sandbox`. Um worker que não consegue acessar o socket do daemon do Docker encerra com uma mensagem que menciona `CMA_DOCKER_SOCKET`. Defina essa variável no `.env` com o caminho do socket do seu daemon e, em seguida, execute `docker compose up -d` novamente no primeiro terminal.

* **Os workers estão em execução, mas uma chamada de ferramenta ainda nunca termina:** A stack inicia 10 workers, e cada um executa o contêiner de uma sessão por vez. Uma sessão ocupa um worker livre quando você a cria, e uma sessão que nunca recebe uma mensagem mantém seu worker por até uma hora. Com todos os 10 ocupados, as chamadas de ferramentas de qualquer outra sessão aguardam um worker. Se o comando `docker ps` da etapa “Encontre o contêiner de sandbox” listar 10 contêineres, arquive as sessões que você não usa:

  1. No primeiro terminal, execute `docker ps --filter label=cma-server.sandbox --format '{{.Label "cma-server.session"}}'`. Ele exibe o ID da sessão por trás de cada contêiner. A sessão que aguarda ainda não tem contêiner, então ela não está na lista.
  2. No segundo terminal, pressione Ctrl+C para sair do chat e execute `ant beta:sessions archive --session-id <session-id>` para cada sessão listada que você não usa.
  3. Execute `ant beta:sessions connect "$SESSION_ID"` novamente. A chamada de ferramenta termina quando um worker assume a sessão dela.

## Próximos passos

<CardGroup cols={2}>
  <Card title="Chamar a API" icon="code-brackets" href="https://platform.claude.com/docs/pt-BR/managed-agents/self-hosted/call-the-api">
    Aponte o SDK e a CLI `ant` para o seu servidor.
  </Card>

  <Card title="Diferenças em relação ao serviço hospedado" icon="arrows-left-right" href="https://platform.claude.com/docs/pt-BR/managed-agents/self-hosted/differences">
    Verifique quais recursos se comportam de forma diferente ou não estão disponíveis.
  </Card>

  <Card title="Console do seu servidor" icon="browser" href="https://platform.claude.com/docs/pt-BR/managed-agents/self-hosted/console">
    Configure o login e crie agentes e execute sessões em um navegador.
  </Card>
</CardGroup>