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 sandboxes) menjaga 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 lengkap.



Perbedaannya dengan lingkungan cloud

Self-hosting 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 menggabungkan dengan MCP tunnels

Self-hosting mengontrol di mana kode agen dieksekusi. MCP tunnels mengontrol bagaimana Anthropic menjangkau server MCP di jaringan Anda. Keduanya independen: sesi yang berjalan di sandbox cloud Anthropic masih 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. Untuk memberikan agen alat dari server MCP di dalam jaringan Anda tanpa menjalankan tunnel, Anda juga dapat membungkus server sebagai alat kustom yang dilayani oleh worker Anda.



Environment worker

Environment worker adalah proses yang Anda jalankan di infrastruktur Anda sendiri. Worker 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 ke antrean sebagai item kerja. Worker Anda mengklaim item kerja dari antrean tersebut, membuat konteks eksekusi untuk masing-masing item, mengunduh skills agen (sumber daya berbasis filesystem yang dapat digunakan kembali yang memberikan agen keahlian spesifik domain), menjalankan panggilan alat, dan mengirimkan hasilnya kembali.

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.
• Output: pada lingkungan yang di-hosting sendiri, prompt sistem sesi menghilangkan instruksi /mnt/session/outputs yang digunakan pada sandbox yang dikelola Anthropic, sehingga hasil akhir berada di mana pun agen menulisnya di filesystem sandbox Anda, biasanya di bawah direktori kerja.



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 di path yang persis tersebut. Alat bash pada 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 Claude Anda membuat sesi dan membaca statistik antrean dari luar host worker. Pembuatan kunci hanya dapat dilakukan melalui Console.



Jalankan worker

Pilih always-on untuk pengaturan 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 pengaturan 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, pengaturan, dan eksekusi dari awal hingga akhir.
  • .run(): berjalan tanpa batas waktu, mengambil sesi saat tiba.
  • .handle_item(): menangani satu item kerja yang diklaim dan keluar. Berikan pengidentifikasi work, session, dan environment secara eksplisit, atau biarkan ia membaca variabel ANTHROPIC_* yang diatur 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 memutuskan 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 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 dan selalu mengirimkan sinyal stop, jadi blokir di badan loop sampai 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 memulai 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
    # teruskan 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, dan dapat mengunduh skill 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 worker terhubung

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

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

Jika workers_polling tetap di 0, worker tidak menjangkau antrean: konfirmasikan bahwa ANTHROPIC_ENVIRONMENT_KEY dan ANTHROPIC_ENVIRONMENT_ID diatur pada host worker. Lihat Baca kedalaman antrean untuk respons statistik lengkap dan contoh bahasa lainnya.



Mulai 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 sampai worker mengklaimnya; jika tidak ada worker yang terhubung, sesi tetap dalam antrean alih-alih gagal.

Anthropic tidak memasang file atau repositori GitHub ke sandbox yang di-hosting sendiri. Untuk membuat file spesifik sesi tersedia, berikan referensi file (seperti path S3 atau SHA commit) di field metadata sesi. Item kerja yang diklaim tidak membawa metadata sesi, tetapi membawa ID sesi: skrip spawn atau handler --on-work Anda mengambil sesi (GET /v1/sessions/{session_id}) untuk membaca field metadata, kemudian 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.



Layani alat kustom dari sandbox Anda

Alat kustom adalah alat yang dieksekusi oleh kode Anda sendiri: agen memancarkan event agent.custom_tool_use dan menunggu user.custom_tool_result yang cocok. Worker dapat menjadi kode tersebut, dan karena berjalan di dalam sandbox Anda, alat tersebut menjangkau layanan internal, kredensial, dan egress jaringan yang Anda konfigurasikan untuk sandbox, dan tidak lebih. Kunci lingkungan mengotorisasi pengiriman hasil alat kustom, sehingga kunci API Claude Anda tetap tidak berada di host worker.

Worker hanya menjawab alat yang terdaftar padanya. Alat kustom yang dideklarasikan pada agen tetapi tidak terdaftar pada worker atau klien mana pun membuat sesi terjeda dengan alasan berhenti requires_action sampai sesuatu mengirimkan hasilnya; lihat Menangani panggilan alat kustom untuk alur event.



Bungkus server MCP sebagai alat kustom

MCP connector terhubung ke server MCP dari sisi Anthropic, sehingga server harus mengekspos endpoint HTTP yang dapat dijangkau Anthropic, secara langsung atau melalui MCP tunnel. Untuk menggunakan server yang hanya dapat dijangkau oleh jaringan Anda, jadikan worker sebagai klien MCP dan deklarasikan alat server sebagai alat kustom. Server MCP tidak memerlukan konektivitas masuk dari luar jaringan Anda; Anthropic menerima definisi alat yang Anda deklarasikan pada agen, input setiap panggilan, dan hasil yang dikirimkan kembali oleh worker Anda. Saat runtime, model memanggil alat yang dibungkus seperti alat kustom lainnya:

1. Agen memancarkan event agent.custom_tool_use.
2. Worker, di dalam sandbox Anda, meneruskan panggilan melalui sesi MCP yang terbuka ke server di jaringan Anda.
3. Worker mengirimkan respons server sebagai user.custom_tool_result.

