Sandboxes auto-hospedados

Os "self-hosted sandboxes" (sandboxes auto-hospedados) movem a execução de ferramentas do agente dos sandboxes em nuvem gerenciados pela Anthropic para uma infraestrutura que você controla, enquanto a Anthropic continua executando o agente. Para entender o que isso significa e decidir se é adequado para o seu agente, consulte Escolhendo um ambiente de agente.

Como funciona

Um ambiente self_hosted atua como uma fila de trabalho. Você executa um "environment worker" (worker de ambiente), um processo na sua própria infraestrutura que atende essa fila:

1. Você cria uma sessão que tem o ambiente como destino. A Anthropic enfileira a sessão como um item de trabalho.
2. Seu worker reivindica o item de trabalho e baixa as skills do agente e os memory stores da sessão.
3. Claude é executado do lado da Anthropic e solicita chamadas de ferramentas. Seu worker executa cada chamada localmente e envia o resultado de volta.

As entradas e saídas das ferramentas ainda fluem para o plano de controle da Anthropic, para que o modelo possa ver os resultados e determinar o que fazer em seguida. A Anthropic armazena as skills e os memory stores. Seu sandbox mantém uma cópia para a sessão. Consulte Modelo de segurança para ver o limite completo do fluxo de dados.

Os sandboxes auto-hospedados oferecem suporte a todos os modelos Claude disponíveis no Managed Agents. O modelo é configurado no agente, não no ambiente.

A CLI ant e os SDKs de Python, TypeScript e Go incluem workers pré-construídos. Provedores de sandbox como Cloudflare, Daytona e Modal também publicam seus próprios guias de plataforma.

Início rápido

Este início rápido executa um worker sempre ativo com a CLI ant, envia uma sessão para ele e confirma que as chamadas de ferramentas do agente foram executadas no seu host.

Pré-requisitos

• Um agente: Se você não tiver um, conclua primeiro Comece a usar o Claude Managed Agents e anote o ID do agente.
• Um host Linux: O host precisa de /bin/bash exatamente nesse caminho. O worker precisa apenas de HTTPS de saída.
• Uma chave de API do Claude: Você a usa a partir da sua própria máquina para criar sessões e ler estatísticas da fila. Mantenha-a fora do host do worker, onde as chamadas de ferramentas do agente poderiam lê-la.
• A CLI ant ou o SDK na sua própria máquina: As etapas de estatísticas e de sessão deste início rápido são executadas lá, não no host do worker. Instale a CLI da mesma forma que a etapa de instalação faz para o worker, ou instale o SDK.

Execute sua primeira sessão

1. 1

   Crie um ambiente auto-hospedado

   No Claude Console, acesse a página Environments (platform.claude.com/environments), clique em Create environment e, em Hosting, selecione Self-hosted.

   Ou por meio da API:

   cURLCLIPythonTypeScriptC#GoJavaPHPRuby

   CLI

   

   ant apply environment.yaml

   environment.yaml

   

   # yaml-language-server: $schema=https://platform.claude.com/schemas/ant/beta/environment.json
   name: self-hosted
   config:
     type: self_hosted

2. 2

   Gere uma chave de ambiente

   No Console, abra o ambiente e clique em Generate environment key. A chave de ambiente autentica o worker na sua fila. Você só pode gerar uma no Console, mesmo para um ambiente que você criou por meio da API.

   Exporte o ID do ambiente e a chave no host do worker:

   export ANTHROPIC_ENVIRONMENT_KEY="sk-ant-oat01-..."
   export ANTHROPIC_ENVIRONMENT_ID="env_..."

   
3. 3

   Instale a CLI ant

   Execute isto no host do worker.

   curl (Linux/WSL)Homebrew (macOS)

   curl (Linux/WSL)

   Para ambientes Linux, baixe o binário da versão diretamente.

   VERSION=1.42.0
   OS=$(uname -s | tr '[:upper:]' '[:lower:]')
   case $(uname -m) in
     x86_64) ARCH=amd64 ;;
     aarch64) ARCH=arm64 ;;
   esac
   curl -fsSL "https://github.com/anthropics/anthropic-cli/releases/download/v${VERSION}/ant_${VERSION}_${OS}_${ARCH}.tar.gz" \
     | sudo tar -xz -C /usr/local/bin ant

   

   Você pode encontrar todas as versões na página de releases do GitHub.

