Claude Platform Docs
Managed AgentsSandbox yang di-host sendiri

Menjalankan satu sandbox per sesi

Berikan setiap sesi sandbox self-hosted miliknya sendiri dengan Helm chart di Kubernetes, skrip spawn, atau poller SDK.

Dalam pola sandbox-per-sesi, setiap sesi berjalan di sandbox baru, yang dapat memiliki sistem file, batas sumber daya, dan kontrol jaringannya sendiri. Untuk membandingkannya dengan pola lain, lihat Pilih pola deployment.

Anda dapat menyiapkannya dengan tiga cara:

  • Helm chart di Kubernetes: Dispatcher Anthropic mengklaim pekerjaan dan memulai pod untuk setiap sesi di cluster Anda.
  • Skrip spawn: CLI ant mengklaim pekerjaan dan memanggil skrip Anda, yang meluncurkan sandbox di platform apa pun.
  • Poller SDK: Kode Anda sendiri mengklaim pekerjaan dan meluncurkan sandbox.

Bagian-bagian setelah Menjalankan sandbox di Kubernetes berlaku untuk skrip spawn dan poller SDK.

Menjalankan sandbox di Kubernetes

Anthropic menerbitkan Helm chart, cma-sandboxes, beserta image-nya. Chart ini menjalankan satu sandbox per sesi di cluster Kubernetes Anda sendiri. Dispatcher-nya melakukan polling pada antrean pekerjaan environment dan memberikan setiap sesi pod miliknya sendiri:

  • Isolasi: Setiap pod berjalan di bawah gVisor di balik network policy chart. Pod memiliki sistem file dan batas sumber dayanya sendiri. Hanya dispatcher yang memegang kunci environment.
  • Afinitas sesi: Setiap pesan dalam sebuah sesi masuk ke sandbox sesi tersebut. Setelah sesi idle selama 30 menit (nilai default dari pengaturan sandbox.idleTimeout chart), pod-nya berhenti. Volume /workspace-nya tetap ada hingga sesi berakhir. Pesan berikutnya memulai pod pada volume yang sama.
  • Warm pool: Kecuali di Google Kubernetes Engine (GKE), chart ini menyiapkan dua pod yang siap untuk sesi baru (nilai default dari pengaturan sandbox.warmPoolSize chart).

Pod sandbox menjalankan worker CLI ant. Pod ini mendukung memory store dengan pengaturan sinkronisasi default, dan tidak mendukung alat kustom.

Menginstal chart

Chart ini berjalan di GKE, Amazon EKS, dan cluster lainnya. Siapkan hal-hal berikut sebelum Anda menginstalnya:

  • Di cluster: Controller Agent Sandbox (di GKE, add-on Agent Sandbox), node yang menjalankan gVisor, dan plugin jaringan yang menerapkan NetworkPolicy.
  • Di namespace Anda sendiri: Label Pod Security Standard Restricted, Secret berisi ID environment dan kunci environment, serta sertifikat TLS dispatcher.

Panduan instalasi di GitHub berisi langkah-langkah penyiapan untuk setiap jenis cluster. Panduan ini juga membahas upgrade dan rotasi kunci.

Simpan pengaturan Anda sebagai cma-values.yaml. Instalasi akan gagal tanpa tiga pengaturan dalam file ini:

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

Panduan instalasi mencantumkan pengaturan yang bergantung pada cluster Anda, seperti gke.dns di GKE Autopilot. Panduan ini juga menjelaskan kapan egress.clusterIsPrivate: true menggantikan egress.clusterCIDRs.

Kemudian, instal 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

Setelah instalasi, jalankan pemeriksaan preflight yang dijelaskan dalam panduan instalasi.

Menambahkan alat ke image sandbox

Image sandbox yang diterbitkan adalah Alpine Linux dengan bash, curl, jq, dan CLI ant. Chart menjalankannya dengan sistem file root read-only dan sebagai pengguna non-root, sehingga agen tidak dapat menginstal paket selama sesi.

