Sandbox yang di-hosting sendiri

Secara default, Managed Agents mengeksekusi alat dan kode di dalam sandbox cloud yang dikelola Anthropic. Sandbox yang di-hosting sendiri (self-hosted sandbox) mempertahankan orkestrasi di sisi Anthropic tetapi memindahkan eksekusi alat ke infrastruktur yang Anda kendalikan, sehingga kode agen, filesystem, dan egress jaringan tidak pernah meninggalkan lingkungan Anda.

Eksekusi alat tetap berada di host Anda: filesystem yang dibaca dan ditulis oleh agen, proses yang dijalankannya, dan jaringan yang dapat dijangkaunya semuanya berada di bawah kendali Anda. Input dan output alat tetap mengalir ke control plane Anthropic (tempat Claude berjalan) sehingga model dapat melihat hasil dan menentukan apa yang harus dilakukan selanjutnya. Lihat model keamanan untuk batas aliran data selengkapnya.



Perbedaannya dengan lingkungan cloud

Hosting sendiri cocok ketika agen perlu beroperasi pada data yang tidak boleh meninggalkan batas jaringan Anda, menjangkau layanan internal yang tidak dapat dirutekan secara publik, atau berjalan di bawah kontrol kepatuhan dan audit organisasi Anda sendiri.

Untuk kelayakan Zero Data Retention dan HIPAA BAA, lihat API dan retensi data.



Kapan menggabungkannya dengan MCP tunnel

Hosting sendiri mengontrol di mana kode agen dieksekusi. MCP tunnel mengontrol bagaimana Anthropic menjangkau server MCP di jaringan Anda. Keduanya independen: sesi yang berjalan di sandbox cloud Anthropic tetap dapat menjangkau server MCP privat melalui tunnel, dan sesi yang di-hosting sendiri dapat menggunakan server MCP yang di-tunnel maupun yang publik. Gunakan keduanya ketika Anda ingin eksekusi dan akses alat tetap berada di dalam batas Anda.



Environment worker

"Environment worker" (pekerja lingkungan) adalah proses yang Anda jalankan di infrastruktur Anda sendiri. Proses ini menerima permintaan eksekusi alat dari Anthropic dan menjalankannya secara lokal. Lingkungan self_hosted bertindak sebagai antrean kerja: ketika sebuah sesi ditugaskan ke lingkungan tersebut, Anthropic memasukkan sesi itu ke antrean sebagai item kerja. Worker Anda mengklaim item kerja dari antrean tersebut, membuat konteks eksekusi untuk masing-masing item, mengunduh skills milik agen (sumber daya berbasis filesystem yang dapat digunakan kembali dan memberi agen keahlian spesifik domain), menjalankan panggilan alat, dan mengirimkan kembali hasilnya.

Item kerja diklaim dengan melakukan polling pada antrean lingkungan: baik oleh worker yang selalu aktif (always-on) yang melakukan polling secara terus-menerus, atau handler yang dipicu webhook yang bangun saat session.status_run_started dan mulai melakukan polling.

CLI dan SDK keduanya menyertakan worker yang sudah jadi. CLI ant hanya mendukung pola always-on; SDK mendukung baik always-on maupun yang dipicu webhook. Keduanya dapat dikonfigurasi: lihat Self-hosted worker di referensi untuk flag CLI, dan SDK helpers di halaman ini untuk opsi SDK. Untuk kontrol lebih, panggil endpoint Environments Work secara langsung dan implementasikan worker Anda sendiri.



Filesystem sandbox

• /workspace: direktori kerja default sistem untuk eksekusi alat dan pengunduhan skill. Flag --workdir pada CLI secara default menggunakan direktori saat ini; berikan --workdir /workspace agar sesuai dengan default sistem. Skill diunduh ke <workdir>/skills/<name>/. Jika Anda menggunakan direktori kerja yang berbeda, perbarui prompt sistem agen Anda agar Claude dapat menemukan file skill tersebut.
• /mnt/session/outputs: harness worker menginstruksikan Claude untuk menulis hasil akhir di sini. Dalam mode sandbox, pasang (mount) direktori host pada path ini untuk mengambil output setelah sesi berakhir. Dalam mode in-process, alat file milik worker menulis di bawah direktori kerja, sehingga path ini tidak berlaku.



Sebelum Anda mulai

Anda memerlukan:

