Cara Menjalankan Agen AI di Sandbox: File, Jaringan, Kredensial
Cara menjalankan agen AI di sandbox dari nol: apa yang dikurung sandbox dan yang tidak, dari file, jaringan, sampai kredensial, di Claude Code dan Docker.
Oleh Matthews WongDitinjau pada Dicek dengan MCP specification 2026-07-28
Poin utama
Sandbox adalah batas yang ditegakkan sistem operasi atau virtual machine di sekeliling agen AI, sehingga tetap bertahan apa pun keputusan model. Periksa tiga pintunya: file apa yang bisa ditulis dan dibaca, host mana yang bisa dijangkau, dan kredensial apa yang ada di dalamnya. Lalu periksa apa yang berjalan di luarnya, karena sandbox Claude Code hanya membungkus perintah shell.
Setelah pelajaran ini, Anda bisa
- Menjelaskan sandbox lewat tiga pintunya, yaitu file, jaringan, dan kredensial, serta tahu default sandbox Claude Code.
- Menyebut apa yang berjalan di luar sandbox, dan memilih batas yang lebih luas saat hal itu penting.
- Membuktikan sandbox bekerja dengan dua uji coba, bukan sekadar memercayai setelannya.
Ikuti diagramnya langkah demi langkah
Tekan Putar, atau melangkah dengan panah. Setiap langkah juga ditulis di bawah diagram.
Tiga pintu sandbox untuk agen
Perintah shell di sandbox hanya boleh menulis ke proyek, bisa membaca sebagian besar file sampai Anda menolaknya, hanya menjangkau jaringan lewat proxy allowlist, sementara MCP server milik agen berjalan di luar batas.
Ditinjau pada 17 Oktober 2026 · MCP specification 2026-07-28
Tombol: ← → langkah · Home / End · K putar atau jeda
Sandbox Claude Code membungkus perintah shell yang dijalankan agen beserta proses turunannya. Agennya sendiri, tool file-nya, dan MCP server lokal berada di luar garis.
Secara default, perintah di sandbox boleh menulis ke folder proyek, direktori temp per user, dan folder yang Anda tambahkan. Penulisan di tempat lain, misalnya direktori home, gagal.
touch ~/sandbox-probe → Operation not permittedTebak langkah berikutnya Bisakah perintah sandbox yang sama membaca ~/.ssh secara default? (Tidak, pembacaan juga dikurung · Ya, pembacaan terbuka sampai Anda menolaknya)Pembacaan tidak dikurung secara default: perintah di sandbox bisa membaca sebagian besar isi mesin, termasuk ~/.ssh dan file kredensial cloud, dan mewarisi environment variable Anda.
cat ~/.ssh/known_hosts → worksDaftarkan file kredensial dan environment variable di sandbox.credentials. File yang ditolak tidak bisa dibaca di dalam sandbox, dan variabel yang ditolak dihapus sebelum setiap perintah berjalan.
credentials · files: ~/.ssh mode deny · envVars: GITHUB_TOKEN mode denyLalu lintas jaringan harus lewat proxy yang mencocokkan setiap host dengan allowed domains Anda, yang awalnya kosong. Perintah yang mencoba melewati proxy tidak bisa me-resolve apa pun.
curl --noproxy '*' https://example.com → Could not resolve hostTebak langkah berikutnya MCP server lokal milik agen butuh jaringan. Apakah sandbox ini membatasinya? (Ya, ia berbagi sandbox yang sama · Tidak, ia berjalan di luarnya)Tool file, hooks, dan MCP server lokal berjalan dengan akses penuh Anda, di luar sandbox shell. Untuk ikut mengurungnya, jalankan seluruh agen di container, VM, atau microVM.
sandbox runtime · dev container · VM or microVM
Apa yang dikurung sandbox, dan apa yang tidak?
Sandbox adalah batas yang ditegakkan di luar model, oleh sistem operasi atau virtual machine, di sekeliling apa yang bisa disentuh agen. Ini penting karena sandbox tetap bertahan apa pun keputusan model: dokumentasi Claude Code menyatakan batasan sandbox tetap berlaku walaupun prompt injection berhasil mengakali keputusan Claude. Jelaskan sandbox apa pun lewat tiga pintunya: file, jaringan, dan kredensial.
Baca selengkapnya (2)Tutup
Sandbox bawaan Claude Code, yang mati secara default dan dinyalakan dengan /sandbox, menunjukkan betapa spesifiknya pintu-pintu itu. Penulisan diarahkan ke direktori kerja, direktori temp per user, dan folder yang Anda tambahkan. Pembacaan mencakup sebagian besar isi mesin, termasuk ~/.ssh dan ~/.aws/credentials. Lalu lintas jaringan lewat proxy lokal yang allowed domains-nya awalnya kosong. Environment variable, termasuk rahasia, ikut diwariskan.
Jadi default-nya mencegah perintah menulis di luar proyek atau menghubungi server luar, tetapi tidak mencegahnya membaca kunci Anda. Dokumentasi menyatakan tidak ada daftar penolakan kredensial bawaan: hanya file dan variabel yang Anda daftarkan di sandbox.credentials yang dilindungi, dengan memblokir pembacaan file itu dan menghapus variabel itu sebelum setiap perintah di sandbox berjalan.
Apa saja yang berjalan di luar sandbox?
Sandbox Claude Code membungkus perintah shell dan proses yang dijalankannya, tidak lebih. Tool file-nya, seperti Read, Edit, dan Write, mengikuti aturan izin; hooks, MCP server lokal, plugin monitor, dan helper seperti status line berjalan dengan akses penuh Anda. Entri denyRead tidak menghentikan tool Read.
Baca selengkapnya (2)Tutup
Sebagian perintah shell juga keluar dari sandbox. Perintah yang Anda ketik di prompt ! biasanya berjalan tanpa sandbox, perintah yang cocok dengan excludedCommands berjalan di luarnya, dan Claude bisa meminta mengulang perintah yang gagal tanpa sandbox. Mengatur allowUnsandboxedCommands ke false menghapus opsi ulang itu, dan failIfUnavailable membuat Claude Code berhenti alih-alih menjalankan perintah tanpa sandbox saat sandbox tidak bisa dimulai.
Sandbox lain menarik garis yang sama di tempat berbeda. Halaman keamanan Docker menyatakan MCP server lokal berjalan di host, di luar isolasi sandbox, dan harus diperlakukan sebagai integrasi host yang tepercaya. Sandbox apa pun yang Anda pakai, tanyakan apa yang ada di luarnya, karena ke sanalah instruksi yang disisipkan akan mencoba pergi.
Kapan Anda butuh batas yang lebih besar?
Saat agen berjalan tanpa pengawasan atau menyentuh kode yang tidak tepercaya, masukkan seluruh agen ke dalam batas, bukan hanya shell-nya. Dokumentasi Claude Code menyatakan sandbox bawaan saja tidak cukup untuk run yang sepenuhnya tanpa pengawasan, menyebut sandbox runtime, dev container, custom container, dan virtual machine sebagai opsi yang lebih luas, dan menyarankan VM khusus untuk repositori yang tidak tepercaya.
Baca selengkapnya (3)Tutup
Docker Sandboxes menjalankan setiap agen di microVM dengan kernel sendiri dan Docker engine sendiri, menolak TCP keluar secara default, dan menyuntikkan API key dari proxy di sisi host sehingga nilai aslinya tidak pernah masuk ke VM. Yang tidak dilindunginya adalah workspace yang Anda bagikan: mount langsung bersifat read-write, jadi agen mengedit working tree Anda di tempat, termasuk git hooks dan konfigurasi CI.
Di Kubernetes, proyek agent-sandbox mengelola satu pod stateful per sandbox, tetapi threat model-nya menyatakan proyek itu tidak mengimplementasikan isolasi sendiri. Ia bergantung pada runtime seperti gVisor atau Kata Containers yang dipilih lewat RuntimeClass, NetworkPolicy default-deny, dan token service account yang tidak di-mount secara default saat memakai SandboxTemplate.
Apa pun batasnya, host yang diizinkan adalah pemberian kemampuan, bukan sekadar tujuan. Anthropic menceritakan kasus ketika instruksi tersembunyi di sebuah file workspace membuat Claude mengunggah file lewat host API yang diizinkan ke akun milik penyerang. Untuk setiap host yang Anda izinkan, tanyakan apa yang bisa dilakukan proses jahat dengan akunnya sendiri di host itu.
Konfigurasi nyata di balik pelajaran ini
Kutipan dari repositori yang membangun dan men-deploy situs ini, apa adanya.
"sandbox": {
"enabled": true,
"credentials": {
"files": [
{ "path": "~/.aws/credentials", "mode": "deny" },
{ "path": "~/.ssh", "mode": "deny" }
],
"envVars": [
{ "name": "GITHUB_TOKEN", "mode": "deny" },
{ "name": "NPM_TOKEN", "mode": "deny" }
]
}
}Repositori ini tidak menyalakan sandbox di .claude/settings.json miliknya sendiri. Blok ini berasal dari artikel situs tentang tulisan containment Anthropic, dan sama dengan contoh di dokumentasi Claude Code. Blok ini menutup pintu baca yang dibiarkan terbuka oleh default: dua file itu ditolak untuk dibaca di dalam sandbox, dan dua variabel itu dihapus sebelum setiap perintah di sandbox berjalan.
touch ~/sandbox-probe
# Sandboxed: "Operation not permitted" on macOS, "Read-only file system" on Linux/WSL2.
# If it succeeds and home is not a writable sandbox path, the sandbox is off: delete the file.
curl --noproxy '*' https://example.com
# Sandboxed: "Could not resolve host", because there is no route around the proxy.Langkah pembuktian dari artikel yang sama, yang mengikuti pengecekan di dokumentasi: satu uji untuk pintu tulis dan satu untuk pintu jaringan. Minta Claude menjalankan kedua baris itu. Perintah yang Anda ketik sendiri di prompt ! biasanya berjalan di luar sandbox, jadi mengetiknya sendiri tidak membuktikan apa-apa.
Kesalahan yang benar-benar membuang waktu
Mengira pembacaan ikut dikurung
Sandbox default membiarkan perintah membaca ~/.ssh dan file kredensial cloud, serta meneruskan environment variable Anda. Daftarkan semuanya di sandbox.credentials, atau perintah yang dibajak tetap bisa membacanya.
Melupakan tool file
sandbox.credentials dan denyRead hanya berlaku untuk perintah shell. Tool Read mengikuti aturan izin, jadi tambahkan aturan deny yang sepadan, misalnya Read(~/.ssh/**), untuk menutupnya.
Sandbox yang diam-diam tidak aktif
Jika sandbox tidak bisa dimulai, misalnya karena bubblewrap atau socat tidak terpasang di Linux, Claude Code menjalankan perintah tanpa sandbox secara default. Atur failIfUnavailable ke true, lalu jalankan dua uji coba itu.
Entri allowlist yang lebih luas dari kelihatannya
Mengizinkan domain yang luas seperti github.com membuat perintah bisa menjangkau apa pun yang bisa dilakukan sebuah akun di sana, dan proxy tidak memeriksa TLS secara default. Tambahkan host satu per satu, dan tanyakan apa yang bisa dilakukan akun jahat di masing-masing host.
| Pendekatan | Yang ada di dalam | Yang tetap di luar |
|---|---|---|
| Bash sandbox di Claude Code | Perintah shell dan proses turunannya | Tool file, hooks, dan MCP server lokal |
| Sandbox runtime di sekeliling Claude Code | Seluruh proses Claude Code, termasuk MCP server dan hooks | Apa pun yang Anda izinkan untuk ditulis atau dijangkau |
| Docker Sandboxes (microVM) | Agen dengan kernel dan Docker engine sendiri | Workspace yang dibagikan dan MCP server lokal |
| agent-sandbox di Kubernetes | Pod di bawah gVisor atau Kata, jika Anda mengaturnya | Isolasinya sendiri: proyek ini bergantung pada runtime |
Lakukan di komputer Anda sendiri
Anda butuh Claude Code di macOS, Linux, atau WSL2, serta satu folder latihan. Anda akan menyalakan sandbox, membuktikannya, lalu melihat pintu baca sebelum dan sesudah ditutup. Tidak ada langkah yang menyentuh kunci asli Anda.
Buat file rahasia palsu dan token palsu, lalu jalankan Claude Code di folder latihan.
echo not-a-real-key > ~/fake-creds.txt export FAKE_TOKEN=not-a-real-token mkdir -p ~/sandbox-practice && cd ~/sandbox-practice && claudeJalankan /sandbox dan pilih mode-nya. Lalu minta Claude menjalankan dua uji coba itu. Keduanya seharusnya gagal; tolak jika Claude meminta mengulangnya di luar sandbox.
/sandbox touch ~/sandbox-probe curl --noproxy '*' https://example.comMinta Claude menjalankan dua perintah ini. Keduanya berhasil, karena pembacaan dan environment variable terbuka secara default.
cat ~/fake-creds.txt echo $FAKE_TOKENTutup pintu bacanya. Tambahkan key berikut ke .claude/settings.local.json, tempat /sandbox menyimpan mode Anda, lalu jalankan ulang Claude Code.
{ "sandbox": { "enabled": true, "credentials": { "files": [{ "path": "~/fake-creds.txt", "mode": "deny" }], "envVars": [{ "name": "FAKE_TOKEN", "mode": "deny" }] } }, "permissions": { "deny": ["Read(~/fake-creds.txt)"] } }Minta dua perintah yang sama lagi: pembacaan file gagal dan variabelnya tercetak kosong. Lalu minta Claude membuka file itu dengan tool Read; yang menolaknya adalah aturan deny di izin, bukan sandbox.
cat ~/fake-creds.txt echo $FAKE_TOKENBersihkan file latihan setelah selesai.
rm -f ~/fake-creds.txt ~/sandbox-probe unset FAKE_TOKEN
Tiga pertanyaan sebelum lanjut
Pilih jawaban untuk melihat kenapa benar atau salah. Tidak ada nilai, jadi tebak saja dengan bebas; jawaban yang salah disimpan di browser ini agar kursus bisa menanyakannya lagi nanti.
Dua pertanyaan dari pelajaran sebelumnya
Mengingat kembali pelajaran lama setelah jeda membuatnya lebih melekat. Jawab dari ingatan sebelum mencari apa pun.
Jawab dalam hati, lalu cek
1.Mengapa sandbox melindungi Anda dari prompt injection, sementara prompt izin belum tentu?Lihat jawabannya
Jawaban:Prompt bergantung pada manusia yang membaca setiap permintaan dengan teliti. Sandbox ditegakkan sistem operasi pada proses yang sedang berjalan, jadi tetap bertahan meski model sudah terbujuk menjalankan sesuatu.
2.Agen Anda perlu membaca issue dari satu host API internal. Apa yang Anda tambahkan, dan apa yang perlu ditanyakan dulu?Lihat jawabannya
Jawaban:Tambahkan satu host itu ke allowedDomains dan jangan yang lebih luas. Tanyakan dulu apa yang bisa dilakukan proses jahat dengan sebuah akun di host itu, karena host yang diizinkan adalah sekumpulan kemampuan, bukan sekadar tujuan.
3.Kapan sandbox shell bawaan Claude Code tidak cukup jika dipakai sendirian?Lihat jawabannya
Jawaban:Saat agen berjalan sepenuhnya tanpa pengawasan, atau saat ada MCP server, hooks, atau tool file yang tidak sepenuhnya Anda percayai. Dalam kasus itu, seluruh agen harus berada di dalam container, VM, atau sandbox runtime.
Bahasan mendalam terkait di situs ini
Sumber
Sumber primer yang diperiksa pada tanggal riset. Ikuti tautannya untuk versi terbaru.
- Dokumentasi Claude Code: mengatur tool Bash yang di-sandbox
- Dokumentasi Claude Code: memilih lingkungan sandbox
- Dokumentasi Docker: model keamanan Docker Sandboxes
- kubernetes-sigs/agent-sandbox: threat model
- Anthropic Engineering: cara kami mengurung Claude
- Spesifikasi MCP 2026-07-28: kompromi MCP server lokal dan sandboxing