Untuk memberikan lebih banyak alat kepada agen Anda, seperti Python atau Git, build kedua image dari repositori pada tag rilis. Bagian Install dalam panduan instalasi berisi perintah-perintahnya. Push image ke registry Anda sebagai cma-dispatcher dan cma-sandbox, dengan versi chart sebagai tag. Kemudian, atur image.registry ke registry tersebut. Jika Anda mem-pin digest image, gunakan digest dari image Anda sendiri.

Membatasi egress jaringan

Secara default, network policy chart memungkinkan sandbox menjangkau internet IPv4 publik. Policy ini memblokir rentang alamat privat, server metadata cloud, dan alamat dalam egress.clusterCIDRs. Agen yang terkena prompt injection dapat mengirimkan apa yang dibacanya ke alamat mana pun yang dapat dijangkau sandbox-nya. Network egress dalam panduan instalasi berisi detailnya.

  • GKE dengan Dataplane V2: Atur egress.mode: fqdnGke untuk membatasi koneksi ke port 443 pada host dalam egress.fqdnGke.hosts. Pertahankan api.anthropic.com dalam daftar tersebut, dan tambahkan setiap host yang dibutuhkan oleh perintah agen Anda. Tidak seperti default, mode ini tidak memiliki daftar rentang yang diblokir. Mode ini mengizinkan alamat apa pun yang di-resolve dari nama host yang tercantum, jadi cantumkan hanya host yang DNS-nya Anda percayai. Sandbox masih dapat mengirimkan data keluar di dalam lookup DNS.
  • Cluster lain dan GKE tanpa Dataplane V2: Default adalah satu-satunya mode.
  • Setiap cluster: Network policy tidak mencakup port yang didengarkan oleh node milik cluster itu sendiri. Lihat Node isolation you own dalam panduan instalasi.

Meluncurkan sandbox dengan skrip spawn

Poller di host mengklaim pekerjaan dan memanggil skrip Anda sekali untuk setiap item pekerjaan. Skrip tersebut meluncurkan sandbox untuk satu sesi itu.

  1. Build image sandbox

    Instal ant dan atur ant beta:worker run sebagai entrypoint. Saat sandbox dimulai, sandbox membaca detail sesi dari variabel lingkungan, menangani sesi tersebut, lalu keluar. Image dasar harus menyediakan /bin/bash; proses build menggunakan curl hanya untuk mengunduh 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. Tulis skrip spawn

    Skrip ini meneruskan detail sesi ke sandbox baru. Skrip ini memerlukan jq di host poller.

    spawn.sh
    #!/bin/bash
    # spawn.sh: dipanggil sekali untuk setiap item pekerjaan yang diklaim
    # Item pekerjaan yang diklaim diterima sebagai JSON melalui 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

    Poller mengatur ANTHROPIC_WORK_ID, ANTHROPIC_ENVIRONMENT_ID, ANTHROPIC_SESSION_ID, dan ANTHROPIC_ENVIRONMENT_KEY. ANTHROPIC_BASE_URL hanya sampai ke skrip jika Anda mengaturnya di host poller. Skrip membaca ANTHROPIC_WORK_SECRET dari JSON item pekerjaan pada standard input. Lihat Variabel lingkungan.

    /host/outputs adalah direktori host yang Anda pilih. Me-mount-nya di /workspace memungkinkan Anda mengambil hasil kerja sesi setelah sandbox keluar. Mount ini juga menyertakan tree skills/ yang diunduh dan file-file perantara apa pun.

  3. Mulai poller

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

Meneruskan secret item pekerjaan

Setiap item pekerjaan yang diklaim dapat membawa secret yang diterbitkan oleh Anthropic untuk sesi tersebut. Worker yang menjalankan sesi memerlukannya untuk me-mount memory store.

