# 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.

URL: https://www.matthewswong.com/id/learn/ai-agents-mcp/run-an-ai-agent-in-a-sandbox/

Agen AI dan MCP · Pelajaran 4 dari 4 · Ditinjau pada 17 Oktober 2026 · Dicek dengan MCP specification 2026-07-28 · Oleh Matthews Wong (https://www.matthewswong.com/id/about/)

> 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.

## 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.

1. **Kenali batasnya.** 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.
2. **Penulisan tetap di dalam.** 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 permitted
   ```

   *Tebak:* Bisakah perintah sandbox yang sama membaca ~/.ssh secara default? (Tidak, pembacaan juga dikurung / Ya, pembacaan terbuka sampai Anda menolaknya)
3. **Pembacaan terbuka lebar.** 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 → works
   ```
4. **Tolak akses ke rahasia.** Daftarkan 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 deny
   ```
5. **Tidak ada jalan keluar.** Lalu 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 host
   ```

   *Tebak:* MCP server lokal milik agen butuh jaringan. Apakah sandbox ini membatasinya? (Ya, ia berbagi sandbox yang sama / Tidak, ia berjalan di luarnya)
6. **Yang tetap di luar.** 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.

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.

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.

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

`app/components/blogs/AnthropicContainClaudeSandboxApprovalFatigue.tsx:81-93`

```json
  "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.

`app/components/blogs/AnthropicContainClaudeSandboxApprovalFatigue.tsx:100-105`

```bash
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.

## Yang sering rusak

- **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.

### Di mana batasnya berada, dan apa yang tetap di luarnya

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

## Coba 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.

1. Buat file rahasia palsu dan token palsu, lalu jalankan Claude Code di folder latihan.

   ```bash
   echo not-a-real-key > ~/fake-creds.txt
   export FAKE_TOKEN=not-a-real-token
   mkdir -p ~/sandbox-practice && cd ~/sandbox-practice && claude
   ```
2. Jalankan /sandbox dan pilih mode-nya. Lalu minta Claude menjalankan dua uji coba itu. Keduanya seharusnya gagal; tolak jika Claude meminta mengulangnya di luar sandbox.

   ```bash
   /sandbox
   touch ~/sandbox-probe
   curl --noproxy '*' https://example.com
   ```
3. Minta Claude menjalankan dua perintah ini. Keduanya berhasil, karena pembacaan dan environment variable terbuka secara default.

   ```bash
   cat ~/fake-creds.txt
   echo $FAKE_TOKEN
   ```
4. Tutup pintu bacanya. Tambahkan key berikut ke .claude/settings.local.json, tempat /sandbox menyimpan mode Anda, lalu jalankan ulang Claude Code.

   ```bash
   {
     "sandbox": {
       "enabled": true,
       "credentials": {
         "files": [{ "path": "~/fake-creds.txt", "mode": "deny" }],
         "envVars": [{ "name": "FAKE_TOKEN", "mode": "deny" }]
       }
     },
     "permissions": {
       "deny": ["Read(~/fake-creds.txt)"]
     }
   }
   ```
5. 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.

   ```bash
   cat ~/fake-creds.txt
   echo $FAKE_TOKEN
   ```
6. Bersihkan file latihan setelah selesai.

   ```bash
   rm -f ~/fake-creds.txt ~/sandbox-probe
   unset FAKE_TOKEN
   ```

## Kuis singkat

1. **Dengan sandbox Claude Code aktif tanpa setelan tambahan, apa yang bisa dilakukan perintah di sandbox?**
   A. Menulis ke direktori home Anda
   B. Membaca ~/.ssh
   C. Terhubung langsung ke host mana pun
   Jawaban: B. Penulisan dibatasi ke proyek, temp, dan folder tambahan, dan jaringan lewat proxy yang allowlist-nya awalnya kosong. Pembacaan mencakup sebagian besar mesin, termasuk kunci, sampai Anda menolaknya.

2. **Mana di antara ini yang berjalan di luar sandbox Claude Code?**
   A. npm test yang dijalankan Claude
   B. Child process dari perintah di sandbox
   C. MCP server lokal
   Jawaban: C. Sandbox membungkus perintah shell dan turunannya. MCP server lokal, hooks, dan tool file berjalan dengan akses penuh Anda.

3. **Anda mengetik touch ~/sandbox-probe di prompt ! dan berhasil. Apa yang Anda pelajari?**
   A. Sandbox-nya mati
   B. Tidak ada: perintah yang diketik di ! biasanya berjalan di luar sandbox
   C. Direktori home Anda termasuk path tulis yang diizinkan
   Jawaban: B. Dokumentasi menyarankan meminta Claude yang menjalankan uji coba, karena perintah shell-mode yang Anda ketik sendiri biasanya berjalan tanpa sandbox dan tidak membuktikan apa-apa.

## Pikirkan dulu

- **Mengapa sandbox melindungi Anda dari prompt injection, sementara prompt izin belum tentu?** 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.
- **Agen Anda perlu membaca issue dari satu host API internal. Apa yang Anda tambahkan, dan apa yang perlu ditanyakan dulu?** 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.
- **Kapan sandbox shell bawaan Claude Code tidak cukup jika dipakai sendirian?** 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.

## Pelajari lebih dalam

- [Sandbox AI Coding Agent: Atasi Approval Fatigue di CI](https://www.matthewswong.com/id/blog/anthropic-how-we-contain-claude-sandbox-approval-fatigue/)
- [Sandboxing Agen AI dan Lethal Trifecta](https://www.matthewswong.com/id/blog/sandboxing-ai-agents-lethal-trifecta/)
- [Sandboxing Claude Code: Menjalankan Bash dengan Aman](https://www.matthewswong.com/id/blog/claude-code-sandboxing-bash-guide/)
- [Docker Sandboxes sbx: Claude Code di MicroVM Cloud](https://www.matthewswong.com/id/blog/docker-sandboxes-cloud-sandboxes-sbx-guide/)

## Sumber

- [Dokumentasi Claude Code: mengatur tool Bash yang di-sandbox](https://code.claude.com/docs/en/sandboxing)
- [Dokumentasi Claude Code: memilih lingkungan sandbox](https://code.claude.com/docs/en/sandbox-environments)
- [Dokumentasi Docker: model keamanan Docker Sandboxes](https://docs.docker.com/ai/sandboxes/security/)
- [kubernetes-sigs/agent-sandbox: threat model](https://github.com/kubernetes-sigs/agent-sandbox/blob/main/docs/security/threat_model.md)
- [Anthropic Engineering: cara kami mengurung Claude](https://www.anthropic.com/engineering/how-we-contain-claude)
- [Spesifikasi MCP 2026-07-28: kompromi MCP server lokal dan sandboxing](https://modelcontextprotocol.io/specification/2026-07-28/basic/security_best_practices)

---

- HTML version: https://www.matthewswong.com/id/learn/ai-agents-mcp/run-an-ai-agent-in-a-sandbox/
- English: https://www.matthewswong.com/en/learn/ai-agents-mcp/run-an-ai-agent-in-a-sandbox/
- Site index for agents: https://www.matthewswong.com/llms.txt
- Sitemap: https://www.matthewswong.com/sitemap.xml
- API description (OpenAPI): https://www.matthewswong.com/openapi.json