Claude Platform Docs
Managed AgentsSandbox self-hosted

Eseguire una sandbox per sessione

Assegna a ogni sessione la propria sandbox self-hosted con il chart Helm su Kubernetes, uno script di avvio o il poller dell’SDK.

Nel modello sandbox per sessione, ogni sessione viene eseguita in una sandbox nuova, che può avere il proprio filesystem, i propri limiti di risorse e i propri controlli di rete. Per confrontarlo con gli altri modelli, consulta Scegli un modello di distribuzione.

Puoi configurarlo in tre modi:

  • Chart Helm su Kubernetes: il dispatcher di Anthropic acquisisce il lavoro e avvia un pod per ogni sessione sul tuo cluster.
  • Script di avvio: la CLI ant acquisisce il lavoro e chiama il tuo script, che avvia una sandbox su qualsiasi piattaforma.
  • Poller dell’SDK: il tuo codice acquisisce il lavoro e avvia la sandbox.

Le sezioni successive a Esegui le sandbox su Kubernetes si applicano allo script di avvio e al poller dell’SDK.

Esegui le sandbox su Kubernetes

Anthropic pubblica un chart Helm, cma-sandboxes, e le relative immagini. Il chart esegue una sandbox per sessione sul tuo cluster Kubernetes. Il suo dispatcher interroga la coda di lavoro dell’ambiente e assegna a ogni sessione un pod dedicato:

  • Isolamento: ogni pod viene eseguito sotto gVisor dietro le network policy del chart. Ha il proprio filesystem e i propri limiti di risorse. Solo il dispatcher detiene la chiave dell’ambiente.
  • Affinità di sessione: ogni messaggio di una sessione va alla sandbox di quella sessione. Dopo che la sessione è rimasta inattiva per 30 minuti (il valore predefinito dell’impostazione sandbox.idleTimeout del chart), il suo pod si arresta. Il suo volume /workspace rimane fino al termine della sessione. Il messaggio successivo avvia un pod sullo stesso volume.
  • Warm pool: tranne che su Google Kubernetes Engine (GKE), il chart mantiene due pod pronti per le nuove sessioni (il valore predefinito dell’impostazione sandbox.warmPoolSize del chart).

I pod delle sandbox eseguono il worker della CLI ant. Supportano i memory store con le impostazioni di sincronizzazione predefinite e non supportano gli strumenti personalizzati.

Installa il chart

Il chart funziona su GKE, Amazon EKS e altri cluster. Prima di installarlo, configura quanto segue:

  • Nel cluster: il controller Agent Sandbox (su GKE, il componente aggiuntivo Agent Sandbox), nodi che eseguono gVisor e un plugin di rete che applica le NetworkPolicy.
  • Nel tuo namespace: le etichette del Pod Security Standard Restricted, un Secret con l’ID dell’ambiente e la chiave dell’ambiente e il certificato TLS del dispatcher.

La guida all’installazione su GitHub contiene i passaggi di configurazione per ogni tipo di cluster. Tratta anche gli aggiornamenti e la rotazione delle chiavi.

Salva le tue impostazioni come cma-values.yaml. L’installazione non riesce senza le tre impostazioni presenti in questo file:

cma-values.yaml
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 address

La guida all’installazione elenca le impostazioni che dipendono dal tuo cluster, come gke.dns su GKE Autopilot. Indica anche quando egress.clusterIsPrivate: true sostituisce egress.clusterCIDRs.

Quindi, installa il 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 \
  --wait

Dopo l’installazione, esegui il controllo preliminare descritto nella guida all’installazione.

Aggiungi strumenti all’immagine della sandbox

L’immagine della sandbox pubblicata è Alpine Linux con bash, curl, jq e la CLI ant. Il chart la esegue con un filesystem radice di sola lettura e come utente non root, quindi un agente non può installare pacchetti durante una sessione.

Per fornire ai tuoi agenti più strumenti, come Python o Git, crea entrambe le immagini dal repository al tag della release. La sezione Install della guida all’installazione contiene i comandi. Carica le immagini nel tuo registry come cma-dispatcher e cma-sandbox, usando la versione del chart come tag. Quindi, imposta image.registry su quel registry. Se fissi i digest delle immagini, usa i digest delle tue immagini.

Limita l’egress di rete

Per impostazione predefinita, le network policy del chart consentono a una sandbox di raggiungere l’internet IPv4 pubblico. Bloccano gli intervalli di indirizzi privati, il server dei metadati del cloud e gli indirizzi in egress.clusterCIDRs. Un agente soggetto a prompt injection può inviare ciò che legge a qualsiasi indirizzo raggiungibile dalla sua sandbox. La sezione Network egress della guida all’installazione contiene i dettagli.

  • GKE con Dataplane V2: imposta egress.mode: fqdnGke per limitare le connessioni alla porta 443 sugli host in egress.fqdnGke.hosts. Mantieni api.anthropic.com in quell’elenco e aggiungi ogni host di cui hanno bisogno i comandi dei tuoi agenti. A differenza dell’impostazione predefinita, questa modalità non ha un elenco di intervalli bloccati. Consente qualsiasi indirizzo a cui si risolve il nome di un host elencato, quindi elenca solo gli host il cui DNS ritieni affidabile. Una sandbox può comunque inviare dati all’esterno all’interno delle query DNS.
  • Altri cluster e GKE senza Dataplane V2: l’impostazione predefinita è l’unica modalità.
  • Ogni cluster: le network policy non coprono le porte su cui sono in ascolto i nodi stessi del cluster. Consulta Node isolation you own nella guida all’installazione.

Avvia le sandbox con uno script di avvio