Worker yang mengklaim dan menjalankan sesi dalam satu proses meneruskan secret tersebut dengan sendirinya. EnvironmentWorker dengan run() adalah salah satu worker tersebut, dan ant beta:worker poll tanpa --on-work adalah yang lainnya. Ketika kode Anda sendiri berada di antara klaim dan worker, Anda yang meneruskan secret:

Anda mengklaim pekerjaan denganSecret tiba sebagaiTeruskan ke worker sebagai
ant beta:worker poll --on-workField secret dari JSON item pekerjaan pada standard input skrip AndaANTHROPIC_WORK_SECRET di environment sandbox
work.poller() dari SDK Python, TypeScript, atau GoField secret dari setiap item pekerjaan yang diklaimANTHROPIC_WORK_SECRET di environment sandbox atau argumen work_secret untuk handle_item()

Teruskan secret hanya ke sandbox yang melayani sesi tersebut, dan jangan pernah mencatatnya ke log. Lihat Model keamanan untuk mengetahui hubungannya dengan kunci environment.

Meluncurkan sandbox dari poller SDK

Untuk mengklaim pekerjaan dari kode Anda sendiri alih-alih ant beta:worker poll --on-work, gunakan poller di SDK Python, TypeScript, atau Go: work.poller(). Poller ini melakukan polling pada antrean dan memberikan setiap sesi yang diklaim kepada Anda, lalu Anda meluncurkan 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}")
    # Ganti `docker run` dengan peluncur sandbox Anda sendiri. Teruskan kunci
    # environment (jangan pernah kunci API Anda) dan secret per sesi milik item pekerjaan: worker
    # di dalamnya memerlukan secret tersebut untuk me-mount memory store sesi.
    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())

Menjalankan worker SDK di dalam sandbox

Ganti entrypoint ant beta:worker run dengan entrypoint SDK ketika sandbox harus melayani alat kustom atau menggunakan pengaturan sinkronisasi memori non-default. Entrypoint ini membuat EnvironmentWorker dan memanggil handle_item(), yang membaca variabel ANTHROPIC_* yang sama dengan yang diteruskan oleh skrip spawn.

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")
        # Tanpa argumen, handle_item() membaca variabel ANTHROPIC_* yang diteruskan
        # oleh skrip spawn, termasuk ANTHROPIC_WORK_SECRET.
        task = asyncio.create_task(worker.handle_item())
        # Membatalkan task saat container dihentikan memungkinkan worker mengunggah
        # file memori yang berubah dan menghapus direktori store sebelum keluar.
        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())

Menyiapkan file untuk sesi

Anthropic tidak me-mount file atau repositori GitHub ke dalam sandbox self-hosted. Untuk menyediakan file khusus sesi:

  1. Teruskan referensi file, seperti path S3 atau SHA commit, di field metadata sesi.
  2. Di skrip spawn atau handler --on-work Anda, ambil sesi (GET /v1/sessions/{session_id}) dan baca metadata. Item pekerjaan yang diklaim membawa ID sesi tetapi tidak membawa metadata.
  3. Tempatkan file ke direktori kerja sebelum alat apa pun berjalan.

Contoh cURL membaca token akses dari ANTHROPIC_AUTH_TOKEN. Untuk mendapatkannya, siapkan Workload Identity Federation dengan scope default workspace:developer, seperti yang dijelaskan di Menyiapkan federasi. Kemudian, tukarkan token identitas workload Anda dengan token akses, seperti yang ditunjukkan di Autentikasi dari workload Anda. Atur ANTHROPIC_AUTH_TOKEN hanya di shell tempat Anda menjalankan contoh cURL, karena variabel ini lebih diutamakan daripada pengaturan federasi Anda. Autentikasi mencantumkan kredensial lain yang diterima API, seperti kunci API dari quickstart.

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

Langkah selanjutnya

Baca kedalaman antrean, hentikan sesi dan worker dengan bersih, serta perbaiki kegagalan umum.

Apakah halaman ini membantu?