• Agen yang sudah ada. Jika Anda belum memilikinya, selesaikan Quickstart terlebih dahulu dan catat ID agennya.
• Host Linux dengan /bin/bash pada path persis tersebut. Alat bash milik worker memanggilnya secara langsung, tanpa memeriksa PATH. SDK TypeScript juga memerlukan unzip dan tar pada PATH serta Node.js 22 atau yang lebih baru; SDK Python dan Go menggunakan pustaka standar mereka untuk ekstraksi arsip dan tidak memiliki persyaratan biner tambahan.
• CLI ant atau SDK Anthropic (Python, TypeScript, atau Go) pada host worker.
• Dua kredensial: kunci lingkungan (dibuat di Console pada langkah-langkah berikut) mengautentikasi worker ke antreannya; kunci API (API key) Claude Anda membuat sesi dan membaca statistik antrean dari luar host worker. Pembuatan kunci hanya dapat dilakukan melalui Console.



Menjalankan worker

Pilih always-on untuk penyiapan paling sederhana: proses yang berjalan lama melakukan polling antrean secara terus-menerus dan hanya memerlukan HTTPS keluar. Pilih dipicu webhook untuk menghindari menjalankan poller yang menganggur; ini memerlukan endpoint webhook yang dapat dijangkau Anthropic (lihat Webhooks untuk penyiapan endpoint dan verifikasi tanda tangan).



SDK helpers

SDK menyediakan tiga helper pada tingkat kontrol yang berbeda. EnvironmentWorker mencakup sebagian besar kasus penggunaan; turun ke helper tingkat lebih rendah ketika Anda perlu meluncurkan proses per sesi Anda sendiri atau menjalankan alat terhadap sesi yang sudah diklaim.

• EnvironmentWorker: worker siap pakai. Menangani polling, penyiapan, dan eksekusi dari awal hingga akhir.
  • .run(): berjalan tanpa batas waktu, mengambil sesi saat sesi tersebut tiba.
  • .handle_item(): menangani satu item kerja yang telah diklaim lalu keluar. Berikan pengidentifikasi work, session, dan environment secara eksplisit, atau biarkan ia membaca variabel ANTHROPIC_* yang diatur oleh ant beta:worker poll --on-work untuk proses yang dijalankannya.
• work.poller(): melakukan polling antrean kerja atas nama Anda dan memberikan setiap sesi yang diklaim. Gunakan ini ketika Anda ingin menentukan apa yang terjadi untuk setiap sesi, misalnya meluncurkan sandbox alih-alih menjalankan alat secara in-process.
  • drain: apakah berhenti melakukan polling setelah antrean kosong alih-alih menunggu pekerjaan baru.
  • block_ms: berapa lama menunggu pekerjaan tiba sebelum kembali, dalam milidetik. Harus antara 1 dan 999 (waktu tunggu per polling; helper melakukan polling ulang secara otomatis). Berikan null (None di Python, param.Null[int64]() di Go) untuk pemeriksaan non-blocking; menghilangkan parameter ini menggunakan long-poll default 999 ms.
  • reclaim_older_than_ms: mengklaim ulang item kerja yang telah diklaim tetapi tidak pernah di-acknowledge dalam jumlah milidetik ini.
  • auto_stop: apakah mengirimkan sinyal stop untuk setiap item kerja setelah badan loop Anda selesai dengannya. Poller Go tidak memiliki opsi untuk menonaktifkan ini dan selalu mengirimkan sinyal stop, jadi blokir di badan loop hingga sesi selesai alih-alih melepaskannya.
• client.beta.sessions.events.tool_runner(): menjalankan panggilan alat untuk satu sesi, dengan ID sesi dan daftar alat. Gunakan ketika Anda sudah mengklaim pekerjaan dan hanya memerlukan lapisan eksekusi.

Gunakan work poller secara langsung ketika Anda ingin meluncurkan proses per sesi Anda sendiri, misalnya menjalankan sandbox untuk setiap sesi yang diklaim:

import asyncio
import os

from anthropic import AsyncAnthropic
from anthropic.types.beta.environments import BetaSelfHostedWork


async def launch_container(work: BetaSelfHostedWork) -> None:
    # Ganti dengan peluncur sandbox per-sesi Anda sendiri. Teruskan
    # ANTHROPIC_ENVIRONMENT_KEY ke dalam sandbox yang diluncurkan, jangan pernah
    # kunci API Anda.
    print(f"claimed session {work.data.id}")


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())

AgentToolContext adalah konteks eksekusi untuk panggilan alat. Ia mendefinisikan direktori kerja dan kebijakan path, serta dapat mengunduh skill milik sesi. beta_agent_toolset_20260401(env) menerima AgentToolContext dan mengembalikan implementasi alat standar (bash, read, write, edit, glob, grep).

Dengan EnvironmentWorker: keduanya dikelola secara otomatis. Berikan factory tools untuk menyesuaikan daftar alat:

EnvironmentWorker(client, ..., tools=lambda env: [beta_bash_tool(env), my_custom_tool])

