Executar um sandbox por sessão
Dê a cada sessão seu próprio sandbox auto-hospedado com o Helm chart no Kubernetes, um script de spawn ou o poller do SDK.
No padrão de sandbox por sessão, cada sessão é executada em um sandbox novo, que pode ter seu próprio sistema de arquivos, limites de recursos e controles de rede. Para compará-lo com os outros padrões, consulte Escolher um padrão de implantação.
Você pode configurá-lo de três maneiras:
- Helm chart no Kubernetes: O dispatcher da Anthropic reivindica o trabalho e inicia um pod para cada sessão no seu cluster.
- Script de spawn: A CLI
antreivindica o trabalho e chama seu script, que inicia um sandbox em qualquer plataforma. - Poller do SDK: Seu próprio código reivindica o trabalho e inicia o sandbox.
As seções após Executar sandboxes no Kubernetes se aplicam ao script de spawn e ao poller do SDK.
Executar sandboxes no Kubernetes
A Anthropic publica um Helm chart, cma-sandboxes, e suas imagens. O chart executa um sandbox por sessão no seu próprio cluster Kubernetes. Seu dispatcher consulta a fila de trabalho do ambiente e dá a cada sessão um pod próprio:
- Isolamento: Cada pod é executado sob o gVisor, protegido pelas políticas de rede do chart. Ele tem seu próprio sistema de arquivos e limites de recursos. Apenas o dispatcher detém a chave do ambiente.
- Afinidade de sessão: Cada mensagem de uma sessão vai para o sandbox dessa sessão. Depois que a sessão fica ociosa por 30 minutos (o padrão da configuração
sandbox.idleTimeoutdo chart), seu pod é parado. Seu volume/workspacepermanece até o fim da sessão. A próxima mensagem inicia um pod no mesmo volume. - Pool pré-aquecido: Exceto no Google Kubernetes Engine (GKE), o chart mantém dois pods prontos para novas sessões (o padrão da configuração
sandbox.warmPoolSizedo chart).
Os pods de sandbox executam o worker da CLI ant. Eles oferecem suporte a memory stores com as configurações de sincronização padrão e não oferecem suporte a ferramentas personalizadas.
Instalar o chart
O chart é executado no GKE, no Amazon EKS e em outros clusters. Configure o seguinte antes de instalá-lo:
- No cluster: O controlador Agent Sandbox (no GKE, o complemento Agent Sandbox), nós que executam o gVisor e um plugin de rede que aplique NetworkPolicy.
- No seu próprio namespace: Rótulos do Pod Security Standard restrito, um Secret com o ID do ambiente e a chave do ambiente e o certificado TLS do dispatcher.
O guia de instalação no GitHub tem as etapas de configuração para cada tipo de cluster. Ele também aborda atualizações e rotação de chaves.
Salve suas configurações como cma-values.yaml. A instalação falha sem as três configurações deste arquivo:
platform: gke # or eks, or generic for any other cluster
egress:
# The chart already blocks the private ranges. List your other addresses
# that sandboxes must not reach.
clusterCIDRs:
- 203.0.113.10/32 # your cluster's Kubernetes API endpoint
cmaServer:
public: true # the Claude API has a public addressO guia de instalação lista as configurações que dependem do seu cluster, como gke.dns no GKE Autopilot. Ele também informa quando egress.clusterIsPrivate: true substitui egress.clusterCIDRs.
Em seguida, instale o chart:
helm install cma \
oci://us-docker.pkg.dev/anthropic-public-registry/sandboxes/charts/cma-sandboxes \
--version 0.1.0 \
--namespace cma \
-f cma-values.yaml \
--waitApós a instalação, execute a verificação prévia descrita no guia de instalação.
Adicionar ferramentas à imagem do sandbox
A imagem de sandbox publicada é Alpine Linux com bash, curl, jq e a CLI ant. O chart a executa com um sistema de arquivos raiz somente leitura e como um usuário não root, então um agente não pode instalar pacotes durante uma sessão.
Para dar mais ferramentas aos seus agentes, como Python ou Git, crie as duas imagens a partir do repositório na tag da versão. A seção Install do guia de instalação tem os comandos. Envie as imagens para o seu registro como cma-dispatcher e cma-sandbox, com a versão do chart como tag. Em seguida, defina image.registry como esse registro. Se você fixar digests de imagem, use os digests das suas próprias imagens.
Restringir o egress de rede
Por padrão, as políticas de rede do chart permitem que um sandbox alcance a internet IPv4 pública. Elas bloqueiam intervalos de endereços privados, o servidor de metadados da nuvem e os endereços em egress.clusterCIDRs. Um agente que sofreu prompt injection pode enviar o que lê para qualquer endereço que seu sandbox consiga alcançar. Network egress no guia de instalação tem os detalhes.
- GKE com Dataplane V2: Defina
egress.mode: fqdnGkepara limitar as conexões à porta 443 nos hosts emegress.fqdnGke.hosts. Mantenhaapi.anthropic.comnessa lista e adicione todos os hosts de que os comandos dos seus agentes precisam. Ao contrário do padrão, esse modo não tem uma lista de intervalos bloqueados. Ele permite qualquer endereço para o qual o nome de um host listado seja resolvido, então liste apenas hosts cujo DNS seja confiável para você. Um sandbox ainda pode enviar dados para fora dentro de consultas DNS. - Outros clusters e GKE sem Dataplane V2: O padrão é o único modo.
- Todos os clusters: As políticas de rede não cobrem as portas nas quais os próprios nós do cluster escutam. Consulte Node isolation you own no guia de instalação.
Iniciar sandboxes com um script de spawn
Um poller no host reivindica o trabalho e chama seu script uma vez para cada item de trabalho. O script inicia um sandbox para essa única sessão.
Criar a imagem do sandbox
Instale o
ante definaant beta:worker runcomo entrypoint. Quando um sandbox é iniciado, ele lê os detalhes da sessão a partir de variáveis de ambiente, atende a essa sessão e encerra. A imagem base deve fornecer/bin/bash; a compilação usacurlapenas para baixar oant.DockerfileFROM your-base-image ARG ANT_VERSION=2.11.0 ARG TARGETARCH RUN ARCH=$([ "$TARGETARCH" = "arm64" ] && echo arm64 || echo amd64) && \ curl -fsSL "https://github.com/anthropics/anthropic-cli/releases/download/v${ANT_VERSION}/ant_${ANT_VERSION}_linux_${ARCH}.tar.gz" \ | tar -xz -C /usr/local/bin ant WORKDIR /workspace VOLUME /workspace ENTRYPOINT ["ant", "beta:worker", "run"]Escrever o script de spawn
O script encaminha os detalhes da sessão para um sandbox novo. Ele requer
jqno host do poller.spawn.sh#!/bin/bash # spawn.sh: chamado uma vez para cada item de trabalho reivindicado # O item de trabalho reivindicado chega como JSON pelo stdin. ANTHROPIC_WORK_SECRET="$(jq -r '.secret // empty')" export ANTHROPIC_WORK_SECRET mkdir -p "/host/outputs/$ANTHROPIC_SESSION_ID" exec docker run --rm \ -e ANTHROPIC_SESSION_ID -e ANTHROPIC_ENVIRONMENT_KEY \ -e ANTHROPIC_WORK_ID -e ANTHROPIC_ENVIRONMENT_ID -e ANTHROPIC_BASE_URL \ -e ANTHROPIC_WORK_SECRET \ -v "/host/outputs/$ANTHROPIC_SESSION_ID":/workspace \ your-imageO poller define
ANTHROPIC_WORK_ID,ANTHROPIC_ENVIRONMENT_ID,ANTHROPIC_SESSION_IDeANTHROPIC_ENVIRONMENT_KEY.ANTHROPIC_BASE_URLsó chega ao script se você a definir no host do poller. O script lêANTHROPIC_WORK_SECRETdo JSON do item de trabalho na entrada padrão. Consulte Variáveis de ambiente./host/outputsé um diretório do host que você escolhe. Montá-lo em/workspacepermite recuperar os entregáveis da sessão depois que o sandbox encerra. A montagem também inclui a árvoreskills/baixada e quaisquer arquivos intermediários.Iniciar o poller
ant beta:worker poll --on-work ./spawn.sh
Encaminhar o segredo do item de trabalho
Cada item de trabalho reivindicado pode conter um secret que a Anthropic emite para essa sessão. O worker que executa a sessão precisa dele para montar memory stores.
Um worker que reivindica e executa sessões em um único processo repassa o segredo por conta própria. EnvironmentWorker com run() é um desses workers, e ant beta:worker poll sem --on-work é outro. Quando seu próprio código fica entre a reivindicação e o worker, você encaminha o segredo:
| Você reivindica trabalho com | O segredo chega como | Repasse-o ao worker como |
|---|---|---|
ant beta:worker poll --on-work | O campo secret do JSON do item de trabalho na entrada padrão do seu script | ANTHROPIC_WORK_SECRET no ambiente do sandbox |
work.poller() do SDK para Python, TypeScript ou Go | O campo secret de cada item de trabalho reivindicado | ANTHROPIC_WORK_SECRET no ambiente do sandbox ou o argumento work_secret de handle_item() |
Repasse o segredo apenas para o sandbox que atende a essa sessão e nunca o registre em log. Consulte Modelo de segurança para saber como ele se relaciona com a chave do ambiente.
Iniciar sandboxes a partir do poller do SDK
Para reivindicar trabalho a partir do seu próprio código em vez de ant beta:worker poll --on-work, use o poller do SDK para Python, TypeScript ou Go: work.poller(). Ele consulta a fila e entrega a você cada sessão reivindicada, e você inicia o sandbox:
import asyncio
import os
from anthropic import AsyncAnthropic
from anthropic.types.beta.environments import BetaSelfHostedWork
SANDBOX_ENV = (
"ANTHROPIC_ENVIRONMENT_ID",
"ANTHROPIC_ENVIRONMENT_KEY",
"ANTHROPIC_WORK_ID",
"ANTHROPIC_SESSION_ID",
"ANTHROPIC_WORK_SECRET",
"ANTHROPIC_BASE_URL", # forwarded only when set on this host
)
async def launch_container(work: BetaSelfHostedWork) -> None:
print(f"claimed session {work.data.id}")
# Substitua `docker run` pelo seu próprio inicializador de sandbox. Repasse a chave do
# ambiente (nunca sua chave de API) e o segredo por sessão do item de trabalho: o worker
# interno precisa do segredo para montar os memory stores da sessão.
env = os.environ | {
"ANTHROPIC_WORK_ID": work.id,
"ANTHROPIC_SESSION_ID": work.data.id,
"ANTHROPIC_WORK_SECRET": work.secret or "",
}
forward = [arg for name in SANDBOX_ENV for arg in ("-e", name)]
launcher = await asyncio.create_subprocess_exec(
"docker", "run", "--rm", "--detach", *forward, "your-image", env=env
)
await launcher.wait()
async def main() -> None:
environment_key = os.environ["ANTHROPIC_ENVIRONMENT_KEY"]
environment_id = os.environ["ANTHROPIC_ENVIRONMENT_ID"]
async with AsyncAnthropic(auth_token=environment_key) as client:
async for work in client.beta.environments.work.poller(
environment_id=environment_id,
environment_key=environment_key,
auto_stop=False, # the launched sandbox owns the stop call
):
await launch_container(work)
asyncio.run(main())Executar o worker do SDK dentro do sandbox
Substitua o entrypoint ant beta:worker run por um entrypoint do SDK quando o sandbox precisar servir ferramentas personalizadas ou usar configurações de sincronização de memória não padrão. O entrypoint constrói EnvironmentWorker e chama handle_item(), que lê as mesmas variáveis ANTHROPIC_* que o script de spawn encaminha.
import asyncio
import contextlib
import os
import signal
from anthropic import AsyncAnthropic
from anthropic.lib.environments import EnvironmentWorker
async def main() -> None:
async with AsyncAnthropic(
auth_token=os.environ["ANTHROPIC_ENVIRONMENT_KEY"]
) as client:
worker = EnvironmentWorker(client, workdir="/workspace")
# Sem argumentos, handle_item() lê as variáveis ANTHROPIC_* que o script de spawn
# encaminhou, incluindo ANTHROPIC_WORK_SECRET.
task = asyncio.create_task(worker.handle_item())
# Cancelar a tarefa quando o contêiner é parado permite que o worker envie
# os arquivos de memória alterados e remova os diretórios do store antes de encerrar.
loop = asyncio.get_running_loop()
for signum in (signal.SIGINT, signal.SIGTERM):
loop.add_signal_handler(signum, task.cancel)
with contextlib.suppress(asyncio.CancelledError):
await task
asyncio.run(main())Preparar arquivos para uma sessão
A Anthropic não monta arquivos nem repositórios do GitHub em sandboxes auto-hospedados. Para disponibilizar arquivos específicos da sessão:
- Passe referências de arquivos, como um caminho do S3 ou um SHA de commit, no campo
metadatada sessão. - No seu script de spawn ou handler de
--on-work, recupere a sessão (GET /v1/sessions/{session_id}) e leiametadata. O item de trabalho reivindicado contém o ID da sessão, mas não os metadados. - Prepare os arquivos no diretório de trabalho antes que qualquer ferramenta seja executada.
O exemplo em cURL lê um “access token” (token de acesso) de ANTHROPIC_AUTH_TOKEN. Para obter um, configure a Workload Identity Federation com o escopo padrão workspace:developer, conforme descrito em Configurar a federação. Em seguida, troque o token de identidade da sua carga de trabalho por um token de acesso, conforme mostrado em Autenticar a partir da sua carga de trabalho. Defina ANTHROPIC_AUTH_TOKEN apenas no shell em que você executar o exemplo em cURL, porque ele tem precedência sobre suas configurações de federação. Autenticação lista as outras credenciais que a API aceita, como a chave de API do início rápido.
session = client.beta.sessions.create(
agent=agent.id,
environment_id=environment.id,
metadata={"input_file": "s3://my-bucket/data.csv"},
)Próximos passos
Leia a profundidade da fila, pare sessões e workers de forma controlada e corrija falhas comuns.
Esta página foi útil?