4. 4

   Inicie o worker

   Crie o diretório de trabalho e, em seguida, inicie o worker. --workdir usa o diretório atual como padrão, então passe /workspace para corresponder ao padrão do sistema.

   sudo mkdir -p /workspace && sudo chown "$USER" /workspace
   ant beta:worker poll --workdir /workspace

   

   O worker lê as duas variáveis que você exportou e faz polling até que você o interrompa.

5. 5

   Verifique se o worker está conectado

   Na sua própria máquina, defina ANTHROPIC_API_KEY como sua chave de API do Claude (não a chave de ambiente) e environment_id como o ID do ambiente. Confirme que workers_polling é pelo menos 1:

   cURLCLIPythonTypeScriptC#GoJavaPHPRuby

   Python

   

   client = anthropic.Anthropic()
   
   stats = client.beta.environments.work.stats(environment_id)
   print(f"workers_polling={stats.workers_polling}")

   Se workers_polling permanecer em 0, consulte Solução de problemas.

6. 6

   Inicie uma sessão

   Defina agent_id como o ID do seu agente. Crie uma sessão que tenha o ambiente como destino e, em seguida, envie uma tarefa para ela:

   cURLCLIPythonTypeScriptC#GoJavaPHPRuby

   Python

   

   session = client.beta.sessions.create(
       agent=agent_id,
       environment_id=environment_id,
   )
   
   client.beta.sessions.events.send(
       session.id,
       events=[
           {
               "type": "user.message",
               "content": [
                   {
                       "type": "text",
                       "text": 'Write the output of "uname -a" to hello.txt in your working directory.',
                   },
               ],
           },
       ],
   )

   A sessão aguarda na fila do ambiente até que um worker a reivindique. Se nenhum worker estiver conectado, a sessão permanece na fila em vez de falhar.

7. 7

   Confirme que as ferramentas foram executadas no seu host

   No host do worker, leia o arquivo que o agente escreveu:

   cat /workspace/hello.txt

   

   O arquivo descreve o kernel do seu próprio host, portanto as chamadas de ferramentas do agente foram executadas lá. Para acompanhar o trabalho do agente enquanto ele acontece, consulte Fluxo de eventos da sessão.

Recursos da sessão

Os sandboxes auto-hospedados oferecem suporte apenas a recursos memory_store. Uma sessão em um ambiente auto-hospedado que inclua um recurso file ou github_repository é rejeitada com um erro 400:

Environment env_... is a self-hosted environment. `resources` are not supported with self-hosted environments.

Deployments que têm um ambiente auto-hospedado como destino seguem a mesma regra. Para fornecer a uma sessão seus próprios arquivos de entrada, consulte Preparar arquivos para uma sessão.

Sandboxes auto-hospedados e túneis MCP

A auto-hospedagem controla onde o código do agente é executado. Os túneis MCP controlam como a Anthropic alcança servidores MCP na sua rede. Os dois são independentes:

• Uma sessão nos sandboxes em nuvem da Anthropic pode alcançar servidores MCP privados por meio de um túnel. Por exemplo, um servidor MCP privado pode ficar na frente de um banco de dados ou de uma API interna atrás do seu firewall.
• Uma sessão auto-hospedada pode usar servidores MCP tunelados ou públicos.

Use ambos quando quiser que a execução e o acesso às ferramentas permaneçam dentro do seu limite. Para dispensar o túnel, encapsule o servidor MCP como ferramentas personalizadas que seu worker atende.

Guias de plataforma

Estas páginas descrevem como construir um worker em qualquer plataforma de sandboxing. Guias específicos de plataforma também estão disponíveis:

• AWS Lambda MicroVMs
• Blaxel
• Cloudflare
• Daytona
• E2B
• Fly.io
• GKE Agent Sandbox
• Modal
• Namespace
• Superserve
• Vercel

Próximos passos