Comece a usar o Claude Managed Agents auto-hospedado

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.

Para produção, a Anthropic recomenda os dois Helm charts da versão. Consulte Implantar no Kubernetes.

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.
• Docker: A versão mais recente do Docker Engine 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.

Inicie a stack

1. 1

   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.

   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.

2. 2

   Crie o arquivo .env

   O Compose lê os segredos da stack de um arquivo .env ao lado do docker-compose.yml. Crie o arquivo:

   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.

3. 3

   Inicie os contêineres

   Faça o build e inicie a stack e, em seguida, acompanhe o log do servidor:

   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.

4. 4

   Verifique se o servidor está pronto

   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.

Execute sua primeira sessão

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

1. 1

   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:

   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.

2. 2

   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.

   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.

   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.

3. 3

   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.

   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

   Peça ao agente para executar um comando

   Conecte seu terminal à sessão:

   ant beta:sessions connect "$SESSION_ID"

   

   O comando abre uma visualização de chat da sessão. Envie esta mensagem:

   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.

5. 5

   Encontre o contêiner de sandbox

   Deixe o chat aberto. No primeiro terminal, liste os contêineres de sandbox:

   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.

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.

1. 1

   Reinicie a stack com o provedor de login simulado

   Execute estes comandos no primeiro terminal:

   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.

2. 2

   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.

Para também criar agentes e iniciar sessões no console, consulte Executar um agente a partir do console.

Pare a stack

No primeiro terminal, execute este comando:

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.
• 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