Helper MCP sisi klien pada SDK mengonversi alat server menjadi alat yang dapat dijalankan yang diterima worker; instal SDK MCP bersama SDK Anthropic (pip install "anthropic[mcp]" "mcp>=1.24", npm install @modelcontextprotocol/sdk, go get github.com/modelcontextprotocol/go-sdk). Contoh-contoh terhubung tanpa autentikasi; untuk mengirim kredensial, konfigurasikan klien HTTP atau opsi permintaan yang Anda berikan ke transport MCP (http_client di Python, requestInit di TypeScript, HTTPClient di Go).

Perhatikan hal-hal berikut saat Anda membungkus server MCP:

• Alat dideklarasikan, bukan ditemukan saat runtime. Worker mendaftar alat server MCP sekali saat startup dan tidak dapat menambahkan alat ke sesi yang sedang berjalan. Ketika alat server berubah, deklarasikan lagi, pada agen atau pada sesi yang menganggur melalui Memperbarui konfigurasi agen, dan mulai ulang worker.
• Nama dan deskripsi harus sesuai dengan API Managed Agents. Nama alat kustom unik per agen dan menggunakan huruf, angka, garis bawah, dan tanda hubung (1–128 karakter); deskripsi wajib (1–4.096 karakter); dan array tools agen menerima paling banyak 128 entri (setiap alat yang dibungkus adalah satu entri, dan toolset bawaan adalah satu entri lagi). API menolak deklarasi yang menggunakan kembali nama alat, menamai alat kustom dengan nama alat agen bawaan seperti bash atau read, atau menggunakan prefiks mcp__ yang dicadangkan. Helper MCP mempertahankan nama dan deskripsi server, jadi ubah nama atau pangkas jika diperlukan. Ketika dua server mengekspos nama alat yang sama, definisikan wrapper sendiri dengan nama berprefiks dan buat ia memanggil nama alat asli server.
• Sebagian besar skema diteruskan tanpa perubahan. API menerima kata kunci JSON Schema yang umum dipancarkan server MCP, seperti additionalProperties dan title. API menolak kata kunci referensi seperti $ref di mana pun dalam input_schema alat kustom, jadi inline-kan skema yang difaktorkan generator seperti pydantic ke dalam $defs. API juga menolak oneOf, anyOf, dan allOf tingkat atas, serta nama properti di luar huruf, angka, garis bawah, titik, dan tanda hubung (1–64 karakter).
• Kegagalan alat muncul sebagai hasil alat error. Ketika server MCP melaporkan error alat, worker mengirimkan hasil alat error yang dapat direaksikan oleh model. Konten MCP yang tidak memiliki padanan hasil alat, seperti blok audio dan tautan resource, juga muncul sebagai error. Atur timeout pada klien MCP untuk kegagalan yang lebih cepat dan lebih jelas, seperti yang dilakukan contoh worker Python dengan read_timeout_seconds. Tanpa itu, panggilan yang menggantung menjadi hasil error hanya ketika timeout permintaan default SDK MCP TypeScript terpicu (sekitar satu menit) atau ketika backstop worker sendiri terpicu: sekitar dua setengah menit di Python, dan dua menit di Go, di mana worker membatalkan panggilan alat yang melebihi default 120 detiknya dan mengirimkan hasil error.
• Bungkus server yang Anda operasikan atau percayai. Nama, deskripsi, dan hasil alat yang dibungkus masuk ke konteks model seperti alat lainnya: input yang tidak tepercaya yang dapat memengaruhi apa yang dilakukan agen dengan alat lainnya, termasuk bash pada host worker. Deklarasikan hanya alat yang Anda maksudkan untuk digunakan agen.
• Kebijakan izin tidak berlaku untuk alat kustom. Kebijakan izin mengatur toolset bawaan dan MCP; worker mengeksekusi setiap panggilan alat yang dibungkus yang dibuat model, jadi letakkan langkah persetujuan apa pun di kode alat Anda sendiri.



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, jadi Anda tidak memanggil endpoint tersebut secara langsung.



Baca 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 pada backlog berdasarkan nilai ini.
• pending adalah jumlah item yang diklaim oleh worker tetapi belum di-acknowledge. Helper worker meng-acknowledge setiap item sebelum memprosesnya, sehingga nilai ini tetap mendekati nol dalam operasi normal; nilai non-nol yang berkelanjutan berarti worker terhenti antara mengklaim dan meng-acknowledge.
• oldest_queued_at adalah timestamp item tertua yang masih berada di antrean, menunggu untuk diklaim atau sudah diklaim tetapi belum di-acknowledge, atau null ketika 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 secara halus

Gunakan work.stop untuk meminta worker yang menangani sesi tertentu agar mematikannya. Secara default, work item berpindah ke stopping: worker menyadarinya pada lease heartbeat berikutnya, membatalkan panggilan alat sesi yang sedang berjalan, dan mengonfirmasi penghentian, pada saat itu work item menjadi stopped. Berikan force: true dalam body permintaan (dengan CLI, gunakan --force) untuk menandai work item sebagai stopped segera alih-alih menunggu konfirmasi dari worker.

Karena panggilan ini dijalankan dari perangkat operasional Anda dan bukan dari host worker, ANTHROPIC_WORK_ID tidak diatur secara otomatis. Atur nilainya ke ID work item target sebelum menjalankan contoh-contoh berikut. Untuk menemukan ID sebuah work item, daftarkan work item environment 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