Dengan work.poller() dan tool_runner(): berikan daftar alat sebagai tools ke client.beta.sessions.events.tool_runner(). Untuk membangun daftar tersebut, siapkan AgentToolContext sendiri dan panggil beta_agent_toolset_20260401(env):

from anthropic.lib.tools.agent_toolset import (
    AgentToolContext,
    beta_agent_toolset_20260401,
)

async with AgentToolContext(
    workdir="/workspace", client=client, session_id=work.data.id
) as env:
    # skills diunduh ke /workspace/skills/<name>/
    tools = beta_agent_toolset_20260401(env)



Verifikasi bahwa worker terhubung

Dari shell terpisah, dengan ANTHROPIC_API_KEY diatur ke kunci API Claude Anda (bukan kunci lingkungan), pastikan workers_polling setidaknya bernilai 1:

ant beta:environments:work stats --environment-id "$ANTHROPIC_ENVIRONMENT_ID"

Jika workers_polling tetap 0, worker tidak menjangkau antrean: pastikan ANTHROPIC_ENVIRONMENT_KEY dan ANTHROPIC_ENVIRONMENT_ID telah diatur pada host worker. Lihat Membaca kedalaman antrean untuk respons statistik lengkap dan contoh bahasa lainnya.



Memulai sesi

Setelah worker Anda berjalan, buat sesi yang menargetkan lingkungan tersebut. Atur AGENT_ID ke ID agen yang Anda catat di Sebelum Anda mulai. Sesi masuk ke antrean kerja lingkungan dan menunggu di sana hingga worker mengklaimnya; jika tidak ada worker yang terhubung, sesi tetap berada dalam antrean alih-alih gagal.

Anthropic tidak memasang file atau repositori GitHub ke dalam sandbox yang di-hosting sendiri. Untuk membuat file spesifik sesi tersedia, berikan referensi file (seperti path S3 atau SHA commit) di field metadata sesi. Skrip spawn atau handler --on-work Anda membaca metadata tersebut dari item kerja yang diklaim (poller CLI menyalurkan JSON item kerja ke stdin skrip, dan handler SDK dapat membacanya melalui endpoint Environments Work) dan menyiapkan file ke direktori kerja sebelum eksekusi alat dimulai.

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

Lihat Self-hosted worker di referensi untuk daftar lengkap flag CLI, dan SDK helpers untuk opsi helper SDK.



Pemantauan dan operasi

Panggilan-panggilan ini dijalankan dari perangkat pemantauan atau operasi Anda, diautentikasi dengan kunci API Claude Anda, untuk mengamati dan mengelola armada worker. Loop klaim dan keep-alive ditangani di dalam helper worker, sehingga Anda tidak memanggil endpoint tersebut secara langsung.



Membaca kedalaman antrean

work.stats mengembalikan status antrean untuk sebuah lingkungan:

• depth adalah jumlah item yang menunggu untuk diklaim. Skalakan armada worker Anda atau buat peringatan berdasarkan backlog menggunakan nilai ini.
• pending adalah jumlah item yang telah diklaim oleh worker dan sedang diproses.
• oldest_queued_at adalah timestamp item tertua yang masih dalam antrean atau sedang diproses, atau null jika tidak ada.
• workers_polling adalah jumlah worker yang telah melakukan polling dalam 30 detik terakhir. Gunakan ini untuk peringatan liveness.

import os

import anthropic

client = anthropic.Anthropic()

stats = client.beta.environments.work.stats(os.environ["ANTHROPIC_ENVIRONMENT_ID"])
print(f"depth={stats.depth} pending={stats.pending}")

{
  "type": "work_queue_stats",
  "depth": 0,
  "pending": 0,
  "oldest_queued_at": null,
  "workers_polling": 0
}



Menghentikan sesi dengan baik

Gunakan work.stop untuk meminta worker yang menangani sesi tertentu agar mematikannya dengan bersih. Worker menyelesaikan panggilan alat yang sedang berjalan, mengirimkan status akhir, dan melepaskan sesi. Berikan force: true di body permintaan (dengan CLI, berikan --force) untuk menginterupsi segera alih-alih menunggu panggilan alat saat ini selesai.

Karena panggilan ini dijalankan dari perangkat operasi Anda dan bukan dari host worker, ANTHROPIC_WORK_ID tidak diatur secara otomatis. Atur variabel ini ke ID item kerja target sebelum menjalankan contoh berikut. Untuk menemukan ID item kerja, daftarkan item kerja lingkungan melalui endpoint Environments Work.

import os

import anthropic

client = anthropic.Anthropic()

work = client.beta.environments.work.stop(
    os.environ["ANTHROPIC_WORK_ID"],
    environment_id=os.environ["ANTHROPIC_ENVIRONMENT_ID"],
)
print(work.state)



Langkah selanjutnya