--- title: Sandboxes auto-hospedados url: https://platform.claude.com/docs/pt-BR/managed-agents/self-hosted-sandboxes description: Execute sessões do Claude Managed Agents em sandboxes auto-hospedados, mantendo a execução de ferramentas, os arquivos e o tráfego de saída de rede na sua própria infraestrutura. featureMetadata: topic: title: Managed Agents url: https://platform.claude.com/docs/en/managed-agents/overview status: beta betaHeader: managed-agents-2026-04-01 --- 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](https://platform.claude.com/docs/pt-BR/managed-agents/choosing-an-environment). ## 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](https://platform.claude.com/docs/pt-BR/managed-agents/sessions) 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](https://platform.claude.com/docs/pt-BR/managed-agents/skills) do agente e os [memory stores](https://platform.claude.com/docs/pt-BR/managed-agents/memory) 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](https://platform.claude.com/docs/pt-BR/managed-agents/self-hosted-sandboxes-security) 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](https://platform.claude.com/docs/pt-BR/managed-agents/self-hosted-sandboxes#platform-guides). ## 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](https://platform.claude.com/docs/pt-BR/managed-agents/quickstart) 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](https://platform.claude.com/docs/pt-BR/managed-agents/self-hosted-sandboxes#run-your-first-session) faz para o worker, ou instale o [SDK](https://platform.claude.com/docs/pt-BR/cli-sdks-libraries/overview). No [Claude Platform on AWS](https://platform.claude.com/docs/pt-BR/build-with-claude/claude-platform-on-aws), o worker se autentica com AWS IAM (SigV4) ou com uma [chave de API gerada no AWS Console](https://platform.claude.com/docs/pt-BR/build-with-claude/claude-platform-on-aws#api-key-authentication), não com uma chave de ambiente. Anexe a política gerenciada [`AnthropicSelfHostedEnvironmentAccess`](https://platform.claude.com/docs/pt-BR/api/claude-platform-on-aws-iam-actions#managed-policies) ao principal do IAM com o qual seu worker é executado. Chaves de ambiente geradas no Claude Console não funcionam com o endpoint do Claude Platform on AWS. ### Execute sua primeira sessão No Claude Console, acesse a página [Environments](https://platform.claude.com/environments) (`platform.claude.com/environments`), clique em **Create environment** e, em **Hosting**, selecione **Self-hosted**. Ou por meio da API: ```bash cURL curl -sS --fail-with-body https://api.anthropic.com/v1/environments \ -H "x-api-key: $ANTHROPIC_API_KEY" \ -H "anthropic-version: 2023-06-01" \ -H "anthropic-beta: managed-agents-2026-04-01" \ -H "content-type: application/json" \ -d '{ "name": "self-hosted", "config": {"type": "self_hosted"} }' ``` ```bash CLI ant apply environment.yaml ``` ```yaml # yaml-language-server: $schema=https://platform.claude.com/schemas/ant/beta/environment.json name: self-hosted config: type: self_hosted ``` ```python Python client = anthropic.Anthropic() environment = client.beta.environments.create( name="self-hosted", config={"type": "self_hosted"} ) print(environment.id) ``` ```typescript TypeScript const client = new Anthropic(); const environment = await client.beta.environments.create({ name: "self-hosted", config: { type: "self_hosted" } }); console.log(environment.id); ``` ```csharp C# using Anthropic.Models.Beta.Environments; var client = new AnthropicClient(); var environment = await client.Beta.Environments.Create( new EnvironmentCreateParams { Name = "self-hosted", Config = new BetaSelfHostedConfigParams(), } ); Console.WriteLine(environment.ID); ``` ```go Go client := anthropic.NewClient() environment, err := client.Beta.Environments.New(context.Background(), anthropic.BetaEnvironmentNewParams{ Name: "self-hosted", Config: anthropic.BetaEnvironmentNewParamsConfigUnion{ OfSelfHosted: &anthropic.BetaSelfHostedConfigParams{}, }, }) if err != nil { panic(err) } fmt.Println(environment.ID) ``` ```java Java import com.anthropic.models.beta.environments.BetaSelfHostedConfigParams; import com.anthropic.models.beta.environments.EnvironmentCreateParams; void main() { var client = AnthropicOkHttpClient.fromEnv(); var environment = client.beta().environments().create( EnvironmentCreateParams.builder() .name("self-hosted") .config(BetaSelfHostedConfigParams.builder().build()) .build() ); IO.println(environment.id()); } ``` ```php PHP $client = new \Anthropic\Client(); $environment = $client->beta->environments->create( name: 'self-hosted', config: ['type' => 'self_hosted'], ); echo $environment->id, PHP_EOL; ``` ```ruby Ruby client = Anthropic::Client.new environment = client.beta.environments.create( name: "self-hosted", config: {type: :self_hosted} ) puts environment.id ``` 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: ```bash export ANTHROPIC_ENVIRONMENT_KEY="sk-ant-oat01-..." export ANTHROPIC_ENVIRONMENT_ID="env_..." ``` Execute isto no host do worker. Para ambientes Linux, baixe o binário da versão diretamente. ```bash 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](https://github.com/anthropics/anthropic-cli/releases). ```bash brew install anthropics/tap/ant ``` 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. ```bash 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. Na sua própria máquina, defina `ANTHROPIC_API_KEY` como sua chave de API do Claude (não a chave de ambiente) e `ANTHROPIC_ENVIRONMENT_ID` (python, ruby: `environment_id`; typescript, java, csharp: `environmentId`; go: `environmentID`; php: `$environmentId`) como o ID do ambiente. Confirme que `workers_polling` (java, php: `workersPolling`; csharp, go: `WorkersPolling`) é pelo menos 1: ```bash cURL curl -sS --fail-with-body "https://api.anthropic.com/v1/environments/$ANTHROPIC_ENVIRONMENT_ID/work/stats" \ -H "x-api-key: $ANTHROPIC_API_KEY" \ -H "anthropic-version: 2023-06-01" \ -H "anthropic-beta: managed-agents-2026-04-01" ``` ```bash CLI ant beta:environments:work stats --environment-id "$ANTHROPIC_ENVIRONMENT_ID" ``` ```python Python client = anthropic.Anthropic() stats = client.beta.environments.work.stats(environment_id) print(f"workers_polling={stats.workers_polling}") ``` ```typescript TypeScript const client = new Anthropic(); const stats = await client.beta.environments.work.stats(environmentId); console.log(`workers_polling=${stats.workers_polling}`); ``` ```csharp C# var client = new AnthropicClient(); var stats = await client.Beta.Environments.Work.Stats(environmentId); Console.WriteLine($"workers_polling={stats.WorkersPolling}"); ``` ```go Go client := anthropic.NewClient() stats, err := client.Beta.Environments.Work.Stats( context.Background(), environmentID, anthropic.BetaEnvironmentWorkStatsParams{}, ) if err != nil { panic(err) } fmt.Printf("workers_polling=%d\n", stats.WorkersPolling) ``` ```java Java var client = AnthropicOkHttpClient.fromEnv(); var stats = client.beta().environments().work().stats(environmentId); IO.println("workers_polling=" + stats.workersPolling().orElse(null)); ``` ```php PHP $client = new Client(); $stats = $client->beta->environments->work->stats($environmentId); printf("workers_polling=%d\n", $stats->workersPolling); ``` ```ruby Ruby client = Anthropic::Client.new stats = client.beta.environments.work.stats(environment_id) puts "workers_polling=#{stats.workers_polling}" ``` Se `workers_polling` (java, php: `workersPolling`; csharp, go: `WorkersPolling`) permanecer em 0, consulte [Solução de problemas](https://platform.claude.com/docs/pt-BR/managed-agents/self-hosted-sandboxes-operations#troubleshooting). Defina `AGENT_ID` (python, ruby: `agent_id`; typescript, java, csharp: `agentId`; go: `agentID`; php: `$agentId`) como o ID do seu agente. Crie uma sessão que tenha o ambiente como destino e, em seguida, envie uma tarefa para ela: ```bash cURL SESSION_ID=$(curl -sS --fail-with-body https://api.anthropic.com/v1/sessions \ -H "x-api-key: $ANTHROPIC_API_KEY" \ -H "anthropic-version: 2023-06-01" \ -H "anthropic-beta: managed-agents-2026-04-01" \ -H "content-type: application/json" \ -d '{ "agent": "'"$AGENT_ID"'", "environment_id": "'"$ANTHROPIC_ENVIRONMENT_ID"'" }' | jq -er '.id' ) curl -sS --fail-with-body "https://api.anthropic.com/v1/sessions/$SESSION_ID/events" \ -H "x-api-key: $ANTHROPIC_API_KEY" \ -H "anthropic-version: 2023-06-01" \ -H "anthropic-beta: managed-agents-2026-04-01" \ -H "content-type: application/json" \ -d '{ "events": [ { "type": "user.message", "content": [ { "type": "text", "text": "Write the output of \"uname -a\" to hello.txt in your working directory." } ] } ] }' ``` ```bash CLI SESSION_ID=$(ant beta:sessions create \ --agent "$AGENT_ID" \ --environment-id "$ANTHROPIC_ENVIRONMENT_ID" \ --transform id --raw-output) ant beta:sessions:events send --session-id "$SESSION_ID" <<'YAML' events: - type: user.message content: - type: text text: Write the output of "uname -a" to hello.txt in your working directory. YAML ``` ```python 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.', }, ], }, ], ) ``` ```typescript TypeScript const session = await client.beta.sessions.create({ agent: agentId, environment_id: environmentId }); await 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.' } ] } ] }); ``` ```csharp C# var session = await client.Beta.Sessions.Create(new() { Agent = agentId, EnvironmentID = environmentId, }); await client.Beta.Sessions.Events.Send(session.ID, new() { Events = [ new BetaManagedAgentsUserMessageEventParams { Type = BetaManagedAgentsUserMessageEventParamsType.UserMessage, Content = [ new BetaManagedAgentsTextBlock { Type = BetaManagedAgentsTextBlockType.Text, Text = "Write the output of \"uname -a\" to hello.txt in your working directory.", }, ], }, ], }); ``` ```go Go session, err := client.Beta.Sessions.New(context.Background(), anthropic.BetaSessionNewParams{ Agent: anthropic.BetaSessionNewParamsAgentUnion{OfString: anthropic.String(agentID)}, EnvironmentID: environmentID, }) if err != nil { panic(err) } _, err = client.Beta.Sessions.Events.Send(context.Background(), session.ID, anthropic.BetaSessionEventSendParams{ Events: []anthropic.BetaManagedAgentsEventParamsUnion{{ OfUserMessage: &anthropic.BetaManagedAgentsUserMessageEventParams{ Type: anthropic.BetaManagedAgentsUserMessageEventParamsTypeUserMessage, Content: []anthropic.BetaManagedAgentsUserMessageEventParamsContentUnion{{ OfText: &anthropic.BetaManagedAgentsTextBlockParam{ Type: anthropic.BetaManagedAgentsTextBlockTypeText, Text: "Write the output of \"uname -a\" to hello.txt in your working directory.", }, }}, }, }}, }) if err != nil { panic(err) } ``` ```java Java var session = client.beta().sessions().create(SessionCreateParams.builder() .agent(agentId) .environmentId(environmentId) .build()); client.beta().sessions().events().send( session.id(), EventSendParams.builder() .addEvent(BetaManagedAgentsUserMessageEventParams.builder() .type(BetaManagedAgentsUserMessageEventParams.Type.USER_MESSAGE) .addTextContent("Write the output of \"uname -a\" to hello.txt in your working directory.") .build()) .build()); ``` ```php PHP $session = $client->beta->sessions->create( agent: $agentId, environmentID: $environmentId, ); $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.']], ], ], ); ``` ```ruby Ruby 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. No host do worker, leia o arquivo que o agente escreveu: ```bash 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](https://platform.claude.com/docs/pt-BR/managed-agents/events-and-streaming). ## 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: ```text wrap Environment env_... is a self-hosted environment. `resources` are not supported with self-hosted environments. ``` [Deployments](https://platform.claude.com/docs/pt-BR/managed-agents/scheduled-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](https://platform.claude.com/docs/pt-BR/managed-agents/self-hosted-sandboxes-workers#stage-files-for-a-session). ## Sandboxes auto-hospedados e túneis MCP A auto-hospedagem controla *onde o código do agente é executado*. Os [túneis MCP](https://platform.claude.com/docs/pt-BR/agents-and-tools/mcp-tunnels/overview) 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](https://platform.claude.com/docs/pt-BR/managed-agents/self-hosted-sandboxes-custom-tools#wrap-an-mcp-server-as-custom-tools) 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](https://docs.aws.amazon.com/lambda/latest/dg/microvms-integrations-claude-managed-agents.html) * [Blaxel](https://docs.blaxel.ai/Tutorials/Claude-Managed-Agents) * [Cloudflare](https://developers.cloudflare.com/sandbox/claude-managed-agents/) * [Daytona](https://www.daytona.io/docs/en/guides/claude/claude-managed-agents) * [E2B](https://e2b.dev/docs/agents/claude-managed-agents) * [Fly.io](https://docs.sprites.dev/integrations/claude-managed-agents/) * [GKE Agent Sandbox](https://github.com/GoogleCloudPlatform/kubernetes-engine-samples/tree/main/ai-ml/anthropic-agent-sandbox) * [Modal](https://github.com/modal-labs/claude-managed-agents-modal-sandbox) * [Namespace](https://namespace.so/docs/integrations/claude) * [Superserve](https://docs.superserve.ai/integrations/managed-agents/claude-managed-agents) * [Vercel](https://vercel.com/kb/guide/run-claude-managed-agent-tools-with-vercel-sandbox) ## Próximos passos Execute o worker do SDK, acione workers a partir de webhooks ou dê a cada sessão seu próprio sandbox. Prepare o host, configure a sincronização e lide com stores somente leitura e conflitos. Sirva suas próprias ferramentas a partir do worker, incluindo ferramentas de um servidor MCP dentro da sua rede. Leia a profundidade da fila, interrompa sessões e workers de forma limpa e corrija falhas comuns. Flags da CLI, variáveis de ambiente, caminhos do sistema de arquivos e opções dos helpers do SDK. Modelo de responsabilidade compartilhada para ambientes de sandbox auto-hospedados.