Un poller sull’host acquisisce il lavoro e chiama il tuo script una volta per ogni elemento di lavoro. Lo script avvia una sandbox per quella singola sessione.

  1. Crea l’immagine della sandbox

    Installa ant e imposta ant beta:worker run come entrypoint. Quando una sandbox si avvia, legge i dettagli della sessione dalle variabili d’ambiente, gestisce quella sessione e termina. L’immagine di base deve fornire /bin/bash; la build usa curl solo per scaricare ant.

    Dockerfile
    FROM 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"]
  2. Scrivi lo script di avvio

    Lo script inoltra i dettagli della sessione a una sandbox nuova. Richiede jq sull’host del poller.

    spawn.sh
    #!/bin/bash
    # spawn.sh: chiamato una volta per ogni elemento di lavoro acquisito
    # L'elemento di lavoro acquisito arriva come JSON su 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-image

    Il poller imposta ANTHROPIC_WORK_ID, ANTHROPIC_ENVIRONMENT_ID, ANTHROPIC_SESSION_ID e ANTHROPIC_ENVIRONMENT_KEY. ANTHROPIC_BASE_URL raggiunge lo script solo se lo imposti sull’host del poller. Lo script legge ANTHROPIC_WORK_SECRET dal JSON dell’elemento di lavoro sullo standard input. Consulta Variabili d’ambiente.

    /host/outputs è una directory dell’host a tua scelta. Montandola in /workspace puoi recuperare i risultati della sessione dopo che la sandbox è terminata. Il mount raccoglie anche l’albero skills/ scaricato e gli eventuali file intermedi.

  3. Avvia il poller

    ant beta:worker poll --on-work ./spawn.sh

Inoltra il segreto dell’elemento di lavoro

Ogni elemento di lavoro acquisito può contenere un secret che Anthropic emette per quella sessione. Il worker che esegue la sessione ne ha bisogno per montare i memory store.

Un worker che acquisisce ed esegue le sessioni in un unico processo passa il segreto da solo. EnvironmentWorker con run() è uno di questi worker, e ant beta:worker poll senza --on-work è un altro. Quando il tuo codice si trova tra l’acquisizione e il worker, sei tu a inoltrare il segreto:

Acquisisci il lavoro conIl segreto arriva comePassalo al worker come
ant beta:worker poll --on-workIl campo secret del JSON dell’elemento di lavoro sullo standard input del tuo scriptANTHROPIC_WORK_SECRET nell’ambiente della sandbox
work.poller() dell’SDK Python, TypeScript o GoIl campo secret di ogni elemento di lavoro acquisitoANTHROPIC_WORK_SECRET nell’ambiente della sandbox oppure l’argomento work_secret di handle_item()

Passa il segreto solo alla sandbox che serve quella sessione e non registrarlo mai nei log. Consulta Modello di sicurezza per scoprire come si rapporta alla chiave dell’ambiente.

Avvia le sandbox dal poller dell’SDK

Per acquisire il lavoro dal tuo codice invece che con ant beta:worker poll --on-work, usa il poller dell’SDK Python, TypeScript o Go: work.poller(). Interroga la coda e ti fornisce ogni sessione acquisita, mentre tu avvii la 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}")
    # Sostituisci `docker run` con il tuo launcher di sandbox. Inoltra la chiave
    # dell'ambiente (mai la tua chiave API) e il segreto per sessione dell'elemento di lavoro: il worker
    # all'interno ha bisogno del segreto per montare i memory store della sessione.
    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())

Esegui il worker dell’SDK all’interno della sandbox

Sostituisci l’entrypoint ant beta:worker run con un entrypoint dell’SDK quando la sandbox deve servire strumenti personalizzati o usare impostazioni di sincronizzazione della memoria non predefinite. L’entrypoint costruisce EnvironmentWorker e chiama handle_item(), che legge le stesse variabili ANTHROPIC_* inoltrate dallo script di avvio.

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")
        # Senza argomenti, handle_item() legge le variabili ANTHROPIC_* che lo script di avvio
        # ha inoltrato, incluso ANTHROPIC_WORK_SECRET.
        task = asyncio.create_task(worker.handle_item())
        # Annullare il task quando il container viene arrestato consente al worker di caricare
        # i file di memoria modificati e rimuovere le directory dello store prima di uscire.
        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())

Prepara i file per una sessione

Anthropic non monta file o repository GitHub nelle sandbox self-hosted. Per rendere disponibili i file specifici della sessione:

  1. Passa i riferimenti ai file, come un percorso S3 o lo SHA di un commit, nel campo metadata della sessione.
  2. Nel tuo script di avvio o nel gestore --on-work, recupera la sessione (GET /v1/sessions/{session_id}) e leggi metadata. L’elemento di lavoro acquisito contiene l’ID della sessione ma non i metadati.
  3. Prepara i file nella directory di lavoro prima che venga eseguito qualsiasi strumento.

L’esempio cURL legge un “access token” (token di accesso) da ANTHROPIC_AUTH_TOKEN. Per ottenerne uno, configura Workload Identity Federation con lo scope predefinito workspace:developer, come descritto in Configura la federazione. Quindi, scambia il token di identità del tuo workload con un token di accesso, come mostrato in Autenticati dal tuo workload. Imposta ANTHROPIC_AUTH_TOKEN solo nella shell in cui esegui l’esempio cURL, perché ha la precedenza sulle tue impostazioni di federazione. Autenticazione elenca le altre credenziali accettate dall’API, come la chiave API della guida rapida.

session = client.beta.sessions.create(
    agent=agent.id,
    environment_id=environment.id,
    metadata={"input_file": "s3://my-bucket/data.csv"},
)

Passaggi successivi

Leggi la profondità della coda, arresta correttamente sessioni e worker e risolvi gli errori più comuni.

Questa pagina ti è stata utile?