Konfigurasikan tool Bash dengan sandbox

Batasi file dan host jaringan yang dapat dijangkau oleh perintah shell Claude Code dengan sandbox bawaan. Aktifkan, tetapkan batasnya, dan perbaiki hal-hal yang terganggu olehnya.

Sandbox Bash adalah batas yang diterapkan oleh sistem operasi di sekitar perintah shell yang dijalankan Claude di mesin Anda. Anda menetapkan file dan domain jaringan mana yang dapat dijangkau oleh perintah tersebut, dan batasan tersebut berlaku untuk perintah Bash, PowerShell, dan Monitor serta proses yang dimulainya. Karena sistem operasi menerapkan batasan tersebut saat perintah berjalan, Claude Code dapat menjalankan perintah dalam sandbox tanpa meminta Anda untuk menyetujui setiap perintah.

Sandbox hanya mencakup perintah shell. Tool file Claude, server MCP, dan hook berjalan di luarnya.

Sandbox berjalan di macOS, Linux, dan WSL2. Di Windows native, Claude Code menjalankan perintah tanpa sandbox. Untuk menggunakan sandbox di mesin Windows, jalankan Claude Code di dalam distribusi WSL2.

Apa yang dibatasi oleh sandbox

Saat sandbox aktif, perintah shell yang dijalankan Claude dimulai di dalam batasnya, demikian pula proses yang dimulai oleh perintah tersebut. Sandbox nonaktif secara default. Untuk mengaktifkannya, jalankan /sandbox dalam sebuah sesi, seperti yang ditunjukkan di Memulai, atau atur sandbox.enabled ke true dalam file pengaturan seperti ~/.claude/settings.json.

Tabel berikut menunjukkan apa yang dapat dijangkau oleh perintah yang berjalan di sandbox secara default dan pengaturan yang mengubah setiap default tersebut.

Akses	Default	Ubah dengan
Penulisan	Direktori kerja, direktori temp per pengguna, dan direktori yang telah Anda tambahkan. Path yang dilindungi tetap ditolak untuk penulisan	`filesystem.allowWrite`, `filesystem.denyWrite`
Pembacaan	Sebagian besar mesin, termasuk file kredensial seperti `~/.ssh` dan `~/.aws/credentials`	`filesystem.denyRead`, `credentials`
Jaringan	Tidak ada rute keluar langsung. Koneksi melewati proxy di mesin Anda yang memeriksa setiap host terhadap domain yang Anda izinkan, yang awalnya kosong. Mode izin Anda menentukan apa yang terjadi pada host lain	`network.allowedDomains`, `network.deniedDomains`
Environment variable	Diwarisi dari Claude Code, termasuk rahasia apa pun di lingkungannya	`credentials`, `CLAUDE_CODE_SUBPROCESS_ENV_SCRUB`

Claude Code membangun sandbox di atas paket open source @anthropic-ai/sandbox-runtime.

Apa yang berjalan di luar sandbox

Sandbox membungkus perintah shell. Tool dan proses berikut berjalan di luarnya:

Tool file dan web bawaan: tool seperti Read, Edit, Write, WebFetch, dan WebSearch mengikuti aturan izin sebagai gantinya. Entri denyRead tidak menghentikan tool Read, dan allowedDomains tidak membatasi WebFetch
Proses lain yang dimulai Claude Code: hook perintah, server MCP lokal, monitor plugin, server LSP, dan perintah pembantu seperti perintah baris status Anda dan apiKeyHelper berjalan dengan akses penuh Anda

Beberapa perintah shell juga berjalan di luar sandbox, tergantung pada pengaturan Anda:

Perintah yang Anda ketik sendiri: perintah yang Anda masukkan di prompt mode shell ! berjalan tanpa sandbox di sebagian besar sesi. Mode sandbox ketat mencantumkan sesi-sesi di mana perintah yang Anda ketik berjalan di dalam sandbox
Perintah yang dikecualikan: perintah yang cocok dengan excludedCommands berjalan tanpa sandbox
Retry tanpa sandbox: Claude dapat meminta untuk menjalankan perintah tanpa sandbox, biasanya setelah perintah tersebut gagal di dalam sandbox

Untuk menempatkan tool, proses, dan perintah di bagian ini di balik satu batas, jalankan proses Claude Code itu sendiri di dalam container, mesin virtual, atau sandbox runtime.

Memulai

Sandbox sudah terpasang di dalam Claude Code. Apa yang perlu Anda instal bergantung pada platform Anda:

macOS: sandboxing menggunakan framework Seatbelt bawaan, sehingga Anda dapat langsung menuju langkah-langkahnya
Linux dan WSL2: sandbox bergantung pada bubblewrap dan socat, yang dibahas di Menyiapkan Linux dan WSL2. Meskipun Anda belum menginstalnya, Anda dapat memulai dengan /sandbox, karena panelnya menunjukkan apakah ada yang belum terpasang

Jalankan /sandbox

Mulai sesi Claude Code dan jalankan perintah /sandbox:

/sandbox

Ini membuka panel sandbox dengan tiga tab, ditambah tab Dependencies di Linux ketika filter seccomp opsional belum terpasang:

Mode: pilih cara perintah yang di-sandbox disetujui, dibahas pada langkah berikutnya
Overrides: pilih apakah perintah yang gagal di bawah sandbox dapat kembali berjalan tanpa sandbox. Ini adalah pengaturan allowUnsandboxedCommands
Config: lihat pengaturan sandbox yang telah diselesaikan

Jika panel hanya menampilkan tab Dependencies, berarti ada paket wajib yang belum terpasang. Instal paket tersebut seperti yang dijelaskan di Menyiapkan Linux dan WSL2, mulai ulang Claude Code, lalu jalankan /sandbox lagi.

Pilih mode

Pada tab Mode, pilih auto-allow atau regular permissions. Auto-allow menjalankan perintah yang di-sandbox tanpa permintaan izin, sedangkan regular permissions tetap mempertahankan permintaan izin biasa bahkan ketika perintah di-sandbox. Lihat Mode sandbox untuk perintah mana saja yang tetap memunculkan permintaan izin dalam mode auto-allow.

Jalankan perintah Bash

Minta Claude menjalankan sebuah perintah, seperti build atau rangkaian pengujian. Secara default, perintah di dalam sandbox dapat menulis ke direktori kerja, direktori temp per pengguna, dan direktori apa pun yang telah Anda tambahkan dengan --add-dir, /add-dir, atau permissions.additionalDirectories.

Saat pertama kali sebuah perintah memerlukan domain jaringan baru, Claude Code meminta persetujuan; dalam auto mode, Claude justru menyebutkan host yang dibutuhkan perintah pada perintah itu sendiri agar pengklasifikasi meninjaunya bersama perintah tersebut.

Untuk memperluas atau mempersempit apa yang diizinkan sandbox, lihat Mengonfigurasi sandboxing.

Jika perintah yang di-sandbox gagal dengan Operation not permitted di dalam container, lihat Bubblewrap gagal dimulai di dalam container.

Ketika Anda memilih mode di panel, Claude Code menyimpannya ke pengaturan lokal proyek Anda di .claude/settings.local.json, yang berlaku untuk proyek saat ini. Claude Code menambahkan file tersebut ke gitignore global Anda ketika menyimpan pengaturan di sana. Untuk mengaktifkan sandbox di semua proyek Anda, atur sandbox.enabled ke true dalam pengaturan pengguna Anda di ~/.claude/settings.json. Untuk mewajibkan sandboxing bagi setiap developer dalam organisasi, gunakan pengaturan terkelola.

Untuk mengubah sandbox untuk satu sesi tanpa menulis ke file pengaturan, mulai Claude Code dengan --settings. Misalnya, perintah ini memulai sesi yang di-sandbox di mana Claude tidak dapat mencoba ulang perintah yang diblokir di luar sandbox:

claude --settings '{"sandbox": {"enabled": true, "allowUnsandboxedCommands": false}}'

Memastikan perintah berjalan di dalam sandbox

Untuk memeriksa apakah sandbox berfungsi, minta Claude menjalankan setiap baris dalam tabel. Apa yang Anda ketik di prompt ! biasanya berjalan di luar sandbox, sehingga mengetik baris tersebut sendiri tidak mengujinya.

Perintah	Hasil di dalam sandbox
`touch ~/sandbox-probe`	Gagal dengan `Operation not permitted` di macOS, atau `Read-only file system` di Linux dan WSL2
`curl --noproxy '*' https://example.com`	Gagal dengan `Could not resolve host`, karena perintah tidak memiliki jalur untuk melewati proxy sandbox

Jika Claude meminta untuk mencoba ulang perintah yang gagal di luar sandbox, tolak retry tersebut. Jika touch berhasil dan direktori home Anda bukan salah satu direktori yang diizinkan sandbox untuk ditulisi oleh perintah, hapus ~/sandbox-probe. Kemudian jalankan /sandbox untuk memeriksa bahwa sandbox aktif dan dependensinya terinstal.

Menyiapkan Linux dan WSL2

Di Linux dan WSL2, sandbox bergantung pada paket-paket berikut:

bubblewrap: tool sandboxing tanpa hak istimewa yang menerapkan isolasi filesystem
socat: relay yang digunakan untuk merutekan lalu lintas jaringan melalui proxy sandbox

Instal paket-paket tersebut dengan package manager distribusi Anda:

sudo apt-get install bubblewrap socat

sudo dnf install bubblewrap socat

Ketika ada dependensi yang belum terpasang, tab Dependencies di /sandbox mencantumkan mana di antara ripgrep, bubblewrap, socat, dan filter seccomp yang tidak dimiliki platform Anda. Jika Anda tidak melihat tab tersebut setelah menginstal dan memulai ulang Claude Code, berarti semua dependensi sudah tersedia.

Ripgrep sudah dibundel dengan binary native Claude Code. Filter seccomp bersifat opsional dan menambahkan pemblokiran Unix domain socket. Instal dengan npm install -g @anthropic-ai/sandbox-runtime jika belum terpasang.

Ketika dependensi wajib belum terpasang, tab Dependencies adalah satu-satunya tab yang ditampilkan hingga Anda menginstalnya. Ketika hanya filter seccomp opsional yang belum terpasang, tab Dependencies muncul bersama tab lainnya. Pemeriksaan dependensi berjalan saat startup, jadi mulai ulang Claude Code setelah menginstal paket agar /sandbox dapat mendeteksinya.

Di Ubuntu 24.04 dan yang lebih baru, kebijakan AppArmor default mencegah bubblewrap membuat user namespace yang dibutuhkannya untuk isolasi.

Untuk memeriksa apakah lingkungan Anda menerapkan pembatasan ini, termasuk di dalam WSL2, jalankan `sysctl kernel.apparmor_restrict_unprivileged_userns`. Jika perintah mengembalikan `0`, lewati langkah ini. Jika perintah mencetak error `No such file or directory`, berarti key tersebut tidak ada dan Anda dapat melewati langkah ini. Jika mengembalikan `1`, tambahkan profil AppArmor yang memberikan kemampuan ini kepada `bwrap`:

```bash theme={null}
sudo tee /etc/apparmor.d/bwrap > /dev/null <<'EOF'
abi <abi/4.0>,
include <tunables/global>

profile bwrap /usr/bin/bwrap flags=(unconfined) {
  userns,
  include if exists <local/bwrap>
}
EOF
```

Profil ini hanya berlaku untuk `bwrap` itu sendiri, bukan untuk perintah yang dijalankannya di dalam sandbox. Muat ulang AppArmor untuk menerapkannya:

```bash theme={null}
sudo systemctl reload apparmor
```

Catatan WSL2

Periksa versi WSL Anda dengan wsl -l -v dari PowerShell. Jika Anda melihat Sandboxing requires WSL2, distribusi Anda berjalan di WSL1. Tingkatkan ke WSL2 atau jalankan Claude Code tanpa sandboxing.

Di WSL2, WSL menyerahkan peluncuran binary Windows seperti cmd.exe, powershell.exe, atau apa pun di bawah /mnt/c/ ke host Windows melalui Unix socket, sehingga apakah perintah yang di-sandbox dapat meluncurkannya mengikuti pengaturan Unix socket sandbox: filter seccomp opsional harus terinstal agar socket tersebut dapat diblokir sejak awal. Untuk mengizinkan peluncuran ini, atur allowAllUnixSockets, yang membuka setiap Unix socket bagi perintah yang di-sandbox.

Mode sandbox

Claude Code menawarkan dua mode sandbox. Pada keduanya, sandbox menerapkan pembatasan filesystem dan jaringan yang sama; perbedaannya hanya pada apakah perintah yang di-sandbox disetujui secara otomatis atau memerlukan izin eksplisit.

Mode auto-allow

Claude Code menyetujui perintah secara otomatis, tanpa permintaan izin, ketika perintah berjalan di dalam sandbox. Sebuah perintah melalui alur izin biasa ketika berjalan di luar sandbox karena cocok dengan excludedCommands atau karena Claude mencobanya ulang tanpa sandbox.

Perintah yang di-sandbox yang terhubung ke host yang belum Anda izinkan tetap berada di dalam sandbox. Host di luar domain yang Anda izinkan membahas siapa yang memutuskan apakah koneksi tersebut diteruskan.

Bahkan dalam mode auto-allow, hal-hal berikut tetap berlaku:

Aturan deny eksplisit selalu dipatuhi
Perintah rm atau rmdir yang menargetkan jalur kritis tetap melalui alur izin biasa
Aturan ask yang dibatasi konten seperti Bash(git push *) tetap memaksa munculnya permintaan izin bahkan untuk perintah yang di-sandbox
Aturan ask Bash polos, atau bentuk setaranya Bash(*), dilewati untuk perintah yang berjalan di-sandbox; aturan ini tetap berlaku untuk perintah yang kembali ke alur izin biasa. Dalam plan mode, aturan ini tidak dilewati: aturan ini memunculkan permintaan izin untuk perintah yang di-sandbox juga, termasuk yang read-only

Mode regular permissions

Semua perintah Bash melalui alur izin biasa, bahkan ketika di-sandbox. Ini memberikan kontrol lebih besar tetapi memerlukan lebih banyak persetujuan.

Jalan keluar retry tanpa sandbox

Retry tanpa sandbox adalah jalan keluar untuk perintah yang gagal di dalam sandbox, seperti tool yang tidak kompatibel dengannya. Ketika sandbox memblokir koneksi jaringan, Claude Code menyebutkan host yang ditolak dalam hasil perintah, sehingga Claude melihat apa yang diblokir. Claude menganalisis kegagalan tersebut dan dapat mencoba ulang perintah dengan parameter dangerouslyDisableSandbox.

Perintah yang dicoba ulang berjalan tanpa sandbox. Dalam sesi terminal interaktif, siapa yang menyetujuinya bergantung pada mode izin Anda:

Mode bypassPermissions: retry berjalan tanpa permintaan izin
Mode Manual dan mode acceptEdits: Anda mendapatkan permintaan izin berjudul "Bash command (unsandboxed)"
Auto mode: model pengklasifikasi terpisah mengevaluasi perintah yang mendasarinya
Mode dontAsk: Claude Code menolak retry tersebut
Plan mode: lihat cara Claude Code membatasi perintah saat Anda membuat rencana

Aturan dan pengaturan berikut mengubah siapa yang menyetujui retry:

Aturan allow yang cocok: jika aturan allow seperti Bash(curl *) cocok dengan perintah, aturan tersebut juga menyetujui retry, sehingga perintah berjalan di luar sandbox tanpa permintaan izin
Aturan ask untuk parameter: tambahkan aturan ask untuk Bash(dangerouslyDisableSandbox:true) agar Anda dimintai izin pada retry Bash. Anda juga mendapatkan permintaan izin dalam auto mode dan mode bypassPermissions, dan aturan ini diutamakan daripada aturan allow yang cocok
permissions.blockReadsOutsideWorkingDirectories: Tindakan yang tidak disetujui otomatis oleh mode mana pun membahas retry yang memunculkan permintaan izin saat pengaturan ini aktif

Matikan retry dengan strict sandbox mode

Anda dapat menonaktifkan retry tanpa sandbox dengan mengatur "allowUnsandboxedCommands": false dalam pengaturan sandbox Anda. Dengan retry dinonaktifkan, Claude Code mengabaikan parameter dangerouslyDisableSandbox. Selama sandbox berjalan, perintah yang dijalankan Claude kemudian di-sandbox kecuali cocok dengan entri excludedCommands. Untuk mencegah Claude Code menjalankan perintah tanpa sandbox ketika sandbox tidak dapat dimulai, atur juga failIfUnavailable. Tab Overrides di /sandbox menampilkan pengaturan ini sebagai Strict sandbox mode.

Nilai false dalam pengaturan pengguna Anda, --settings, atau pengaturan terkelola tetap berlaku bahkan ketika pengaturan proyek mengatur true. Nilai false dalam pengaturan pengguna Anda tidak membuat sandbox menjadi wajib oleh admin, sehingga pengaturan sandbox lain dari proyek tetap berlaku. Sebelum v2.1.285, nilai true dari proyek menimpa nilai false dalam pengaturan pengguna Anda.

Jika Anda atau administrator Anda menonaktifkan retry dalam pengaturan terkelola atau dengan flag --settings, sandbox menjadi wajib oleh admin. Claude Code kemudian mengabaikan pengaturan dalam file repositori yang melonggarkan sandbox, termasuk entri excludedCommands. Pengaturan repositori di bawah sandbox yang diwajibkan admin mencantumkan pengaturan tersebut.

Strict sandbox mode berlaku untuk perintah yang dijalankan Claude. Perintah yang Anda ketik sendiri di prompt shell-mode ! berjalan di luar sandbox kecuali sesinya merupakan salah satu dari berikut:

Sesi latar belakang: strict sandbox mode juga mencakup perintah shell-mode
Sesi Linux dengan CLAUDE_CODE_SUBPROCESS_ENV_SCRUB diatur: setiap perintah berjalan di-sandbox, termasuk perintah shell-mode

Sebelum v2.1.260, strict sandbox mode men-sandbox perintah shell-mode di setiap sesi.

Direktori sementara

Direktori temp per pengguna dapat ditulisi di dalam sandbox secara default, bersama dengan direktori kerja. Kecuali Anda menonaktifkan isolasi filesystem, Claude Code mengatur $TMPDIR ke direktori ini untuk perintah yang di-sandbox, sehingga tool yang menulis file sementara dapat bekerja tanpa konfigurasi tambahan.

Perintah tanpa sandbox mewarisi $TMPDIR dari shell Anda ketika variabel tersebut diatur, sehingga selama isolasi filesystem aktif, perintah yang di-sandbox dan yang tidak di-sandbox menyelesaikan $TMPDIR ke direktori yang berbeda. Jika shell Anda membiarkan $TMPDIR tidak diatur atau kosong, perintah tanpa sandbox yang mereferensikan $TMPDIR menerima override CLAUDE_CODE_TMPDIR Anda, atau direktori temp sistem operasi ketika Anda belum mengaturnya atau override tersebut berupa jalur yang panjang, sehingga variabel tersebut tidak diekspansi menjadi string kosong. Untuk meneruskan file sementara di antara keduanya, tuliskan file tersebut di bawah direktori kerja.

Mengonfigurasi sandboxing

Sesuaikan perilaku sandbox melalui file settings.json Anda. Lihat Pengaturan untuk referensi konfigurasi lengkap.

Secara default, perintah yang berjalan di sandbox dapat menulis ke direktori kerja saat ini, direktori temp per pengguna, dan direktori apa pun yang telah Anda tambahkan dengan --add-dir, /add-dir, atau permissions.additionalDirectories. Jika perintah subproses seperti kubectl, terraform, atau npm perlu menulis di luar direktori tersebut, gunakan sandbox.filesystem.allowWrite untuk memberikan akses ke path tertentu:

{
  "sandbox": {
    "enabled": true,
    "filesystem": {
      "allowWrite": ["~/.kube", "/tmp/build"]
    }
  }
}

Path ini diberlakukan di tingkat OS, sehingga semua perintah yang berjalan di dalam sandbox, termasuk proses turunannya, mematuhinya. Ini adalah pendekatan yang direkomendasikan ketika sebuah tool memerlukan akses tulis ke lokasi tertentu, alih-alih mengecualikan tool tersebut dari sandbox sepenuhnya dengan excludedCommands.

Ketika Anda mendefinisikan array filesystem yang sama di beberapa cakupan pengaturan, Claude Code menggabungkannya, yaitu mengombinasikan path dari setiap cakupan alih-alih mengganti array dari satu cakupan dengan array dari cakupan lain.

Jika Anda mengecualikan suatu sumber dengan --setting-sources di CLI atau settingSources di Agent SDK, Claude Code mengabaikan entri sandbox.filesystem, aturan izin Edit, dan aturan deny Read dari sumber tersebut saat membangun konfigurasi sandbox. Memerlukan Claude Code v2.1.246 atau lebih baru.

Ketika Anda mengedit daftar filesystem ini selama sesi, Claude Code menerapkan perubahan tersebut ke sesi yang sedang berjalan, sehingga perintah sandbox berikutnya berjalan dengan path yang baru.

Path filesystem sandbox menggunakan konvensi standar: /tmp/build adalah path absolut dan ~/.kube relatif terhadap direktori home Anda. Ini berbeda dari aturan izin Read dan Edit, yang menggunakan //path untuk path absolut dan /path untuk path relatif terhadap proyek. Untuk path relatif, garis miring di akhir, dan wildcard, lihat Prefiks path sandbox.

Anda juga dapat menolak akses tulis atau baca menggunakan sandbox.filesystem.denyWrite dan sandbox.filesystem.denyRead, dan mengizinkan kembali path tertentu di dalam wilayah yang ditolak menggunakan sandbox.filesystem.allowRead. Ketika aturan baca tumpang tindih, aturan dengan path yang lebih sempit yang berlaku:

Contoh aturan	Hasil
`"denyRead": ["~/"]` dengan `"allowRead": ["~/projects"]`	`~/projects` dapat dibaca dan bagian lain dari direktori home tetap diblokir. Allow yang lebih sempit membuka kembali bagian tersebut dari wilayah yang ditolak
`"allowRead": ["~/"]` dengan `"denyRead": ["~/.env"]`	`~/.env` tetap diblokir dan bagian lain dari direktori home dapat dibaca. Deny tetap berlaku di dalam allow yang lebih luas, sehingga allow yang luas tidak dapat secara diam-diam mengekspos kembali sebuah rahasia
`"allowRead": ["~/"]` dengan `"denyRead": ["~/**/.env"]`	Setiap `.env` di bawah direktori home tetap diblokir dan sisanya dapat dibaca. Deny dengan wildcard tetap berlaku di dalam allow yang lebih luas dengan cara yang sama seperti path yang persis

Contoh di bawah ini memblokir pembacaan dari seluruh direktori home sambil tetap mengizinkan pembacaan dari proyek saat ini. Letakkan di .claude/settings.json proyek Anda, karena path relatif . di-resolve ke root proyek hanya ketika konfigurasi berada di pengaturan proyek:

{
  "sandbox": {
    "enabled": true,
    "filesystem": {
      "denyRead": ["~/"],
      "allowRead": ["."]
    }
  }
}

Jika Anda meletakkan konfigurasi yang sama di ~/.claude/settings.json, . akan di-resolve ke ~/.claude, dan file proyek akan tetap diblokir oleh aturan denyRead.

Untuk menolak akses baca perintah sandbox ke direktori home dan volume yang di-mount sambil menjaga direktori kerja tetap dapat dibaca, atur permissions.blockReadsOutsideWorkingDirectories alih-alih menulis aturan path.

Menjalankan perintah di luar sandbox dengan `excludedCommands`

Cantumkan pola perintah di sandbox.excludedCommands untuk menjalankan perintah yang cocok di luar sandbox, yang berarti tanpa pembatasan filesystem dan tanpa proxy jaringan. Gunakan ini untuk tool yang tidak dapat bekerja di dalam sandbox dan yang Anda percayai dengan akses penuh Anda. Tool yang memerlukan satu direktori atau satu host tambahan mungkin dapat bekerja dengan allowWrite atau allowedDomains, yang menjaga perintah tetap berada di dalam sandbox.

Contoh ini mengeluarkan perintah docker compose dari sandbox. Simpan di ~/.claude/settings.json untuk menerapkannya ke semua proyek Anda:

{
  "sandbox": {
    "enabled": true,
    "excludedCommands": ["docker compose *"]
  }
}

Claude Code memeriksa entri Anda terhadap setiap panggilan Bash dan Monitor. Sebuah panggilan adalah seluruh baris perintah yang dikirim Claude, yang dapat merangkai beberapa perintah. Aturan berikut menentukan apakah sebuah panggilan keluar dari sandbox:

Akhiri pola dengan *: entri menggunakan sintaks yang sama dengan aturan izin Bash(...), di mana pola tanpa wildcard merupakan kecocokan persis. docker hanya cocok dengan docker tanpa argumen. docker * cocok dengan docker dengan atau tanpa argumen
Setiap perintah dalam panggilan harus cocok: npm ci && docker compose build tetap berada di dalam sandbox kecuali ada entri lain yang mencakup npm ci
Claude Code mencocokkan teks panggilan: skrip atau target make yang memanggil docker secara internal tidak cocok, begitu pula /usr/local/bin/docker
Beberapa panggilan tetap berada di dalam sandbox: redirect ke file, cd, atau command substitution seperti $(...) membuat seluruh panggilan tetap berada di dalam sandbox. Entri referensi mencantumkan lebih banyak panggilan yang tetap berada di dalam sandbox
Lokasi penyimpanan entri dapat berpengaruh: selama sandbox diwajibkan oleh admin, Claude Code mengabaikan entri di .claude/settings.json dan .claude/settings.local.json

Perintah yang dikecualikan melewati alur izin biasa:

Perintah read-only dan perintah yang dicakup oleh aturan allow Anda berjalan tanpa permintaan izin
Dalam auto mode, pengklasifikasi meninjau perintah lain yang dikecualikan
Dalam mode bypassPermissions, perintah yang dikecualikan berjalan tanpa permintaan izin kecuali ada aturan ask yang cocok dengannya

Untuk memastikan sebuah entri cocok, beralihlah ke mode Manual dan minta Claude menjalankan perintah yang cocok yang mengubah sesuatu, seperti docker compose up -d. Dialog izin akan berjudul "Bash command (unsandboxed)".

Menonaktifkan isolasi filesystem

Atur sandbox.filesystem.disabled ke true untuk melewati isolasi filesystem sambil tetap mempertahankan isolasi jaringan. Contoh di bawah ini mematikan isolasi filesystem sambil tetap mempertahankan allowlist domain jaringan:

{
  "sandbox": {
    "enabled": true,
    "filesystem": {
      "disabled": true
    },
    "network": {
      "allowedDomains": ["github.com", "*.npmjs.org"]
    }
  }
}

Sandbox memiliki dua lapisan independen: isolasi filesystem mengontrol path mana yang dapat dibaca dan ditulis oleh perintah sandbox, dan isolasi jaringan mengontrol domain mana yang dapat mereka jangkau. Dengan lapisan filesystem dimatikan, perintah sandbox mendapatkan akses baca dan tulis tanpa batas ke filesystem host, sementara lalu lintas jaringan keluarnya tetap terbatas pada domain yang Anda izinkan. Matikan lapisan ini ketika Anda menggunakan sandbox untuk mengontrol ke mana perintah terhubung, bukan apa yang mereka tulis.

sandbox.filesystem.disabled default ke false. Memerlukan Claude Code v2.1.216 atau lebih baru.

Pengaturan mana yang dapat menonaktifkannya

Karena mematikan isolasi filesystem memperluas apa yang dapat dilakukan perintah sandbox, Claude Code hanya menghormati filesystem.disabled dari sumber pengaturan berikut:

Pengaturan pengguna, pengaturan terkelola, dan flag CLI --settings dapat mengaturnya. Pengaturan proyek di .claude/settings.json dan .claude/settings.local.json tidak dapat, sehingga proyek yang di-checkout tidak dapat mematikan isolasi filesystem.
Ketika pengaturan terkelola mengonfigurasi sandbox.filesystem sama sekali, atau mencantumkan entri sandbox.credentials.files apa pun dengan "mode": "deny", hanya pengaturan terkelola yang dapat mengatur kunci tersebut. Ini menjaga pembatasan filesystem yang di-deploy administrator tetap berlaku; untuk melonggarkan deployment semacam itu, atur "disabled": true di pengaturan terkelola.
Ketika CLAUDE_CODE_SUBPROCESS_ENV_SCRUB diatur, Claude Code mengabaikan filesystem.disabled dari setiap sumber, termasuk pengaturan terkelola, dan tetap mengaktifkan isolasi filesystem.

Entri mask yang valid tidak mengunci kunci tersebut, bahkan ketika Claude Code melakukan fallback ke deny untuk entri tersebut saat startup. Cantumkan path yang tidak dapat di-mask, seperti direktori kredensial, sebagai entri deny eksplisit di pengaturan terkelola, yang mengunci kunci tersebut.

Apa yang berubah saat isolasi filesystem dimatikan

Mengatur filesystem.disabled mencabut perlindungan yang diberlakukan oleh lapisan filesystem itu sendiri. Perlindungan yang diberlakukan oleh lapisan lain tetap berlaku:

Perlindungan	Dengan isolasi filesystem dimatikan
`filesystem.denyRead` dan blokir baca `deny` `credentials.files`	Tidak diberlakukan. Lapisan filesystem yang menerapkan keduanya
Entri `deny` dan `mask` `credentials.envVars`	Diberlakukan. Pembersihan environment variable tidak bergantung pada lapisan filesystem
Entri `mask` `credentials.files` yang diterapkan sebagai mask	Diberlakukan: masking tidak bergantung pada lapisan filesystem. Entri yang mengalami fallback ke `deny` tidak diberlakukan, seperti entri `deny` lainnya

Dua hal lain berubah:

Perintah sandbox mewarisi $TMPDIR shell Anda alih-alih direktori temp per pengguna, karena setiap direktori temp dapat ditulis dan Claude Code tidak lagi mengarahkan perintah ke direktori per pengguna.

Di Linux, variabel ini sering kali tidak diatur di shell induk. Panduan tool Bash memberi tahu Claude untuk membuat direktori sementara dengan mktemp -d alih-alih mengandalkan $TMPDIR.
autoAllowBashIfSandboxed tetap default ke true, sehingga perintah sandbox tetap berjalan tanpa permintaan izin. Atur ke false untuk meminta izin bagi perintah sandbox.

Melindungi kredensial

Pengaturan sandbox.credentials mendeklarasikan file kredensial dan environment variable yang akan dilindungi dari perintah sandbox. Setiap entri menyebutkan path file atau environment variable dan sebuah mode. Blok credentials khusus ini menjaga aturan kredensial tetap terkelompok dan terpisah dari aturan filesystem umum.

Untuk entri dengan "mode": "deny", path file ditolak untuk dibaca di dalam sandbox, pembatasan yang sama dengan yang diterapkan filesystem.denyRead, dan environment variable dihapus sebelum setiap perintah sandbox dijalankan. Perlindungan file merupakan bagian dari lapisan filesystem, sehingga tidak berlaku jika Anda menonaktifkan isolasi filesystem; perlindungan environment variable tetap berlaku.

Contoh di bawah ini memblokir pembacaan file kredensial AWS dan direktori SSH serta menghapus GITHUB_TOKEN dan NPM_TOKEN dari environment perintah sandbox:

{
  "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" }
      ]
    }
  }
}

Entri environment variable dan entri file juga menerima "mode": "mask", yang dijelaskan di Melakukan mask kredensial.

Path file mengikuti aturan prefiks yang sama dengan pengaturan sandbox.filesystem.*.

Claude Code menggabungkan entri deny dari setiap cakupan pengaturan yang dimuat sesi. Entri deny hanya pernah mempersempit akses, sehingga cakupan mana pun dapat menambahkannya, tetapi tidak ada cakupan yang dapat menghapus entri yang ditambahkan oleh cakupan lain.

Ketika Anda mengecualikan sumber pengaturan:

Pengaturan proyek atau lokal: Claude Code tidak menerapkan satu pun entri credentials dari sumber tersebut. Memerlukan Claude Code v2.1.246 atau lebih baru.
Pengaturan pengguna: Claude Code tetap menerapkan entri deny di ~/.claude/settings.json dan mempertahankan entri mask file sebagai pembatasan yang tidak lagi memberi wewenang kepada proxy untuk mensubstitusi nilai sebenarnya, tetapi membuang entri mask environment variable.

Tidak ada daftar deny kredensial bawaan, sehingga hanya file dan variabel yang Anda cantumkan yang dibatasi.

sandbox.credentials hanya memengaruhi perintah Bash sandbox. Untuk menghapus kredensial dari semua subproses terlepas dari sandboxing, atur CLAUDE_CODE_SUBPROCESS_ENV_SCRUB.

Melakukan mask kredensial

Ketika Anda melakukan mask pada kredensial, Claude Code menampilkan placeholder per sesi yang disebut sentinel kepada perintah sandbox, dan proxy sandbox mensubstitusi nilai sebenarnya pada permintaan keluar ke host yang Anda izinkan. Entri deny di Melindungi kredensial justru memblokir kredensial. Untuk file di macOS, Claude Code memblokir file tersebut alih-alih melakukan mask.

Melakukan mask environment variable memerlukan Claude Code v2.1.199 atau lebih baru. Referensi sandbox.credentials mencantumkan setiap field.

Masking memerlukan hal berikut:

Terminasi TLS: proxy mensubstitusi nilai sebenarnya di dalam isi permintaan, sehingga proxy harus dapat melihatnya. Atur network.tlsTerminate agar proxy menghentikan TLS sendiri. Tanpanya, masking gagal tanpa mengekspos apa pun: perintah tetap hanya melihat sentinel, tetapi sentinel mencapai server tanpa perubahan dan autentikasi gagal. Claude Code melaporkan kesalahan konfigurasi ini saat startup.
Tujuan yang diizinkan: setiap entri mask dapat mencantumkan injectHosts, yaitu host yang diizinkan untuk dijangkau oleh nilai sebenarnya. Proxy hanya menyuntikkan pada koneksi yang diterima oleh allowlist domain, sehingga setiap host injectHosts juga harus dapat dijangkau melalui network.allowedDomains. Untuk entri mask tanpa injectHosts, proxy mensubstitusi nilai sebenarnya pada permintaan ke setiap host di network.allowedDomains.
Cakupan pengaturan tepercaya: masking memberi wewenang kepada proxy untuk mengirimkan kredensial sebenarnya Anda ke suatu tempat, sehingga Claude Code hanya menghormati entri mask, network.tlsTerminate, credentials.allowPlaintextInject, awsPairs, dan sigv4 dari pengaturan pengguna, pengaturan terkelola, dan flag --settings. Claude Code mengabaikannya di .claude/settings.json atau .claude/settings.local.json milik repositori. Ketika administrator Anda mengirimkan entri mask, network.tlsTerminate, atau credentials.allowPlaintextInject melalui pengaturan yang dikelola server, entri tersebut dihitung sebagai pengaturan yang memerlukan persetujuan.

Melakukan mask environment variable

Untuk melakukan mask pada environment variable, atur "mode": "mask" pada entri credentials.envVars-nya. Perintah tersebut dan apa pun yang dicatatnya ke log tidak pernah memegang kredensial sebenarnya, tetapi permintaannya tetap terautentikasi. Ketika variabel yang sama dicantumkan dengan deny di cakupan mana pun, deny diutamakan.

Contoh ini melakukan mask pada dua token. GH_TOKEN disubstitusi hanya pada permintaan ke api.github.com, sedangkan NPM_TOKEN tidak memiliki injectHosts dan disubstitusi pada permintaan ke setiap host di network.allowedDomains:

{
  "sandbox": {
    "enabled": true,
    "network": {
      "tlsTerminate": {},
      "allowedDomains": ["*.github.com", "registry.npmjs.org"]
    },
    "credentials": {
      "envVars": [
        { "name": "GH_TOKEN", "mode": "mask", "injectHosts": ["api.github.com"] },
        { "name": "NPM_TOKEN", "mode": "mask" }
      ]
    }
  }
}

Masking mengganti seluruh nilai secara default. Untuk nilai yang memiliki struktur, seperti string koneksi DATABASE_URL atau JWT, gunakan field extract, decode, maskClaims, dan onExtractNoMatch agar tool yang mem-parse nilai tersebut tetap berfungsi.

Untuk tujuan IPv6, tuliskan alamat secara berbeda di kedua daftar:

network.allowedDomains: bentuk dalam kurung siku, seperti "[::1]"
injectHosts: alamat polos dalam bentuk terkompresi kanonisnya, seperti "::1"

Proxy mencocokkan setiap entri injectHosts dengan alamat tujuan polos koneksi, dengan mengabaikan port, sehingga penulisan dengan kurung siku, zone-ID, atau kompresi yang berbeda tidak pernah cocok. claude doctor menandai entri yang tidak akan pernah cocok dengan peringatan Sandbox credential injectHosts entries can never match their destination. Pemeriksaan ini memerlukan Claude Code v2.1.229 atau lebih baru.

Menandatangani ulang permintaan AWS

Permintaan AWS membawa tanda tangan SigV4 atas isi permintaan, jadi lakukan mask pada AWS_ACCESS_KEY_ID dan AWS_SECRET_ACCESS_KEY secara bersamaan. Proxy mendeteksi permintaan SigV4 melalui sentinel access key dan menandatangani ulang permintaan dengan nilai sebenarnya, yang memerlukan Claude Code v2.1.221 atau lebih baru. Jika Anda hanya melakukan mask pada secret, permintaan ditandatangani dengan placeholder yang tidak dapat dideteksi oleh proxy, sehingga permintaan tersebut gagal di AWS.

Claude Code secara otomatis menautkan variabel konvensional AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, dan AWS_SESSION_TOKEN menjadi satu kredensial ketika Anda melakukan mask pada seluruh nilainya. Jika kredensial AWS Anda berada di variabel dengan nama lain, kelompokkan dengan credentials.awsPairs, yang memerlukan Claude Code v2.1.224 atau lebih baru.

Unggahan streaming, URL presigned, dan permintaan SigV4A membawa tanda tangan yang tidak dapat dihitung ulang oleh proxy. Ketika salah satu permintaan ini ditandatangani dengan placeholder dari pasangan yang di-mask, proxy menggagalkannya alih-alih meneruskan tanda tangan yang rusak. Permintaan yang ditandatangani dengan kredensial yang tidak di-mask tidak terpengaruh. Gunakan credentials.sigv4, yang memerlukan Claude Code v2.1.224 atau lebih baru, untuk meneruskan salah satu bentuk permintaan ini sebagai gantinya. AWS tetap menolak permintaan tersebut, sehingga tool pemanggil menerima respons penolakan dari AWS sendiri alih-alih error proxy.

Melakukan mask file kredensial

Untuk melakukan mask pada file kredensial, atur "mode": "mask" pada entri credentials.files-nya. Melakukan mask file memerlukan Claude Code v2.1.221 atau lebih baru. Apa yang dilihat perintah sandbox bergantung pada platform:

Linux dan WSL2: perintah sandbox membaca salinan sentinel dari file, dan proxy mensubstitusi nilai sebenarnya pada permintaan keluar.
macOS: perintah sandbox sama sekali tidak dapat membaca file tersebut. Claude Code tidak membuat salinan sentinel, sehingga tool yang melakukan autentikasi dengan file tersebut tidak berfungsi di dalam sandbox, efek yang sama dengan deny. Blokir baca tetap berlaku bahkan ketika Anda menonaktifkan isolasi filesystem.

Contoh ini melakukan mask pada token GitHub yang disimpan di ~/.config/gh/hosts.yml. Pola extract menandai bagian mana dari file yang merupakan rahasia, sehingga di Linux dan WSL2 gh tetap dapat mem-parse bagian lain dari konfigurasinya:

{
  "sandbox": {
    "enabled": true,
    "network": {
      "tlsTerminate": {},
      "allowedDomains": ["*.github.com"]
    },
    "credentials": {
      "files": [
        {
          "path": "~/.config/gh/hosts.yml",
          "mode": "mask",
          "extract": "oauth_token:\\s*(\\S+)",
          "injectHosts": ["api.github.com"]
        }
      ]
    }
  }
}

Untuk memastikan mask aktif, minta Claude menjalankan cat ~/.config/gh/hosts.yml dalam perintah sandbox. Di Linux dan WSL2 output menampilkan sentinel sebagai pengganti token, dan di macOS pembacaan gagal.

Tanpa extract atau decode, Claude Code mengganti seluruh file dengan satu sentinel, yang cocok untuk file yang berisi satu rahasia polos. Gunakan field extract, decode, maskClaims, onExtractNoMatch, dan maskDuplicates untuk mengontrol masking parsial dan apa yang terjadi ketika pola tidak cocok dengan apa pun.

mask berlaku untuk satu file, jadi cantumkan setiap file kredensial secara individual. Claude Code melakukan fallback ke deny untuk entri mask yang tidak dapat di-mask dengan aman: path direktori, pola glob, file yang lebih besar dari 8 MiB, atau file yang bukan teks UTF-8.

Cara kerja sandboxing

Isolasi sistem file

Tool Bash yang di-sandbox membatasi akses sistem file ke direktori tertentu:

Perilaku tulis default: akses baca dan tulis ke direktori kerja saat ini dan subdirektorinya, direktori apa pun yang telah Anda tambahkan dengan --add-dir, /add-dir, atau permissions.additionalDirectories, ditambah direktori temp per pengguna yang ditunjuk oleh $TMPDIR
Perilaku baca default: akses baca ke seluruh komputer, kecuali direktori tertentu yang ditolak. Default ini tetap mengizinkan pembacaan file kredensial, jadi lindungi kredensial yang tidak ingin Anda biarkan dibaca oleh perintah.
Pemblokiran baca: dengan permissions.blockReadsOutsideWorkingDirectories diaktifkan, perintah yang di-sandbox juga kehilangan akses baca ke direktori home Anda dan direktori lain yang menyimpan file pengguna, kecuali jalur yang dicantumkan dalam Perintah yang di-sandbox di bawah pemblokiran. Bagian tersebut juga menjelaskan kapan bagian pemblokiran ini tidak berlaku.
Git worktree: ketika direktori kerja adalah git worktree yang ditautkan, sandbox juga mengizinkan penulisan ke direktori .git bersama milik repositori utama sehingga perintah seperti git commit dapat memperbarui ref dan index. Penulisan ke hooks/ dan config di dalam direktori tersebut tetap ditolak.

Untuk melewati isolasi sistem file sepenuhnya sambil tetap mempertahankan isolasi jaringan, atur sandbox.filesystem.disabled.

Jalur yang dilindungi

Di dalam direktori yang dapat ditulisi oleh perintah yang di-sandbox, sandbox tetap menolak penulisan ke file tempat Claude Code memuat konfigurasi dan kode. Perintah yang dapat mengedit file tersebut dapat memberikan izin kepada dirinya sendiri, atau menambahkan hook atau server MCP yang dijalankan Claude Code di luar sandbox. Sistem izin memiliki jalur yang dilindungi tersendiri, yang mengontrol apa yang disetujui Claude Code sebelum sebuah tool berjalan; daftar milik sandbox berlaku untuk perintah yang sudah berjalan. Daftar ini mencakup empat kelompok jalur:

Di direktori kerja Anda dan direktori di atasnya: file pengaturan .claude, direktori .claude/skills, .claude/agents, .claude/commands, dan .claude/hooks, .mcp.json, serta file yang dijalankan Claude Code dengan sendirinya, seperti .claude/workflows dan .claude/scheduled_tasks.json
Hanya di direktori kerja Anda: file startup shell seperti .bashrc dan .zshrc, .gitconfig, direktori .vscode dan .idea, serta hooks dan config di dalam .git
File yang akan mengubah direktori kerja Anda menjadi repositori git bare: HEAD, objects, dan refs di tingkat teratas, ditambah entri config dan hooks yang sudah ada di sana ketika terdapat HEAD di sampingnya. File bernama config ditolak bahkan tanpa HEAD. Di Linux dan WSL2, sandbox menghapus file HEAD atau direktori objects atau refs di tingkat teratas yang muncul saat perintah yang di-sandbox sedang berjalan
Di ~/.claude, atau direktori yang ditunjuk oleh CLAUDE_CONFIG_DIR: sebagian besar isinya, ditambah ~/.claude.json dan penyimpanan kredensial .credentials.json

Jika sebuah symlink muncul di jalur file pengaturan yang dilindungi selama sesi, sandbox juga menolak penulisan ke file yang ditunjuknya, dimulai dari perintah berikutnya.

Tidak ada cara untuk mengecualikan salah satu jalur ini: entri allowWrite atau aturan izin Edit yang mencakup jalur tersebut tidak mencabut perlindungannya. Satu-satunya cara untuk mematikan perlindungan adalah filesystem.disabled, yang mematikan isolasi sistem file untuk setiap jalur. Untuk melihat sebagian besar jalur ini sebagaimana diterapkan di mesin Anda, jalankan /sandbox dan buka tab Config, yang mencantumkannya di bawah Denied within allowed, bercampur dengan entri denyWrite Anda sendiri.

Jika git merge atau git checkout gagal dengan unable to unlink old pada salah satu jalur ini, lihat Perintah git gagal dengan unable to unlink old.

Isolasi jaringan

Perintah yang di-sandbox tidak memiliki rute langsung ke jaringan:

Linux dan WSL2: perintah berjalan di network namespace terpisah yang tidak memiliki koneksi ke jaringan Anda
macOS: framework sandbox Seatbelt secara default memblokir koneksi selain koneksi ke proxy sandbox

Claude Code menjalankan proxy sandbox di mesin Anda, di luar sandbox, dan mengarahkan perintah ke proxy tersebut dengan HTTP_PROXY, HTTPS_PROXY, ALL_PROXY, dan environment variable terkait. Proxy memeriksa hostname setiap koneksi terhadap domain yang diizinkan dan ditolak milik Anda.

Apa yang dapat dijangkau oleh sebuah tool bergantung pada apakah tool tersebut menggunakan proxy:

Tool yang membaca variabel proxy: curl, npm, git melalui HTTPS, dan tool serupa dapat terhubung setelah host-nya diizinkan. Entri allowedDomains tanpa port mengizinkan setiap port pada host tersebut
Tool yang mengabaikan variabel proxy: ssh biasa, sebagian besar driver database, dan tool serupa tidak dapat terhubung, bahkan ke host yang diizinkan. Lihat Klien database atau tool non-HTTP lainnya gagal menjangkau host yang diizinkan
Apa pun yang bukan TCP: UDP, HTTP/3 melalui QUIC, dan tool ICMP seperti ping tidak dapat keluar dari sandbox

Pengaturan dan perilaku berikut mengontrol host mana yang diizinkan oleh proxy:

Pembatasan domain: domain yang diizinkan milik Anda awalnya kosong. Host di luar domain yang diizinkan menjelaskan apa yang terjadi saat pertama kali sebuah perintah memerlukan domain baru.
Pilihan persetujuan: jika Anda memilih Yes saat diminta, Claude Code mengizinkan host tersebut selama sisa sesi saat ini. Jika Anda memilih "Yes, and don't ask again", Claude Code menyimpan aturan izin WebFetch(domain:...) ke pengaturan lokal Anda, sehingga host tetap diizinkan di sesi mendatang. Selama sandbox bersifat wajib oleh admin, Claude Code menyimpan aturan tersebut ke pengaturan pengguna Anda, yang berlaku di setiap proyek.
Domain yang diizinkan sebelumnya: izinkan domain terlebih dahulu dengan allowedDomains untuk menghindari permintaan persetujuan sepenuhnya. Claude Code juga mengizinkan terlebih dahulu domain dari aturan izin WebFetch(domain:...), seperti yang dijelaskan dalam Aturan izin.
Allowlist ketat: jika Anda mengatur strictAllowlist ke true di pengaturan pengguna, pengaturan terkelola, atau pengaturan CLI --settings, Claude Code menolak akses perintah yang di-sandbox ke host apa pun di luar allowlist alih-alih meminta persetujuan. Allowlist terdiri dari allowedDomains ditambah domain dari aturan izin WebFetch(domain:...), atau hanya entri pengaturan terkelola ketika allowManagedDomainsOnly diatur. Penguncian yang berlaku tanpa sandbox wajib oleh admin menjelaskan entri milik repositori. Claude Code hanya menerapkan ini untuk perintah yang di-sandbox; tool dalam proses seperti WebFetch tetap mengikuti aturan izin masing-masing. Mengaturnya di .claude/settings.json atau .claude/settings.local.json milik repositori tidak berpengaruh. Memerlukan Claude Code v2.1.219 atau yang lebih baru.
Penguncian terkelola: jika allowManagedDomainsOnly diatur di pengaturan terkelola, domain yang tidak diizinkan diblokir secara otomatis alih-alih meminta persetujuan, dan hanya aturan izin allowedDomains dan WebFetch(domain:...) dari pengaturan terkelola yang dipatuhi.
Proxy perusahaan: ketika jaringan Anda mengharuskan lalu lintas keluar melewati proxy perusahaan, atur HTTPS_PROXY, HTTP_PROXY, dan NO_PROXY seperti yang dijelaskan dalam konfigurasi proxy, di blok env pengaturan Anda agar agent latar belakang juga mendapatkannya, atau di environment tempat Anda meluncurkan Claude Code. Claude Code menerapkan allowlist domain lalu meneruskan koneksi yang diizinkan melalui proxy upstream tersebut. URL proxy http:// dan https:// dapat digunakan, dengan autentikasi basic di URL jika Anda memerlukannya.

Dalam aturan WebFetch(domain:...), sandbox mematuhi dua bentuk wildcard: *. di awal, seperti *.example.com, dan * tunggal. Bentuk * tunggal memerlukan Claude Code v2.1.186 atau yang lebih baru. Wildcard di posisi lain, seperti WebFetch(domain:example.*), tetap cocok dengan pengambilan tetapi tidak berpengaruh pada perintah yang di-sandbox.

Host di luar domain yang diizinkan

Ketika perintah yang di-sandbox terhubung ke host yang tidak ada dalam domain yang diizinkan milik Anda, perintah tetap berada di sandbox dan menunggu keputusan. Dalam sesi terminal interaktif, keputusan bergantung pada mode izin Anda:

Mode izin	Apa yang terjadi pada koneksi
Mode `bypassPermissions`, dan plan mode dengan bypass permissions tersedia	Diizinkan tanpa permintaan persetujuan
Mode manual, mode `acceptEdits`, dan plan mode dalam kondisi lainnya	Anda mendapatkan permintaan persetujuan
Auto mode	Ditolak kecuali perintah tersebut mencantumkan host dan pengklasifikasi menyetujui daftarnya
Mode `dontAsk`	Ditolak

Dengan strictAllowlist atau allowManagedDomainsOnly diaktifkan, proxy sandbox bawaan menolak koneksi di setiap mode izin. Dalam mode bypassPermissions, host di luar domain yang diizinkan milik Anda diizinkan kecuali salah satu pengaturan tersebut diaktifkan. Jalan keluar retry tanpa sandbox menjelaskan kapan sebuah perintah dapat keluar dari sandbox dalam mode tersebut. Koneksi ke host di deniedDomains juga ditolak di setiap mode izin.

Hostname yang di-resolve ke alamat lokal

Setelah sebuah hostname lolos allowlist, proxy sandbox me-resolve-nya dan menolak koneksi ketika nama tersebut hanya di-resolve ke alamat lokal. Alamat lokal mencakup alamat loopback seperti 127.0.0.1, alamat link-local seperti endpoint metadata cloud 169.254.169.254, dan alamat yang ditetapkan ke mesin Anda sendiri. Nama localhost dan *.localhost diizinkan untuk di-resolve ke loopback.

Hostname intranet yang diizinkan yang di-resolve ke rentang privat seperti 10.0.0.0/8 dapat terhubung. Untuk membiarkan sebuah nama di-resolve ke alamat yang ditolak, tambahkan alamat IP tersebut ke allowedDomains, seperti "127.0.0.1:8080".

Pemeriksaan ini berlaku untuk hostname. Domain yang diizinkan dan mode izin Anda menentukan koneksi ke alamat IP. Proxy juga melewati pemeriksaan untuk koneksi yang dikirimkannya melalui proxy perusahaan upstream, karena proxy tersebut yang me-resolve nama.

Domain yang diizinkan per perintah dalam auto mode

Dalam auto mode dengan sandboxing aktif, Claude menyebutkan host yang diperlukan sebuah perintah pada perintah itu sendiri alih-alih memicu persetujuan jaringan untuk setiap koneksi. Setiap perintah Bash, PowerShell, atau Monitor yang berjalan di sandbox dapat membawa daftar host di luar allowlist sandbox: domain seperti registry.npmjs.org, wildcard seperti *.pythonhosted.org, atau alamat IP, masing-masing dengan :port opsional. Pengklasifikasi meninjau host tersebut bersama dengan perintahnya. Memerlukan Claude Code v2.1.271 atau yang lebih baru.

Daftar yang disetujui membuka host tersebut hanya untuk satu perintah itu, selama perintah tersebut berjalan. Tidak ada yang ditambahkan ke host yang diizinkan dalam sesi Anda atau ke pengaturan Anda; perintah berikutnya menyebutkan host-nya sendiri.

Perintah yang membawa host dikirim ke pengklasifikasi alih-alih disetujui oleh aturan izin atau mode auto-allow milik sandbox. Jika sebuah aturan ask memaksa permintaan persetujuan untuk perintah tersebut, dialog izin di terminal Anda mencantumkan host di sampingnya, dan menyetujui di sana mencakup keduanya.

Daftar per perintah hanya memperluas apa yang ditolak sandbox secara default. Entri deniedDomains tetap memblokir. Ketika strictAllowlist atau allowManagedDomainsOnly mengunci allowlist, Claude Code menolak daftar per perintah.

Selama daftar per perintah berlaku, Claude Code menolak koneksi ke host yang tidak dicantumkan oleh perintah mana pun yang disetujui, tanpa permintaan persetujuan atau pemeriksaan pengklasifikasi. Penolakan tersebut menyebutkan host dalam hasil perintah, dan Claude menjalankan ulang perintah dengan host tersebut ditambahkan.

Alamat IPv6 dalam daftar domain

Untuk mencocokkan alamat IPv6 di allowedDomains, deniedDomains, atau aturan WebFetch(domain:...), tulis alamat tersebut dalam kurung siku: "[::1]" cocok dengan alamat tersebut di setiap port, dan "[::1]:443" hanya cocok dengannya di port 443. Bentuk berkurung siku memerlukan Claude Code v2.1.229 atau yang lebih baru.

Entri tanpa kurung siku seperti ::1:443 bersifat ambigu antara sebuah alamat dan alamat yang diikuti port:

Daftar penolakan: Claude Code menolak setiap pembacaan yang dapat di-parse dari entri tersebut, sehingga pembacaan mana pun yang Anda maksud akan diblokir. Untuk entri tanpa pembacaan yang dapat di-parse, Claude Code tidak memblokir apa pun
Daftar izin: Claude Code tidak pernah mengizinkan lebih dari yang Anda tulis. Claude Code menulis ulang entri ambigu ke pembacaan host-dan-port ketika pembacaan tersebut dapat di-parse dengan bersih, dan dapat membuang entri tersebut sepenuhnya alih-alih memperluas allowlist

Untuk menemukan entri yang ambigu, jalankan claude doctor di terminal Anda dan cari peringatan Sandbox network domain entries have unreliable spellings. Tulis ulang setiap entri yang ambigu dalam bentuk berkurung siku.

Penerapan tingkat OS

Tool Bash yang di-sandbox menggunakan primitif keamanan sistem operasi:

macOS: menggunakan Seatbelt untuk penerapan sandbox
Linux: menggunakan bubblewrap untuk isolasi
WSL2: menggunakan bubblewrap, sama seperti Linux

Anda juga dapat menjalankan paket @anthropic-ai/sandbox-runtime secara mandiri untuk membungkus proses Claude Code. Lihat Sandbox runtime.

Bagaimana sandboxing berhubungan dengan izin dan mode izin

Sandboxing, permission rules, dan permission modes adalah lapisan komplementer. Bagian di bawah mencakup bagaimana sandbox berinteraksi dengan masing-masing.

Aturan izin

Aturan izin dan sandboxing mengontrol hal yang berbeda:

Aturan izin mengontrol alat mana yang dapat digunakan Claude Code dan dievaluasi sebelum alat apa pun berjalan. Mereka berlaku untuk semua alat: Bash, Read, Edit, WebFetch, MCP, dan lainnya, kecuali bahwa aturan deny atau ask tidak dapat memblokir EndConversation sementara alat lain tetap ada.
Sandboxing menyediakan penegakan tingkat OS yang membatasi apa yang dapat diakses perintah Bash pada tingkat filesystem dan jaringan. Ini hanya berlaku untuk perintah Bash, PowerShell, dan Monitor serta proses anak mereka.

Kedua lapisan juga berbeda dalam cara penegakan mereka. Claude Code mengevaluasi keputusan izin sebelum perintah berjalan, berdasarkan string perintah dan, dalam mode auto, penilaian classifier terpisah tentang apakah perintah aman. Sistem operasi memberlakukan batas sandbox pada proses yang berjalan, sehingga berlaku terlepas dari apa yang dipilih model untuk dijalankan dan bahkan jika perintah yang diizinkan melakukan lebih dari nama yang disarankan.

Pembatasan filesystem dan jaringan dikonfigurasi melalui pengaturan sandbox dan aturan izin:

Pengaturan atau aturan	Apa yang dilakukannya
`sandbox.filesystem.allowWrite`	Memberikan akses tulis subprocess ke jalur di luar direktori kerja
`sandbox.filesystem.denyWrite` dan `sandbox.filesystem.denyRead`	Memblokir akses subprocess ke jalur tertentu
`sandbox.filesystem.allowRead`	Mengizinkan kembali pembacaan jalur tertentu dalam wilayah `denyRead`
`sandbox.filesystem.disabled`	Mematikan lapisan filesystem sepenuhnya sambil mempertahankan isolasi jaringan
Aturan izin `Edit`	Memberikan akses tulis ke jalur tertentu, dengan cara yang sama seperti `sandbox.filesystem.allowWrite`
Aturan tolak `Read` dan `Edit`	Memblokir akses ke file atau direktori tertentu
Aturan izin dan tolak `WebFetch(domain:...)`	Mengontrol akses domain
Sandbox `allowedDomains`	Mengontrol domain mana yang dapat dijangkau perintah Bash
Sandbox `deniedDomains`	Memblokir domain tertentu bahkan ketika wildcard `allowedDomains` yang lebih luas akan sebaliknya mengizinkannya

Jalur dan domain dari pengaturan sandbox dan aturan izin digabungkan bersama ke dalam konfigurasi sandbox akhir.

Direktori contoh repositori claude-code mencakup konfigurasi pengaturan pemula untuk skenario penyebaran umum, termasuk contoh khusus sandbox. Gunakan ini sebagai titik awal dan sesuaikan dengan kebutuhan Anda.

Mode izin

/sandbox bukan permission mode. Mode izin memutuskan apakah panggilan alat berjalan dan apakah Anda diminta terlebih dahulu, sementara sandbox membatasi apa yang dapat diakses perintah Bash setelah berjalan. Mereka berbeda dalam apa yang mereka kontrol dan apa yang menggantikan prompt per-aksi:

	Apa yang dikontrol	Apa yang menggantikan prompt
`/sandbox`	Apa yang dapat diakses perintah Bash setelah berjalan	Batas sandbox itu sendiri, dalam mode auto-allow
Auto mode	Apakah setiap panggilan alat berjalan	Classifier yang meninjau tindakan
`--dangerously-skip-permissions`	Apakah setiap panggilan alat berjalan	Tidak ada. Pemeriksaan Protected path juga dilewati; tindakan yang tidak ada mode auto-approve masih berlaku

Mode auto-allow sandbox terpisah dari auto mode: auto-allow menyetujui perintah Bash karena batas sandbox memuatnya, sementara auto mode menggunakan classifier untuk meninjau tindakan. Keduanya bekerja secara independen dan dapat dikombinasikan, dengan pengecualian yang tercantum di bawah Sandbox modes. Untuk memilih batas isolasi untuk run tanpa pengawasan, lihat Sandbox environments. Untuk tabel pasangan mode izin dan sandbox umum dengan flag yang memulai masing-masing, lihat Common setups.

Konfigurasi sandbox untuk organisasi Anda

Administrator dapat memerlukan sandboxing untuk setiap pengguna, mencegah pengembang memperluas kebijakan, dan merutekan lalu lintas sandbox melalui proxy perusahaan.

Memberlakukan sandboxing dengan pengaturan terkelola

Untuk memerlukan sandbox untuk setiap pengembang, berikan kunci sandbox melalui managed settings, baik sebagai file yang dikelola oleh MDM Anda atau melalui server-managed settings di claude.ai.

Konfigurasi pengaturan terkelola berikut mengaktifkan sandbox, menolak untuk memulai Claude Code ketika platform tidak didukung atau ada dependensi yang hilang, dan mencegah model mencoba ulang perintah di luar sandbox:

{
  "sandbox": {
    "enabled": true,
    "failIfUnavailable": true,
    "allowUnsandboxedCommands": false
  }
}

Dua kunci di luar enabled mengontrol apa yang terjadi ketika sandbox tidak dapat menjalankan perintah:

failIfUnavailable: dependensi yang hilang seperti bubblewrap di Linux memblokir Claude Code dari memulai alih-alih kembali ke eksekusi unsandboxed
allowUnsandboxedCommands: false: Claude Code mengabaikan escape hatch dangerouslyDisableSandbox, sehingga ketika perintah gagal di bawah sandbox, Claude tidak dapat mencoba ulangnya tanpa sandbox

Pertimbangkan penambahan berikut bersama keduanya:

Tambahkan excludedCommands untuk alat apa pun yang disetujui organisasi yang harus berjalan tanpa isolasi, karena konfigurasi ini mencegah pengaturan repositori mengeluarkan perintah dari sandbox
Tambahkan entri sandbox.credentials untuk direktori kredensial seperti ~/.aws dan ~/.ssh dan untuk environment variable rahasia, karena kebijakan pembacaan default masih mengizinkannya

Konfigurasi ini melakukan sandboxing pada perintah yang dijalankan Claude. Pengembang masih dapat mengetik perintah di prompt shell-mode ! dan menjalankannya di luar sandbox, dengan akses yang sama yang mereka miliki di terminal apa pun di luar Claude Code. Lihat mode sandbox ketat untuk sesi di mana perintah yang diketik dijalankan dengan sandbox.

Sandbox tidak berjalan di Windows asli, sehingga dengan failIfUnavailable diatur, Claude Code keluar saat startup di mesin tersebut. Jika armada Anda mencakup host Windows, Anda dapat:

Memberikan konfigurasi berdasarkan sistem operasi: terapkan melalui MDM Anda atau sebagai file pengaturan terkelola hanya di mesin macOS dan Linux. Server-managed settings berlaku untuk semua pengguna di organisasi
Memindahkan pengguna Windows ke lingkungan yang didukung: minta mereka menjalankan Claude Code di dalam WSL2 atau container

Cegah pengembang memperluas kebijakan

Ketika pengaturan terkelola menetapkan kunci Boolean seperti enabled atau failIfUnavailable, Claude Code menggunakan nilai terkelola dan mengabaikan apa pun yang ditetapkan pengembang secara lokal. Untuk kunci array seperti allowRead, Claude Code menggabungkan entri dari cakupan yang dimuat sesi, sehingga pengembang dapat menambahkan entri yang memperluas kebijakan kecuali ada kunci pengunci yang mencakup kunci tersebut.

Kecuali pengaturan terkelola menetapkannya, pengaturan pengguna milik pengembang atau --settings dapat mengaktifkan kunci berikut. .claude/settings.json milik repositori juga dapat melakukannya, kecuali sandbox bersifat diwajibkan admin. Masing-masing melemahkan sandbox, jadi atur ke false dalam pengaturan terkelola jika Anda tidak ingin kunci tersebut digunakan:

enableWeakerNestedSandbox
enableWeakerNetworkIsolation
network.allowAllUnixSockets
network.allowLocalBinding
allowAppleEvents, yang tidak dapat diaktifkan oleh repositori

Atur allowManagedReadPathsOnly ke true dalam pengaturan terkelola sehingga hanya entri allowRead dari pengaturan terkelola yang dihormati. Ini mencegah pengembang memperluas akses baca di luar jalur yang disetujui organisasi.

Untuk mengunci domain jaringan ke nilai terkelola dengan cara yang sama, atur allowManagedDomainsOnly. Dengan penguncian ini aktif, hanya pengaturan terkelola yang dapat menetapkan port proxy.

Ketika pengaturan terkelola mengonfigurasi sandbox.filesystem atau mencantumkan entri sandbox.credentials.files apa pun dengan "mode": "deny", hanya pengaturan terkelola yang dapat mengatur filesystem.disabled, sehingga pengembang tidak dapat mematikan pembatasan filesystem yang diterapkan administrator. Entri mask yang valid tidak mengunci kunci tersebut. Lihat Which settings can disable it.

Pengaturan repositori di bawah sandbox yang diwajibkan admin

Sandbox bersifat diwajibkan admin selama salah satu pengaturan berikut berlaku:

allowUnsandboxedCommands diatur ke false dalam pengaturan terkelola, atau dengan flag --settings kecuali pengaturan terkelola mengaturnya ke true
allowManagedDomainsOnly diatur ke true dalam pengaturan terkelola

Pengaturan ini tidak mengaktifkan sandbox, jadi atur juga enabled.

Selama sandbox diwajibkan admin, Claude Code mengambil pengaturan yang melonggarkannya hanya dari pengaturan terkelola, flag --settings, dan ~/.claude/settings.json milik setiap pengembang. Claude Code mengabaikan pengaturan berikut di .claude/settings.json dan .claude/settings.local.json milik repositori:

Pengaturan repositori	Apa yang diabaikan Claude Code
`excludedCommands`, `ignoreViolations`, `network.allowedDomains`, `network.allowUnixSockets`, `network.allowMachLookup`, `network.httpProxyPort`, `network.socksProxyPort`	Setiap entri
`filesystem.allowWrite`, aturan izinkan `Edit(...)`, `permissions.additionalDirectories`	Akses tulis yang diberikan setiap entri kepada perintah yang di-sandbox. Tool file Claude tetap mengikuti aturan `Edit(...)` dan direktori tambahan
Aturan izinkan `WebFetch(domain:...)`	Host yang ditambahkan setiap aturan ke allowlist sandbox. Tool WebFetch tetap mengikuti aturan tersebut
`enableWeakerNestedSandbox`, `enableWeakerNetworkIsolation`, `network.allowAllUnixSockets`, `network.allowLocalBinding`	`true`. Nilai `false` tetap berlaku
`enabled`, `failIfUnavailable`	`false`, ketika `~/.claude/settings.json` milik pengembang menetapkan `true`
`filesystem.allowRead`	Entri pada atau di bawah jalur yang dilarang untuk dibaca oleh pengaturan terkelola, `--settings`, atau pengaturan pengguna, atau glob yang dapat mencocokkan salah satunya

Pengaturan berikut tetap berlaku selama sandbox diwajibkan admin:

Di file repositori: entri deny dan nilai autoAllowBashIfSandboxed. Atur kunci tersebut dalam pengaturan terkelola untuk mencegah repositori mengubahnya
Di pengaturan milik pengembang sendiri: pengaturan dalam tabel tetap berlaku dari ~/.claude/settings.json atau --settings, kecuali penguncian khusus terkelola seperti allowManagedDomainsOnly mencakupnya. Sebagian besar di antaranya, seperti excludedCommands dan filesystem.allowWrite, tidak memiliki penguncian khusus terkelola

Konfigurasi di bawah Memberlakukan sandboxing dengan pengaturan terkelola membuat sandbox diwajibkan admin. Tambahkan entri excludedCommands, allowWrite, dan socket yang dibutuhkan alat yang Anda setujui ke pengaturan terkelola, karena repositori tidak dapat menyediakannya.

Memerlukan Claude Code v2.1.285 atau lebih baru. Dari v2.1.282 hingga v2.1.284, pengaturan yang sama membuat Claude Code mengabaikan entri excludedCommands milik repositori.

Penguncian yang berlaku tanpa sandbox yang diwajibkan admin

Beberapa pengaturan membuat Claude Code mengabaikan kunci repositori yang secara langsung menimpa satu pembatasan, bahkan ketika sandbox tidak diwajibkan admin. Masing-masing memiliki efek ini hanya ketika Anda mengaturnya di file yang disebutkan dalam barisnya, dan pengaturan sandbox lain milik repositori tetap berlaku. Memerlukan Claude Code v2.1.285 atau lebih baru.

Pengaturan	Tempat Anda mengaturnya	Apa yang diabaikan Claude Code dalam pengaturan repositori
`network.deniedDomains` atau aturan deny `WebFetch(domain:...)`	Pengaturan terkelola, `--settings`	`httpProxyPort` dan `socksProxyPort`
`network.strictAllowlist`	Pengaturan terkelola, `--settings`, pengaturan pengguna	Port proxy, `allowedDomains`, dan aturan izinkan `WebFetch(domain:...)`
`filesystem.denyRead`, aturan deny `Read(...)`, atau entri `credentials.files`	Pengaturan terkelola, `--settings`	Entri `allowRead`, `allowWrite`, izinkan `Edit(...)`, atau `additionalDirectories` pada atau di bawah jalur yang dilarang untuk dibaca oleh pengaturan terkelola, `--settings`, atau pengaturan pengguna, atau glob yang dapat mencocokkan salah satunya

Penguncian ini mengubah apa yang dapat dijangkau oleh perintah yang di-sandbox. Tool WebFetch dan tool file Claude tetap mengikuti aturan dan direktori tambahan milik repositori.

Konfigurasi proxy khusus

Untuk memeriksa, memfilter, atau mencatat lalu lintas sandbox dengan alat Anda sendiri, ganti proxy sandbox bawaan dengan proxy yang Anda jalankan di mesin yang sama.

Untuk merutekan lalu lintas sandbox melalui proxy perusahaan di tempat lain dalam jaringan Anda, atur HTTPS_PROXY sebagai gantinya, seperti yang dijelaskan entri Corporate proxy di bawah Network isolation. Dengan cara itu, allowlist Claude Code tetap berlaku.

Untuk mengarahkan perintah yang di-sandbox ke proxy Anda, atur port localhost yang didengarkannya dalam sandbox settings:

{
  "sandbox": {
    "network": {
      "httpProxyPort": 8080,
      "socksProxyPort": 8081
    }
  }
}

Jika Anda mengatur port dan juga mengatur HTTPS_PROXY atau HTTP_PROXY, Claude Code tidak meneruskan apa yang dikirim perintah yang di-sandbox ke proxy Anda kepada proxy yang disebutkan oleh variabel tersebut. Untuk menjangkau proxy perusahaan, konfigurasikan proxy Anda sendiri agar meneruskan ke sana.

File mana yang dapat mengatur port bergantung pada pengaturan sandbox Anda yang lain:

allowManagedDomainsOnly aktif: hanya pengaturan terkelola
Sandbox diwajibkan admin, atau penguncian jaringan yang lebih sempit berlaku: pengaturan terkelola, --settings, dan pengaturan pengguna
Selain itu: file pengaturan apa pun

Claude Code mengabaikan port yang diatur di tempat lain. Sebelum v2.1.285, file pengaturan apa pun dapat mengatur port.

Pemecahan masalah

Beberapa perintah gagal di dalam sandbox meskipun bekerja di luar itu. Temukan judul yang sesuai dengan gejala atau pesan kesalahan Anda.

Jika sandbox organisasi Anda bersifat wajib oleh admin, Claude Code mengabaikan pengaturan yang disebutkan oleh perbaikan ini di file pengaturan proyek, jadi simpan pengaturan tersebut di ~/.claude/settings.json, tempat pengaturan itu berlaku di setiap proyek. Jika suatu perbaikan tetap tidak berpengaruh, pengaturan terkelola organisasi Anda mungkin menetapkan kunci tersebut.

Perbaikan yang menambahkan pola excludedCommands menghapus sandbox dari perintah yang cocok dengan pola tersebut. Lihat apa yang dapat dilakukan perintah yang dikecualikan.

Perintah gagal dengan kesalahan host-not-allowed

Banyak tool CLI perlu menjangkau host tertentu. Setujui host saat diminta, atau tambahkan ke allowedDomains. Jika organisasi Anda mengunci allowlist dengan allowManagedDomainsOnly, tidak ada permintaan izin, jadi minta administrator Anda untuk menambahkan host tersebut.

`jest` hang atau gagal

watchman tidak kompatibel dengan sandbox. Jalankan jest --no-watchman sebagai gantinya.

Go-based CLIs gagal verifikasi TLS di macOS

Tool seperti gh, gcloud, dan terraform mungkin gagal verifikasi TLS di bawah Seatbelt. Untuk menjalankan tool ini di luar sandbox, tambahkan pola untuk setiap tool, seperti gh *, ke excludedCommands. Tool tersebut kemudian berjalan dengan akses penuh Anda dan kredensial yang tersimpan. Jika Anda menggunakan httpProxyPort dengan proxy MITM dan CA khusus, atur enableWeakerNetworkIsolation ke true sebagai gantinya.

`open`, `osascript`, atau alur autentikasi berbasis browser gagal dengan kesalahan `-600` di macOS

Sandbox memblokir Apple Events secara default. Atur allowAppleEvents ke true dalam pengaturan pengguna, terkelola, atau CLI Anda untuk mengizinkannya. Claude Code mengabaikan kunci ini dalam pengaturan proyek.

Mengaktifkan allowAppleEvents menghilangkan isolasi eksekusi kode, karena perintah sandboxed kemudian dapat meluncurkan aplikasi lain tanpa sandbox tanpa permintaan izin pengguna, dan dapat mengirim perintah AppleScript ke aplikasi yang berjalan, tunduk pada permintaan persetujuan otomasi macOS (TCC). Alternatifnya, tambahkan pola seperti open * ke excludedCommands. Setiap panggilan open kemudian melalui alur izin, dan open dapat meluncurkan file atau aplikasi apa pun, termasuk yang ditulis oleh Claude.

Perintah `docker` gagal

docker tidak kompatibel dengan sandbox. Keluarkan perintah docker yang Anda butuhkan dari sandbox dengan pola excludedCommands seperti docker compose *. Menjalankan perintah di luar sandbox dengan excludedCommands menjelaskan apa yang dapat dijangkau oleh perintah docker yang dikecualikan. Pola yang lebih sempit mengeluarkan lebih sedikit perintah dari sandbox.

`pbcopy`, `xclip`, atau `wl-copy` tidak memperbarui clipboard

Utilitas clipboard pbcopy, xclip, dan wl-copy dapat gagal menjangkau clipboard sistem dari dalam sandbox, dalam hal ini teks yang dialirkan ke dalamnya tidak tiba.

Untuk menempatkan output Claude di clipboard Anda, minta Claude untuk mencetaknya dalam responsnya, kemudian jalankan /copy. /copy menulis ke clipboard dari proses Claude Code daripada dari perintah sandboxed.

Ketika Claude mengalirkan teks ke salah satu tool ini, menambahkan tool ke excludedCommands tidak mengeluarkan panggilan itu dari sandbox dengan sendirinya.

Perintah git gagal dengan `unable to unlink old`

git merge, git checkout, dan perintah serupa gagal dengan unable to unlink old ketika mereka perlu mengganti file yang penulisannya ditolak oleh sandbox. Di Linux dan WSL2 kesalahan berakhir dengan Read-only file system. File tersebut dapat berada di salah satu lokasi berikut:

Di bawah jalur yang dilindungi seperti .claude/skills
Di bawah salah satu entri denyWrite Anda
Di luar direktori yang sama sekali diizinkan sandbox untuk ditulisi oleh perintah

Setelah kegagalan, Claude mungkin menawarkan untuk menjalankan kembali perintah di luar sandbox. Setujui retry itu, atau jalankan perintah git sendiri di terminal lain. Jika Anda telah menetapkan allowUnsandboxedCommands ke false, Claude tidak dapat menawarkan retry, jadi jalankan perintah sendiri.

Bubblewrap gagal memulai di dalam container

Dalam container tanpa privilege, bubblewrap tidak dapat memasang filesystem /proc baru, sehingga perintah sandboxed gagal dengan kesalahan bwrap seperti Can't mount proc on /newroot/proc: Operation not permitted. Atur enableWeakerNestedSandbox ke true sehingga sandbox melakukan bind-mount terhadap /proc yang sudah ada milik container sebagai gantinya. Hanya gunakan pengaturan ini ketika container luar sudah menyediakan batas isolasi yang Anda butuhkan, karena pengaturan ini mengekspos informasi proses ke perintah sandboxed yang akan disembunyikan oleh mount /proc baru.

File read-only 0-byte muncul di jalur pengaturan `.claude`, dan "Ya, dan jangan tanya lagi" tidak menyimpan

Di Linux dan WSL2, sandbox menahan penolakan penulisan pada file yang belum ada dengan membuat placeholder read-only 0-byte di sana sementara perintah sandboxed berjalan. Sandbox menghapus placeholder setelahnya. Jika sesi dihentikan paksa sebelum pembersihan itu berjalan, misalnya oleh SIGKILL, placeholder tetap tertinggal. Sesi berikutnya mengikat placeholder tersebut sebagai read-only lagi pada setiap awal, sehingga penulisan pengaturan seperti menyimpan pilihan izin gagal di jalur tempat placeholder masih ada.

Jalankan claude doctor di terminal Anda untuk membuat daftar file placeholder yang tersisa. Peringatan Stale sandbox mask files left by a killed session menyebutkan beberapa di antaranya dan menghitung sisanya. Hapus setiap file dengan rm sementara tidak ada sesi Claude Code lain yang berjalan di proyek itu. Sebelum v2.1.257, Claude Code meninggalkan placeholder yang sama tanpa menandainya.

`git` melalui SSH gagal saat sandbox aktif

Di macOS, git fetch, git pull, dan git push terhadap remote SSH gagal di dalam sandbox bahkan ketika host diizinkan. Di Linux dan WSL2, perintah tersebut berfungsi setelah host diizinkan. Claude Code menyalurkan koneksi SSH git melalui proxy sandbox, dan tunnel macOS tidak dapat melakukan autentikasi ke proxy tersebut.

Di Linux dan WSL2, periksa hal-hal berikut jika koneksi masih gagal:

Host diizinkan pada port 22: entri allowedDomains tanpa port, seperti "git.example.com", mencakupnya
Proxy perusahaan Anda mengizinkan port 22: jika jaringan Anda memerlukan proxy upstream, tunnel juga melewatinya
Kunci dapat dibaca sebagai file: sandbox dapat memblokir socket ssh-agent, dan entri denyRead atau credentials untuk ~/.ssh menyembunyikan file kunci Anda

Di macOS, ubah remote ke HTTPS, yang memerlukan kredensial HTTPS seperti personal access token:

git remote set-url origin https://git.example.com/example-org/example-repo.git

Jika Anda harus mempertahankan remote SSH, keluarkan perintah jaringan git dari sandbox dengan excludedCommands:

{
  "sandbox": {
    "excludedCommands": ["git fetch *", "git pull *", "git push *"]
  }
}

Entri ini cocok dengan git push origin main. Panggilan yang menambahkan cd, menggunakan git -C, atau berisi command substitution tetap berada di dalam sandbox. Perintah git yang dikecualikan dapat menjangkau host mana pun, tidak hanya yang ada di allowedDomains.

ssh, scp, dan rsync biasa melalui SSH gagal karena alasan yang diberikan oleh entri klien database.

Klien database atau tool non-HTTP lainnya gagal menjangkau host yang diizinkan

Tool yang mengabaikan environment variable proxy tidak dapat terhubung dari dalam sandbox, bahkan ke host yang ada di allowedDomains. Perintah sandboxed tidak memiliki rute langsung ke jaringan, sehingga tool yang membuka koneksinya sendiri akan gagal. Sebagian besar driver database, ssh biasa, dan tool yang menggunakan UDP berperilaku seperti ini.

Kegagalan tampak seperti kesalahan jaringan atau resolusi nama:

macOS: Operation not permitted, atau kesalahan resolusi nama seperti Could not resolve host
Linux dan WSL2: Network is unreachable, atau kesalahan resolusi nama seperti Temporary failure in name resolution

Tool yang menggunakan proxy gagal dengan cara berbeda ketika host-nya tidak diizinkan. Anda mendapatkan permintaan izin jaringan, atau tool menerima respons 403 dari proxy.

Untuk memungkinkan tool terhubung, jalankan perintah yang memerlukannya di luar sandbox dengan excludedCommands. Contoh ini mengecualikan satu skrip dan menambahkan aturan ask sehingga Anda menyetujui setiap eksekusi:

{
  "sandbox": {
    "excludedCommands": ["python scripts/load_orders.py *"]
  },
  "permissions": {
    "ask": ["Bash(python scripts/load_orders.py *)"]
  }
}

Skrip berjalan dengan akses penuh Anda, dan Claude dapat mengedit skrip yang berada di dalam direktori kerja Anda, jadi tinjau skrip tersebut saat permintaan izin muncul.

Perintah gagal menjangkau server di localhost

Secara default, perintah sandboxed tidak dapat terhubung langsung ke server yang berjalan di mesin Anda di luar sandbox, seperti dev server atau database dalam container. Apa yang dapat Anda ubah bergantung pada platform Anda:

macOS: atur network.allowLocalBinding ke true. Perintah sandboxed kemudian dapat mendengarkan pada port jaringan dan terhubung ke port mana pun di localhost, yang mencakup setiap layanan lain yang mendengarkan di sana. Layanan localhost yang tidak memerlukan autentikasi, seperti debugger, kemudian dapat bertindak atas nama perintah di luar sandbox, dan perintah yang mendengarkan pada alamat non-loopback menerima koneksi dari mesin lain
Linux dan WSL2: localhost milik perintah sandboxed bersifat privat untuk perintah tersebut. Perintah dapat mendengarkan pada port dan menjangkau server yang dimulainya sendiri. Koneksi langsung ke localhost atau 127.0.0.1 tidak menjangkau server di host, dan allowLocalBinding tidak berpengaruh. Jalankan perintah yang memerlukan server host di luar sandbox dengan excludedCommands, tempat perintah tersebut tidak memiliki batasan filesystem atau jaringan. Untuk koneksi yang melalui proxy sandbox, lihat Hostname yang di-resolve ke alamat lokal

Contoh ini mengaktifkan pengaturan untuk macOS:

{
  "sandbox": {
    "network": {
      "allowLocalBinding": true
    }
  }
}

Entri allowedDomains untuk localhost berlaku untuk koneksi yang melalui proxy, sehingga tidak mengubah koneksi langsung. Claude Code menetapkan NO_PROXY untuk perintah sandboxed sehingga perintah tersebut terhubung ke localhost secara langsung alih-alih melalui proxy. Entri tersebut juga mengekspos setiap port di localhost mesin Anda ke perintah yang memang menggunakan proxy. Untuk hostname pengembangan yang mengarah ke 127.0.0.1, lihat Hostname yang diizinkan ditolak dengan resolved to a loopback address.

Hostname yang diizinkan ditolak dengan `resolved to a loopback address`

Proxy sandbox menolak hostname yang diizinkan yang di-resolve ke alamat lokal, yang memengaruhi nama pengembangan seperti myapp.test yang mengarah ke 127.0.0.1. Perintah melihat respons 403 yang isinya menyebutkan jenis alamat, seperti Connection to myapp.test blocked: resolved to a loopback address.

Tambahkan alamat IP tempat nama tersebut di-resolve bersama hostname di allowedDomains, masing-masing dengan port tempat server Anda mendengarkan:

{
  "sandbox": {
    "network": {
      "allowedDomains": ["myapp.test:3000", "127.0.0.1:3000"]
    }
  }
}

Entri alamat IP tanpa port memungkinkan perintah sandboxed menjangkau setiap layanan yang mendengarkan pada alamat tersebut.

Sebelum v2.1.284, proxy terhubung ke alamat apa pun tempat hostname yang diizinkan di-resolve.

`/sandbox` gagal dengan `Sandbox settings are overridden by a higher-priority configuration`

/sandbox mencetak Error: Sandbox settings are overridden by a higher-priority configuration and cannot be changed locally. alih-alih membuka panelnya ketika tingkat pengaturan yang lebih tinggi menetapkan sandbox.enabled, sandbox.autoAllowBashIfSandboxed, atau sandbox.allowUnsandboxedCommands. Panel menyimpan pilihan Anda ke .claude/settings.local.json, dan nilai yang disimpan di sana tidak dapat menimpa tingkat-tingkat tersebut.

Pengaturan terkelola dan --settings memiliki peringkat di atas pengaturan lokal. Untuk melihat mana di antaranya yang dimuat oleh sesi ini, jalankan /status dan baca baris Setting sources:

Command line arguments: jika Anda memulai Claude Code dengan --settings, periksa apakah file atau JSON yang Anda berikan menetapkan salah satu kunci tersebut. Jika ya, ubah nilainya di sana, atau mulai Claude Code lagi tanpa kunci-kunci tersebut.
Enterprise managed settings: pengaturan terkelola organisasi Anda dimuat. Jika pengaturan tersebut menetapkan salah satu kunci tersebut, Anda tidak dapat mengubah kunci itu dari /sandbox atau dari file pengaturan apa pun yang Anda kendalikan, jadi tanyakan kepada administrator Anda.

Keterbatasan

Sandboxing mengurangi risiko tetapi bukan batas isolasi lengkap. Tinjau keterbatasan di bawah sebelum mengandalkannya sebagai kontrol keamanan keras.

Keterbatasan keamanan

Penyaringan jaringan: sandbox membatasi domain mana yang dapat terhubung oleh proses. Secara default, proxy bawaan tidak menghentikan atau melakukan inspeksi TLS pada lalu lintas keluar, sehingga isi koneksi terenkripsi tidak diperiksa. Pengaturan eksperimental network.tlsTerminate menghentikan TLS di proxy untuk substitusi kredensial mask tetapi tidak menambahkan penyaringan konten. Anda bertanggung jawab untuk memastikan bahwa hanya domain tepercaya yang diizinkan dalam kebijakan Anda.

Eskalasi privilege melalui soket Unix: konfigurasi allowUnixSockets dapat secara tidak sengaja memberikan akses ke layanan sistem yang dapat menyebabkan bypass sandbox. Misalnya, mengizinkan akses ke /var/run/docker.sock secara efektif memberikan akses ke sistem host melalui soket Docker. Pertimbangkan dengan hati-hati soket Unix apa pun yang Anda izinkan melalui sandbox.
Eskalasi izin filesystem: izin penulisan filesystem yang terlalu luas dapat memungkinkan serangan eskalasi privilege. Mengizinkan penulisan ke direktori yang berisi executable dalam $PATH, direktori konfigurasi sistem, atau file konfigurasi shell pengguna seperti .bashrc atau .zshrc dapat menyebabkan eksekusi kode dalam konteks keamanan yang berbeda ketika pengguna lain atau proses sistem mengakses file ini.
Kekuatan sandbox Linux: implementasi Linux menyediakan isolasi filesystem dan jaringan yang kuat tetapi mencakup mode enableWeakerNestedSandbox yang memungkinkannya bekerja di dalam lingkungan Docker tanpa namespace istimewa. Opsi ini secara konsiderabel melemahkan keamanan dan hanya boleh digunakan ketika isolasi tambahan sebaliknya diberlakukan.
Apple Events pada macOS: sandbox macOS memblokir Apple Events secara default. Pengaturan allowAppleEvents menghapus pembatasan ini sehingga alat seperti open dan osascript berfungsi, tetapi menghilangkan isolasi eksekusi kode: perintah sandboxed dapat meluncurkan aplikasi lain tanpa sandbox tanpa prompt pengguna, dan dapat mengirim perintah AppleScript ke aplikasi yang sedang berjalan, tunduk pada prompt persetujuan otomasi macOS per-aplikasi (TCC). Ini hanya dihormati dari pengaturan pengguna, terkelola, atau CLI. Pengaturan proyek tidak dapat mengaktifkannya.

Cakupan

Sandbox mengisolasi perintah shell dan proses turunannya. Apa yang berjalan di luar sandbox mencantumkan tool dan proses pembantu yang tidak dicakupnya. Penggunaan komputer dan subagent berkaitan dengan sandbox sebagai berikut:

Penggunaan komputer: ketika Claude membuka aplikasi dan mengontrol layar Anda, itu berjalan di desktop aktual Anda daripada di lingkungan terisolasi. Prompt izin per-aplikasi membatasi setiap aplikasi. Lihat computer use in the CLI atau computer use in Desktop.
Subagents: subagents berjalan dalam proses yang sama dengan sesi induk dan menggunakan konfigurasi sandbox yang sama. Perintah Bash di dalam subagent di-sandbox ketika sandboxing diaktifkan dalam sesi induk.
Mods: mod adalah plugin yang menjalankan kodenya sendiri di dalam Claude Code, dan proses yang dimulai oleh mod berjalan di luar sandbox. Lihat Apa yang dapat dijangkau mod.

Lihat juga

Sandbox environments: bandingkan sandbox bawaan dengan dev containers, containers, dan VM
Security: fitur keamanan komprehensif dan praktik terbaik
Permissions: konfigurasi izin dan kontrol akses
All settings: setiap kunci pengaturan
CLI reference: opsi baris perintah

sandboxing.md +596 −297

2> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt2> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt

3> Use this file to discover all available pages before exploring further.3> Use this file to discover all available pages before exploring further.

4 4

~~5# Konfigurasi alat Bash sandboxed~~5# Konfigurasikan tool Bash dengan sandbox

6 6

~~7> Pelajari bagaimana alat Bash sandboxed Claude Code menyediakan isolasi filesystem dan jaringan untuk eksekusi agen yang lebih aman dan mandiri.~~7> Batasi file dan host jaringan yang dapat dijangkau oleh perintah shell Claude Code dengan sandbox bawaan. Aktifkan, tetapkan batasnya, dan perbaiki hal-hal yang terganggu olehnya.

8 8

9Sandbox Bash memungkinkan Claude menjalankan sebagian besar perintah shell tanpa berhenti untuk meminta izin. Alih-alih menyetujui setiap perintah, Anda menentukan file dan domain jaringan mana yang dapat diakses perintah, dan sistem operasi memberlakukan batas itu untuk setiap perintah Bash, PowerShell, atau Monitor dan proses anak-anaknya.9Sandbox Bash adalah batas yang diterapkan oleh sistem operasi di sekitar perintah shell yang dijalankan Claude di mesin Anda. Anda menetapkan file dan domain jaringan mana yang dapat dijangkau oleh perintah tersebut, dan batasan tersebut berlaku untuk perintah Bash, PowerShell, dan Monitor serta proses yang dimulainya. Karena sistem operasi menerapkan batasan tersebut saat perintah berjalan, Claude Code dapat [menjalankan perintah dalam sandbox tanpa meminta Anda](#sandbox-modes) untuk menyetujui setiap perintah.

11Sandbox hanya mencakup perintah shell. Tool file Claude, server MCP, dan hook [berjalan di luarnya](#what-runs-outside-the-sandbox).

13Sandbox berjalan di macOS, Linux, dan WSL2. Di Windows native, Claude Code menjalankan perintah tanpa sandbox. Untuk menggunakan sandbox di mesin Windows, jalankan Claude Code di dalam distribusi WSL2.

10 14

11<Note>15<Note>

12 Untuk membandingkan pendekatan isolasi lain seperti dev containers, container khusus, dan mesin virtual, lihat [Sandbox environments](/docs/id/sandbox-environments). Untuk mengurangi prompt izin untuk alat selain Bash, lihat [permission modes](/docs/id/permission-modes).16 Halaman ini membahas sandbox di sekitar perintah shell di mesin Anda sendiri. Halaman lain membahas pertanyaan terkait:

18 * Untuk cara sesi cloud diisolasi, lihat [Keamanan dan isolasi](/docs/id/claude-code-on-the-web#security-and-isolation)

19 * Untuk membandingkan pendekatan isolasi lain seperti dev container, container kustom, dan mesin virtual, lihat [Lingkungan sandbox](/docs/id/sandbox-environments)

20 * Untuk mengurangi permintaan izin untuk tool selain Bash, lihat [mode izin](/docs/id/permission-modes)

13</Note>21</Note>

14 22

23<h2 id="what-the-sandbox-restricts">

24 Apa yang dibatasi oleh sandbox

25</h2>

27Saat sandbox aktif, perintah shell yang dijalankan Claude dimulai di dalam batasnya, demikian pula proses yang dimulai oleh perintah tersebut. Sandbox nonaktif secara default. Untuk mengaktifkannya, jalankan `/sandbox` dalam sebuah sesi, seperti yang ditunjukkan di [Memulai](#get-started), atau atur [`sandbox.enabled`](/docs/id/settings-reference#sandbox-enabled) ke `true` dalam [file pengaturan](/docs/id/settings) seperti `~/.claude/settings.json`.

29Tabel berikut menunjukkan apa yang dapat dijangkau oleh perintah yang berjalan di sandbox secara default dan pengaturan yang mengubah setiap default tersebut.

31| Akses | Default | Ubah dengan |

32| :- | :- | :- |

33| Penulisan | Direktori kerja, direktori temp per pengguna, dan [direktori yang telah Anda tambahkan](/docs/id/permissions#additional-directories-grant-file-access-not-configuration). [Path yang dilindungi](#protected-paths) tetap ditolak untuk penulisan | [`filesystem.allowWrite`](/docs/id/settings-reference#sandbox-filesystem-allowwrite), [`filesystem.denyWrite`](/docs/id/settings-reference#sandbox-filesystem-denywrite) |

34| Pembacaan | Sebagian besar mesin, termasuk file kredensial seperti `~/.ssh` dan `~/.aws/credentials` | [`filesystem.denyRead`](/docs/id/settings-reference#sandbox-filesystem-denyread), [`credentials`](#protect-credentials) |

35| Jaringan | Tidak ada rute keluar langsung. Koneksi melewati proxy di mesin Anda yang memeriksa setiap host terhadap domain yang Anda izinkan, yang awalnya kosong. Mode izin Anda menentukan [apa yang terjadi pada host lain](#hosts-outside-your-allowed-domains) | [`network.allowedDomains`](/docs/id/settings-reference#sandbox-network-alloweddomains), [`network.deniedDomains`](/docs/id/settings-reference#sandbox-network-denieddomains) |

36| Environment variable | Diwarisi dari Claude Code, termasuk rahasia apa pun di lingkungannya | [`credentials`](#protect-credentials), [`CLAUDE_CODE_SUBPROCESS_ENV_SCRUB`](/docs/id/env-vars) |

38Claude Code membangun sandbox di atas paket open source [`@anthropic-ai/sandbox-runtime`](https://github.com/anthropics/sandbox-runtime).

40<h3 id="what-runs-outside-the-sandbox">

41 Apa yang berjalan di luar sandbox

42</h3>

44Sandbox membungkus perintah shell. Tool dan proses berikut berjalan di luarnya:

46* **Tool file dan web bawaan**: tool seperti Read, Edit, Write, WebFetch, dan WebSearch mengikuti [aturan izin](/docs/id/permissions) sebagai gantinya. Entri `denyRead` tidak menghentikan tool Read, dan `allowedDomains` tidak membatasi WebFetch

47* **Proses lain yang dimulai Claude Code**: [hook](/docs/id/hooks) perintah, [server MCP](/docs/id/mcp) lokal, [monitor plugin](/docs/id/plugins/components#monitors), [server LSP](/docs/id/tools-reference#lsp-tool-behavior), dan perintah pembantu seperti perintah [baris status](/docs/id/statusline) Anda dan `apiKeyHelper` berjalan dengan akses penuh Anda

49Beberapa perintah shell juga berjalan di luar sandbox, tergantung pada pengaturan Anda:

51* **Perintah yang Anda ketik sendiri**: perintah yang Anda masukkan di [prompt mode shell `!`](/docs/id/interactive-mode#shell-mode-with-prefix) berjalan tanpa sandbox di sebagian besar sesi. [Mode sandbox ketat](#turn-off-the-retry-with-strict-sandbox-mode) mencantumkan sesi-sesi di mana perintah yang Anda ketik berjalan di dalam sandbox

52* **Perintah yang dikecualikan**: perintah yang cocok dengan [`excludedCommands`](#run-commands-outside-the-sandbox-with-excludedcommands) berjalan tanpa sandbox

53* **Retry tanpa sandbox**: Claude dapat [meminta untuk menjalankan perintah tanpa sandbox](#the-unsandboxed-retry-escape-hatch), biasanya setelah perintah tersebut gagal di dalam sandbox

55Untuk menempatkan tool, proses, dan perintah di bagian ini di balik satu batas, jalankan proses Claude Code itu sendiri di dalam [container, mesin virtual, atau sandbox runtime](/docs/id/sandbox-environments).

15<h2 id="get-started">57<h2 id="get-started">

16 Memulai58 Memulai

17</h2>59</h2>

18 60

~~19Sandbox dibangun ke dalam Claude Code dan berjalan di macOS, Linux, dan WSL2. Windows asli tidak didukung. Di Windows, jalankan Claude Code di dalam distribusi WSL2.~~61Sandbox sudah terpasang di dalam Claude Code. Apa yang perlu Anda instal bergantung pada platform Anda:

20 62

21Di macOS, tidak ada yang perlu diinstal: sandboxing menggunakan kerangka Seatbelt bawaan. Di Linux dan WSL2, sandbox bergantung pada dua paket, yang dibahas dalam [Set up Linux and WSL2](#set-up-linux-and-wsl2). Bahkan jika Anda belum menginstalnya, Anda dapat memulai dengan `/sandbox`, karena panelnya menunjukkan apakah ada yang hilang.63* **macOS**: sandboxing menggunakan framework Seatbelt bawaan, sehingga Anda dapat langsung menuju langkah-langkahnya

64* **Linux dan WSL2**: sandbox bergantung pada `bubblewrap` dan `socat`, yang dibahas di [Menyiapkan Linux dan WSL2](#set-up-linux-and-wsl2). Meskipun Anda belum menginstalnya, Anda dapat memulai dengan `/sandbox`, karena panelnya menunjukkan apakah ada yang belum terpasang

22 65

23<Steps>66<Steps>

24 <Step title="Jalankan /sandbox">67 <Step title="Jalankan /sandbox">

28 /sandbox71 /sandbox

29 ```72 ```

30 73

~~31 Ini membuka panel sandbox dengan tiga tab, ditambah tab Dependencies di Linux ketika filter seccomp opsional hilang:~~74 Ini membuka panel sandbox dengan tiga tab, ditambah tab Dependencies di Linux ketika filter seccomp opsional belum terpasang:

32 75

~~33 * **Mode**: pilih bagaimana perintah sandboxed disetujui, dibahas dalam langkah berikutnya~~76 * **Mode**: pilih cara perintah yang di-sandbox disetujui, dibahas pada langkah berikutnya

34 * **Overrides**: pilih apakah perintah yang gagal di bawah sandbox dapat kembali ke menjalankan unsandboxed. Ini adalah pengaturan [`allowUnsandboxedCommands`](/docs/id/settings-reference#sandbox-allowunsandboxedcommands)77 * **Overrides**: pilih apakah perintah yang gagal di bawah sandbox dapat kembali berjalan tanpa sandbox. Ini adalah pengaturan [`allowUnsandboxedCommands`](/docs/id/settings-reference#sandbox-allowunsandboxedcommands)

~~35 * **Config**: lihat pengaturan sandbox yang diselesaikan~~78 * **Config**: lihat pengaturan sandbox yang telah diselesaikan

36 79

37 Jika panel hanya menampilkan tab Dependencies, paket yang diperlukan hilang. Instal seperti yang dijelaskan dalam [Set up Linux and WSL2](#set-up-linux-and-wsl2), restart Claude Code, dan jalankan `/sandbox` lagi.80 Jika panel hanya menampilkan tab Dependencies, berarti ada paket wajib yang belum terpasang. Instal paket tersebut seperti yang dijelaskan di [Menyiapkan Linux dan WSL2](#set-up-linux-and-wsl2), mulai ulang Claude Code, lalu jalankan `/sandbox` lagi.

38 </Step>81 </Step>

39 82

40 <Step title="Pilih mode">83 <Step title="Pilih mode">

41 Di tab Mode, pilih auto-allow atau regular permissions. Auto-allow menjalankan perintah sandboxed tanpa prompt, dan regular permissions menjaga prompt izin reguler bahkan ketika perintah sandboxed. Lihat [Sandbox modes](#sandbox-modes) untuk perintah mana yang masih prompt dalam mode auto-allow.84 Pada tab Mode, pilih auto-allow atau regular permissions. Auto-allow menjalankan perintah yang di-sandbox tanpa permintaan izin, sedangkan regular permissions tetap mempertahankan permintaan izin biasa bahkan ketika perintah di-sandbox. Lihat [Mode sandbox](#sandbox-modes) untuk perintah mana saja yang tetap memunculkan permintaan izin dalam mode auto-allow.

42 </Step>85 </Step>

43 86

44 <Step title="Jalankan perintah Bash">87 <Step title="Jalankan perintah Bash">

45 Minta Claude untuk menjalankan perintah, seperti build atau test suite. Secara default, perintah di dalam sandbox dapat menulis ke direktori kerja, [direktori temp per-pengguna](/docs/id/env-vars), dan [direktori apa pun yang telah Anda tambahkan](/docs/id/permissions#additional-directories-grant-file-access-not-configuration) dengan `--add-dir`, `/add-dir`, atau `permissions.additionalDirectories`.88 Minta Claude menjalankan sebuah perintah, seperti build atau rangkaian pengujian. Secara default, perintah di dalam sandbox dapat menulis ke direktori kerja, [direktori temp per pengguna](/docs/id/env-vars), dan [direktori apa pun yang telah Anda tambahkan](/docs/id/permissions#additional-directories-grant-file-access-not-configuration) dengan `--add-dir`, `/add-dir`, atau `permissions.additionalDirectories`.

46 89

47 Pertama kali perintah memerlukan domain jaringan baru, Claude Code meminta persetujuan; dalam [mode auto](/docs/id/permission-modes#eliminate-prompts-with-auto-mode), Claude malah menamai host yang dibutuhkan perintah [pada perintah itu sendiri](#per-command-allowed-domains-in-auto-mode) untuk pengklasifikasi ditinjau bersama dengannya.90 Saat pertama kali sebuah perintah memerlukan domain jaringan baru, Claude Code meminta persetujuan; dalam [auto mode](/docs/id/permission-modes#eliminate-prompts-with-auto-mode), Claude justru menyebutkan host yang dibutuhkan perintah [pada perintah itu sendiri](#per-command-allowed-domains-in-auto-mode) agar pengklasifikasi meninjaunya bersama perintah tersebut.

48 91

49 Perintah yang tidak dapat berjalan sandboxed kembali ke alur izin reguler. Claude Code memberi judul prompt izin mereka "Bash command (unsandboxed)" bukan "Bash command", sehingga Anda dapat mengetahui perintah mana yang berjalan di luar sandbox. Untuk memperluas atau mempersempit apa yang diizinkan sandbox, lihat [Configure sandboxing](#configure-sandboxing).92 Untuk memperluas atau mempersempit apa yang diizinkan sandbox, lihat [Mengonfigurasi sandboxing](#configure-sandboxing).

50 93

~~51 Jika perintah sandboxed gagal dengan `Operation not permitted` di dalam kontainer, lihat entri Bubblewrap di bawah [Troubleshooting](#troubleshooting).~~94 Jika perintah yang di-sandbox gagal dengan `Operation not permitted` di dalam container, lihat [Bubblewrap gagal dimulai di dalam container](#bubblewrap-fails-to-start-inside-a-container).

52 </Step>95 </Step>

53</Steps>96</Steps>

54 97

55Ketika Anda memilih mode dalam panel, Claude Code menyimpannya ke pengaturan lokal proyek Anda di `.claude/settings.local.json`, yang berlaku untuk proyek saat ini. Claude Code menambahkan file itu ke gitignore global Anda ketika menyimpan pengaturan di sana. Untuk mengaktifkan sandbox di semua proyek Anda, atur [`sandbox.enabled`](/docs/id/settings-reference#sandbox-enabled) ke `true` dalam pengaturan pengguna Anda di `~/.claude/settings.json`. Untuk memberlakukan sandboxing untuk setiap pengembang dalam organisasi, gunakan [managed settings](#enforce-sandboxing-with-managed-settings).98Ketika Anda memilih mode di panel, Claude Code menyimpannya ke pengaturan lokal proyek Anda di `.claude/settings.local.json`, yang berlaku untuk proyek saat ini. Claude Code menambahkan file tersebut ke gitignore global Anda ketika menyimpan pengaturan di sana. Untuk mengaktifkan sandbox di semua proyek Anda, atur [`sandbox.enabled`](/docs/id/settings-reference#sandbox-enabled) ke `true` dalam pengaturan pengguna Anda di `~/.claude/settings.json`. Untuk mewajibkan sandboxing bagi setiap developer dalam organisasi, gunakan [pengaturan terkelola](#enforce-sandboxing-with-managed-settings).

56 99

57Untuk mengubah sandbox untuk satu sesi tanpa menulis ke file pengaturan, mulai Claude Code dengan [`--settings`](/docs/id/settings#change-a-setting-for-one-session). Misalnya, perintah ini memulai sesi sandboxed di mana Claude tidak dapat mencoba kembali perintah yang diblokir di luar sandbox:100Untuk mengubah sandbox untuk satu sesi tanpa menulis ke file pengaturan, mulai Claude Code dengan [`--settings`](/docs/id/settings#change-a-setting-for-one-session). Misalnya, perintah ini memulai sesi yang di-sandbox di mana Claude tidak dapat mencoba ulang perintah yang diblokir di luar sandbox:

58 101

59```bash theme={null}102```bash theme={null}

60claude --settings '{"sandbox": {"enabled": true, "allowUnsandboxedCommands": false}}'103claude --settings '{"sandbox": {"enabled": true, "allowUnsandboxedCommands": false}}'

61```104```

62 105

63<Warning>106<Warning>

64 Secara default, jika sandbox tidak dapat dimulai karena dependensi hilang atau platform tidak didukung, Claude Code menampilkan peringatan dan menjalankan perintah tanpa sandboxing. Untuk menjadikan ini kegagalan keras sebagai gantinya, atur [`sandbox.failIfUnavailable`](/docs/id/settings-reference#sandbox-failifunavailable) ke `true`. Ini dimaksudkan untuk penyebaran terkelola yang memerlukan sandboxing sebagai gerbang keamanan.107 Secara default, jika sandbox tidak dapat dimulai karena ada dependensi yang belum terpasang atau platform tidak didukung, Claude Code menjalankan perintah tanpa sandboxing. Agar Claude Code keluar saat startup, atur [`sandbox.failIfUnavailable`](/docs/id/settings-reference#sandbox-failifunavailable) ke `true`. Deployment terkelola yang mewajibkan sandboxing sebagai gerbang keamanan dapat menggunakan pengaturan ini.

65</Warning>108</Warning>

66 109

110<h3 id="confirm-commands-run-inside-the-sandbox">

111 Memastikan perintah berjalan di dalam sandbox

112</h3>

113

114Untuk memeriksa apakah sandbox berfungsi, minta Claude menjalankan setiap baris dalam tabel. Apa yang Anda ketik di [prompt `!`](#what-runs-outside-the-sandbox) biasanya berjalan di luar sandbox, sehingga mengetik baris tersebut sendiri tidak mengujinya.

115

116| Perintah | Hasil di dalam sandbox |

117| :- | :- |

118| `touch ~/sandbox-probe` | Gagal dengan `Operation not permitted` di macOS, atau `Read-only file system` di Linux dan WSL2 |

119| `curl --noproxy '*' https://example.com` | Gagal dengan `Could not resolve host`, karena perintah tidak memiliki jalur untuk melewati proxy sandbox |

120

121Jika Claude meminta untuk mencoba ulang perintah yang gagal di luar sandbox, tolak retry tersebut. Jika `touch` berhasil dan direktori home Anda bukan salah satu direktori yang diizinkan sandbox untuk ditulisi oleh perintah, hapus `~/sandbox-probe`. Kemudian jalankan `/sandbox` untuk memeriksa bahwa sandbox aktif dan dependensinya terinstal.

122

67<h3 id="set-up-linux-and-wsl2">123<h3 id="set-up-linux-and-wsl2">

~~68 Set up Linux dan WSL2~~124 Menyiapkan Linux dan WSL2

69</h3>125</h3>

70 126

~~71Di Linux dan WSL2, sandbox bergantung pada dua paket:~~127Di Linux dan WSL2, sandbox bergantung pada paket-paket berikut:

72 128

~~73* [`bubblewrap`](https://github.com/containers/bubblewrap): alat sandboxing tanpa privilege yang memberlakukan isolasi filesystem~~129* [`bubblewrap`](https://github.com/containers/bubblewrap): tool sandboxing tanpa hak istimewa yang menerapkan isolasi filesystem

74* [`socat`](http://www.dest-unreach.org/socat/): relay yang digunakan untuk merutekan lalu lintas jaringan melalui proxy sandbox130* [`socat`](http://www.dest-unreach.org/socat/): relay yang digunakan untuk merutekan lalu lintas jaringan melalui proxy sandbox

75 131

~~76Instal dengan manajer paket distribusi Anda:~~132Instal paket-paket tersebut dengan package manager distribusi Anda:

77 133

78<Tabs>134<Tabs>

79 <Tab title="Ubuntu/Debian">135 <Tab title="Ubuntu/Debian">

89 </Tab>145 </Tab>

90</Tabs>146</Tabs>

91 147

92Ketika dependensi hilang, tab Dependencies dalam `/sandbox` mencantumkan mana dari `ripgrep`, `bubblewrap`, `socat`, dan filter seccomp yang platform Anda kurangi. Jika Anda tidak melihat tab setelah menginstal dan memulai ulang Claude Code, semua dependensi ada.148Ketika ada dependensi yang belum terpasang, tab Dependencies di `/sandbox` mencantumkan mana di antara `ripgrep`, `bubblewrap`, `socat`, dan filter seccomp yang tidak dimiliki platform Anda. Jika Anda tidak melihat tab tersebut setelah menginstal dan memulai ulang Claude Code, berarti semua dependensi sudah tersedia.

93 149

94Ripgrep disertakan dengan binari Claude Code asli. Filter seccomp bersifat opsional dan menambahkan pemblokiran soket domain Unix. Instal dengan `npm install -g @anthropic-ai/sandbox-runtime` jika hilang.150Ripgrep sudah dibundel dengan binary native Claude Code. Filter seccomp bersifat opsional dan menambahkan pemblokiran Unix domain socket. Instal dengan `npm install -g @anthropic-ai/sandbox-runtime` jika belum terpasang.

95 151

96Ketika dependensi yang diperlukan hilang, tab Dependencies adalah satu-satunya tab yang ditampilkan sampai Anda menginstalnya. Ketika hanya filter seccomp opsional yang hilang, tab Dependencies muncul bersama tab lainnya. Pemeriksaan dependensi berjalan saat startup, jadi restart Claude Code setelah menginstal paket untuk `/sandbox` mendeteksinya.152Ketika dependensi wajib belum terpasang, tab Dependencies adalah satu-satunya tab yang ditampilkan hingga Anda menginstalnya. Ketika hanya filter seccomp opsional yang belum terpasang, tab Dependencies muncul bersama tab lainnya. Pemeriksaan dependensi berjalan saat startup, jadi mulai ulang Claude Code setelah menginstal paket agar `/sandbox` dapat mendeteksinya.

97 153

98<AccordionGroup>154<AccordionGroup>

~~99 <Accordion title="Ubuntu 24.04 dan yang lebih baru: izinkan bubblewrap untuk membuat user namespaces">~~155 <Accordion title="Ubuntu 24.04 dan yang lebih baru: izinkan bubblewrap membuat user namespace">

100 Di Ubuntu 24.04 dan yang lebih baru, kebijakan AppArmor default mencegah bubblewrap dari membuat user namespaces yang dibutuhkannya untuk isolasi.156 Di Ubuntu 24.04 dan yang lebih baru, kebijakan AppArmor default mencegah bubblewrap membuat user namespace yang dibutuhkannya untuk isolasi.

101 157

102 Untuk memeriksa apakah lingkungan Anda memberlakukan pembatasan ini, termasuk di dalam WSL2, jalankan `sysctl kernel.apparmor_restrict_unprivileged_userns`. Jika perintah mengembalikan `0`, lewati langkah ini. Jika mencetak kesalahan `No such file or directory`, kunci tidak ada dan Anda dapat melewati langkah ini. Jika mengembalikan `1`, tambahkan profil AppArmor yang memberikan `bwrap` kemampuan ini:158 Untuk memeriksa apakah lingkungan Anda menerapkan pembatasan ini, termasuk di dalam WSL2, jalankan `sysctl kernel.apparmor_restrict_unprivileged_userns`. Jika perintah mengembalikan `0`, lewati langkah ini. Jika perintah mencetak error `No such file or directory`, berarti key tersebut tidak ada dan Anda dapat melewati langkah ini. Jika mengembalikan `1`, tambahkan profil AppArmor yang memberikan kemampuan ini kepada `bwrap`:

103 159

104 ```bash theme={null}160 ```bash theme={null}

105 sudo tee /etc/apparmor.d/bwrap > /dev/null <<'EOF'161 sudo tee /etc/apparmor.d/bwrap > /dev/null <<'EOF'

113 EOF169 EOF

114 ```170 ```

115 171

116 Profil hanya berlaku untuk `bwrap` itu sendiri, bukan untuk perintah yang berjalan di dalam sandbox. Muat ulang AppArmor untuk menerapkannya:172 Profil ini hanya berlaku untuk `bwrap` itu sendiri, bukan untuk perintah yang dijalankannya di dalam sandbox. Muat ulang AppArmor untuk menerapkannya:

117 173

118 ```bash theme={null}174 ```bash theme={null}

119 sudo systemctl reload apparmor175 sudo systemctl reload apparmor

121 </Accordion>177 </Accordion>

122 178

123 <Accordion title="Catatan WSL2">179 <Accordion title="Catatan WSL2">

124 Periksa versi WSL Anda dengan `wsl -l -v` dari PowerShell. Jika Anda melihat `Sandboxing requires WSL2`, distribusi Anda menjalankan WSL1. Tingkatkan ke WSL2 atau jalankan Claude Code tanpa sandboxing.180 Periksa versi WSL Anda dengan `wsl -l -v` dari PowerShell. Jika Anda melihat `Sandboxing requires WSL2`, distribusi Anda berjalan di WSL1. Tingkatkan ke WSL2 atau jalankan Claude Code tanpa sandboxing.

125 181

126 Di WSL2, WSL menyerahkan peluncuran binari Windows seperti `cmd.exe`, `powershell.exe`, atau apa pun di bawah `/mnt/c/` ke host Windows melalui soket Unix, jadi apakah perintah sandboxed dapat meluncurkan satu mengikuti pengaturan [Unix-socket](/docs/id/settings-reference#sandbox-network-allowunixsockets) sandbox: filter seccomp opsional harus diinstal untuk memblokir soket di tempat pertama. Untuk memungkinkan peluncuran ini, atur `allowAllUnixSockets`; untuk menjaganya keluar dari sandbox sepenuhnya, tambahkan perintah ke [`excludedCommands`](/docs/id/settings-reference#sandbox-excludedcommands).182 Di WSL2, WSL menyerahkan peluncuran binary Windows seperti `cmd.exe`, `powershell.exe`, atau apa pun di bawah `/mnt/c/` ke host Windows melalui Unix socket, sehingga apakah perintah yang di-sandbox dapat meluncurkannya mengikuti [pengaturan Unix socket](/docs/id/settings-reference#sandbox-network-allowunixsockets) sandbox: filter seccomp opsional harus terinstal agar socket tersebut dapat diblokir sejak awal. Untuk mengizinkan peluncuran ini, atur `allowAllUnixSockets`, yang membuka setiap Unix socket bagi perintah yang di-sandbox.

127 </Accordion>183 </Accordion>

128</AccordionGroup>184</AccordionGroup>

129 185

131 Mode sandbox187 Mode sandbox

132</h3>188</h3>

133 189

134Claude Code menawarkan dua mode sandbox. Di keduanya, sandbox memberlakukan pembatasan filesystem dan jaringan yang sama; perbedaannya hanya dalam apakah perintah sandboxed disetujui secara otomatis atau memerlukan izin eksplisit.190Claude Code menawarkan dua mode sandbox. Pada keduanya, sandbox menerapkan pembatasan filesystem dan jaringan yang sama; perbedaannya hanya pada apakah perintah yang di-sandbox disetujui secara otomatis atau memerlukan izin eksplisit.

135 191

136<h4 id="auto-allow-mode">192<h4 id="auto-allow-mode">

137 Mode auto-allow193 Mode auto-allow

138</h4>194</h4>

139 195

140Ketika perintah dapat di-sandbox, Claude Code menjalankannya di dalam sandbox dan menyetujuinya secara otomatis, tanpa meminta izin Anda. Perintah yang tidak dapat di-sandbox, seperti yang memerlukan akses jaringan ke host yang tidak diizinkan, kembali ke alur izin reguler, di mana Claude Code memeriksa [permission rules](/docs/id/permissions) Anda dan membatasi perintah apa pun yang tidak diizinkan oleh aturan tersebut, dengan prompt dalam mode Manual.196Claude Code menyetujui perintah secara otomatis, tanpa permintaan izin, ketika perintah berjalan di dalam sandbox. Sebuah perintah melalui [alur izin](/docs/id/permissions) biasa ketika berjalan di luar sandbox karena cocok dengan [`excludedCommands`](#run-commands-outside-the-sandbox-with-excludedcommands) atau karena Claude [mencobanya ulang tanpa sandbox](#the-unsandboxed-retry-escape-hatch).

197

198Perintah yang di-sandbox yang terhubung ke host yang belum Anda izinkan tetap berada di dalam sandbox. [Host di luar domain yang Anda izinkan](#hosts-outside-your-allowed-domains) membahas siapa yang memutuskan apakah koneksi tersebut diteruskan.

141 199

142Bahkan dalam mode auto-allow, hal berikut masih berlaku:200Bahkan dalam mode auto-allow, hal-hal berikut tetap berlaku:

143 201

144* [Deny rules](/docs/id/permissions) eksplisit selalu dihormati202* [Aturan deny](/docs/id/permissions) eksplisit selalu dipatuhi

145* Perintah `rm` atau `rmdir` yang menargetkan [critical path](/docs/id/permission-modes#critical-paths) masih melalui alur izin reguler203* Perintah `rm` atau `rmdir` yang menargetkan [jalur kritis](/docs/id/permission-modes#critical-paths) tetap melalui alur izin biasa

146* [Ask rules](/docs/id/permissions) yang dibatasi konten seperti `Bash(git push *)` masih memaksa prompt bahkan untuk perintah sandboxed204* [Aturan ask](/docs/id/permissions) yang dibatasi konten seperti `Bash(git push *)` tetap memaksa munculnya permintaan izin bahkan untuk perintah yang di-sandbox

147* Aturan `Bash` ask yang kosong, atau bentuk setara `Bash(*)`, dilewati untuk perintah yang berjalan sandboxed; masih berlaku untuk perintah yang kembali ke alur izin reguler. Dalam [plan mode](/docs/id/permission-modes#analyze-before-you-edit-with-plan-mode), aturan tidak dilewati: itu meminta perintah sandboxed juga, termasuk yang hanya-baca. Sebelum v2.1.212, skip berlaku dalam plan mode juga205* Aturan ask `Bash` polos, atau bentuk setaranya `Bash(*)`, dilewati untuk perintah yang berjalan di-sandbox; aturan ini tetap berlaku untuk perintah yang kembali ke alur izin biasa. Dalam [plan mode](/docs/id/permission-modes#analyze-before-you-edit-with-plan-mode), aturan ini tidak dilewati: aturan ini memunculkan permintaan izin untuk perintah yang di-sandbox juga, termasuk yang read-only

148 206

149<Info>207<Info>

150 Mode auto-allow bekerja secara independen dari pengaturan mode izin Anda, dengan tiga pengecualian: [plan mode](/docs/id/permission-modes#analyze-before-you-edit-with-plan-mode), perintah mode auto yang membawa [per-command allowed domains](#per-command-allowed-domains-in-auto-mode), dan [server-side classifier review](/docs/id/permission-modes#how-the-classifier-evaluates-actions) dari perintah sandboxed dalam mode auto. Bahkan jika Anda tidak dalam mode "accept edits", perintah Bash sandboxed berjalan secara otomatis ketika auto-allow diaktifkan. Ini berarti perintah Bash yang memodifikasi file dalam batas sandbox dieksekusi tanpa prompt, bahkan dalam mode Manual, di mana alat edit file akan meminta.208 Mode auto-allow bekerja secara independen dari pengaturan mode izin Anda, dengan tiga pengecualian: [plan mode](/docs/id/permission-modes#analyze-before-you-edit-with-plan-mode), perintah auto mode yang membawa [domain yang diizinkan per perintah](#per-command-allowed-domains-in-auto-mode), dan [peninjauan pengklasifikasi sisi server](/docs/id/permission-modes#how-the-classifier-evaluates-actions) terhadap perintah yang di-sandbox dalam auto mode. Meskipun Anda tidak berada dalam mode "accept edits", perintah Bash yang di-sandbox berjalan secara otomatis ketika auto-allow diaktifkan. Ini berarti perintah Bash yang memodifikasi file di dalam batas sandbox dieksekusi tanpa permintaan izin, bahkan dalam mode Manual, di mana tool pengeditan file akan memunculkan permintaan izin.

151 209

152 Dalam plan mode, auto-allow tidak memperluas persetujuan; lihat [plan mode](/docs/id/permission-modes#analyze-before-you-edit-with-plan-mode) untuk bagaimana Claude Code membatasi perintah saat Anda merencanakan. Sebelum v2.1.212, auto-allow menjalankan perintah sandboxed tanpa prompt dalam plan mode juga.210 Dalam plan mode, auto-allow tidak memperluas persetujuan; lihat [plan mode](/docs/id/permission-modes#analyze-before-you-edit-with-plan-mode) untuk cara Claude Code membatasi perintah saat Anda membuat rencana.

153</Info>211</Info>

154 212

155<h4 id="regular-permissions-mode">213<h4 id="regular-permissions-mode">

156 Mode regular permissions214 Mode regular permissions

157</h4>215</h4>

158 216

159Semua perintah Bash melalui alur izin reguler, bahkan ketika sandboxed. Ini memberikan lebih banyak kontrol tetapi memerlukan lebih banyak persetujuan.217Semua perintah Bash melalui alur izin biasa, bahkan ketika di-sandbox. Ini memberikan kontrol lebih besar tetapi memerlukan lebih banyak persetujuan.

160 218

161<h4 id="the-unsandboxed-retry-escape-hatch">219<h4 id="the-unsandboxed-retry-escape-hatch">

162 Pintu keluar retry unsandboxed220 Jalan keluar retry tanpa sandbox

221</h4>

222

223Retry tanpa sandbox adalah jalan keluar untuk perintah yang gagal di dalam sandbox, seperti tool yang tidak kompatibel dengannya. Ketika sandbox memblokir koneksi jaringan, Claude Code menyebutkan host yang ditolak dalam hasil perintah, sehingga Claude melihat apa yang diblokir. Claude menganalisis kegagalan tersebut dan dapat mencoba ulang perintah dengan parameter `dangerouslyDisableSandbox`.

224

225Perintah yang dicoba ulang berjalan tanpa sandbox. Dalam sesi terminal interaktif, siapa yang menyetujuinya bergantung pada mode izin Anda:

226

227* **Mode `bypassPermissions`**: retry berjalan tanpa permintaan izin

228* **Mode Manual dan mode `acceptEdits`**: Anda mendapatkan permintaan izin berjudul "Bash command (unsandboxed)"

229* **[Auto mode](/docs/id/permission-modes#eliminate-prompts-with-auto-mode)**: model pengklasifikasi terpisah mengevaluasi perintah yang mendasarinya

230* **Mode `dontAsk`**: Claude Code menolak retry tersebut

231* **Plan mode**: lihat [cara Claude Code membatasi perintah saat Anda membuat rencana](/docs/id/permission-modes#analyze-before-you-edit-with-plan-mode)

232

233Aturan dan pengaturan berikut mengubah siapa yang menyetujui retry:

234

235* **Aturan allow yang cocok**: jika aturan allow seperti `Bash(curl *)` cocok dengan perintah, aturan tersebut juga menyetujui retry, sehingga perintah berjalan di luar sandbox tanpa permintaan izin

236* **Aturan ask untuk parameter**: tambahkan [aturan ask](/docs/id/permissions#match-by-input-parameter) untuk `Bash(dangerouslyDisableSandbox:true)` agar Anda dimintai izin pada retry Bash. Anda juga mendapatkan permintaan izin dalam auto mode dan mode `bypassPermissions`, dan aturan ini diutamakan daripada aturan allow yang cocok

237* **[`permissions.blockReadsOutsideWorkingDirectories`](/docs/id/settings-reference#permissions-blockreadsoutsideworkingdirectories)**: [Tindakan yang tidak disetujui otomatis oleh mode mana pun](/docs/id/permission-modes#actions-no-mode-auto-approves) membahas retry yang memunculkan permintaan izin saat pengaturan ini aktif

238

239<h4 id="turn-off-the-retry-with-strict-sandbox-mode">

240 Matikan retry dengan strict sandbox mode

163</h4>241</h4>

164 242

165Beberapa perintah tidak dapat berjalan di dalam sandbox sama sekali, seperti alat yang tidak kompatibel dengannya atau yang memerlukan host yang belum Anda izinkan. Claude Code melaporkan pelanggaran sandbox dalam hasil perintah yang diblokir, menamai jalur atau host yang sandbox tolak, sehingga Claude melihat apa yang sandbox blokir. Daripada gagal tugas atau memerlukan Anda untuk mematikan sandboxing, Claude Code menyertakan pintu keluar: Claude menganalisis pelanggaran dan dapat mencoba kembali perintah dengan parameter `dangerouslyDisableSandbox`.243Anda dapat menonaktifkan retry tanpa sandbox dengan mengatur `"allowUnsandboxedCommands": false` dalam [pengaturan sandbox](/docs/id/settings-reference#sandbox-settings) Anda. Dengan retry dinonaktifkan, Claude Code mengabaikan parameter `dangerouslyDisableSandbox`. Selama sandbox berjalan, perintah yang dijalankan Claude kemudian di-sandbox kecuali cocok dengan entri `excludedCommands`. Untuk mencegah Claude Code menjalankan perintah tanpa sandbox ketika sandbox tidak dapat dimulai, atur juga [`failIfUnavailable`](/docs/id/settings-reference#sandbox-failifunavailable). Tab **Overrides** di `/sandbox` menampilkan pengaturan ini sebagai **Strict sandbox mode**.

166 244

167Perintah yang dicoba kembali berjalan di luar sandbox, sehingga melalui alur izin reguler. Dalam mode Manual Anda mendapatkan prompt konfirmasi. Dalam [auto mode](/docs/id/permission-modes#eliminate-prompts-with-auto-mode), pengklasifikasi mengevaluasi perintah yang mendasar. Sementara [`permissions.blockReadsOutsideWorkingDirectories`](/docs/id/settings-reference#permissions-blockreadsoutsideworkingdirectories) aktif, retry yang memerlukan persetujuan untuk berjalan di luar sandbox meminta Anda sebagai gantinya. Untuk diminta pada setiap retry unsandboxed bahkan dalam mode auto, tambahkan [ask rule](/docs/id/permissions#match-by-input-parameter) untuk `Bash(dangerouslyDisableSandbox:true)`.245Nilai `false` dalam pengaturan pengguna Anda, `--settings`, atau pengaturan terkelola tetap berlaku bahkan ketika pengaturan proyek mengatur `true`. Nilai `false` dalam pengaturan pengguna Anda tidak membuat sandbox menjadi wajib oleh admin, sehingga pengaturan sandbox lain dari proyek tetap berlaku. Sebelum v2.1.285, nilai `true` dari proyek menimpa nilai `false` dalam pengaturan pengguna Anda.

168 246

169Anda dapat menonaktifkan pintu keluar ini dengan mengatur `"allowUnsandboxedCommands": false` dalam [sandbox settings](/docs/id/settings-reference#sandbox-settings) Anda. Dengan pintu keluar dinonaktifkan, Claude Code mengabaikan parameter `dangerouslyDisableSandbox`, dan setiap perintah Claude jalankan harus berjalan sandboxed kecuali Anda telah mencantumkannya dalam `excludedCommands`. Tab **Overrides** `/sandbox` menampilkan pengaturan ini sebagai **Strict sandbox mode**.247Jika Anda atau administrator Anda menonaktifkan retry dalam pengaturan terkelola atau dengan flag `--settings`, sandbox menjadi wajib oleh admin. Claude Code kemudian mengabaikan pengaturan dalam file repositori yang melonggarkan sandbox, termasuk entri `excludedCommands`. [Pengaturan repositori di bawah sandbox yang diwajibkan admin](#repository-settings-under-an-admin-required-sandbox) mencantumkan pengaturan tersebut.

170 248

171Mode strict sandbox berlaku untuk perintah yang Claude jalankan. Perintah yang Anda ketik sendiri di prompt [shell-mode `!`](/docs/id/interactive-mode#shell-mode-with-prefix) berjalan di luar sandbox kecuali sesi adalah salah satu dari ini:249Strict sandbox mode berlaku untuk perintah yang dijalankan Claude. Perintah yang Anda ketik sendiri di [prompt shell-mode `!`](/docs/id/interactive-mode#shell-mode-with-prefix) berjalan di luar sandbox kecuali sesinya merupakan salah satu dari berikut:

172 250

173* **Sesi [background](/docs/id/agent-view)**: mode strict sandbox mencakup perintah shell-mode juga251* **[Sesi latar belakang](/docs/id/agent-view)**: strict sandbox mode juga mencakup perintah shell-mode

174* **Sesi Linux dengan [`CLAUDE_CODE_SUBPROCESS_ENV_SCRUB`](/docs/id/env-vars#variables) diatur**: setiap perintah berjalan sandboxed, perintah shell-mode termasuk252* **Sesi Linux dengan [`CLAUDE_CODE_SUBPROCESS_ENV_SCRUB`](/docs/id/env-vars#variables) diatur**: setiap perintah berjalan di-sandbox, termasuk perintah shell-mode

175 253

176Sebelum v2.1.260, mode strict sandbox sandboxed perintah shell-mode dalam setiap sesi.254Sebelum v2.1.260, strict sandbox mode men-sandbox perintah shell-mode di setiap sesi.

177 255

178<h4 id="temporary-directories">256<h4 id="temporary-directories">

179 Direktori sementara257 Direktori sementara

180</h4>258</h4>

181 259

182Direktori temp per-pengguna dapat ditulis di dalam sandbox secara default, bersama dengan direktori kerja. Kecuali Anda [disable filesystem isolation](#disable-filesystem-isolation), Claude Code menetapkan `$TMPDIR` ke direktori ini untuk perintah sandboxed, sehingga alat yang menulis file sementara bekerja tanpa konfigurasi tambahan.260Direktori temp per pengguna dapat ditulisi di dalam sandbox secara default, bersama dengan direktori kerja. Kecuali Anda [menonaktifkan isolasi filesystem](#disable-filesystem-isolation), Claude Code mengatur `$TMPDIR` ke direktori ini untuk perintah yang di-sandbox, sehingga tool yang menulis file sementara dapat bekerja tanpa konfigurasi tambahan.

183 261

184Perintah unsandboxed mewarisi `$TMPDIR` shell Anda ketika diatur, sehingga sementara isolasi filesystem aktif, perintah sandboxed dan unsandboxed menyelesaikan `$TMPDIR` ke direktori yang berbeda. Jika shell Anda membiarkan `$TMPDIR` tidak diatur atau kosong, perintah unsandboxed yang mereferensikan `$TMPDIR` menerima override [`CLAUDE_CODE_TMPDIR`](/docs/id/env-vars) Anda, atau direktori temp sistem operasi ketika Anda belum menetapkan satu atau override adalah jalur panjang, sehingga variabel tidak berkembang menjadi string kosong. Untuk meneruskan file sementara di antara keduanya, tulis di bawah direktori kerja sebagai gantinya.262Perintah tanpa sandbox mewarisi `$TMPDIR` dari shell Anda ketika variabel tersebut diatur, sehingga selama isolasi filesystem aktif, perintah yang di-sandbox dan yang tidak di-sandbox menyelesaikan `$TMPDIR` ke direktori yang berbeda. Jika shell Anda membiarkan `$TMPDIR` tidak diatur atau kosong, perintah tanpa sandbox yang mereferensikan `$TMPDIR` menerima override [`CLAUDE_CODE_TMPDIR`](/docs/id/env-vars) Anda, atau direktori temp sistem operasi ketika Anda belum mengaturnya atau override tersebut berupa jalur yang panjang, sehingga variabel tersebut tidak diekspansi menjadi string kosong. Untuk meneruskan file sementara di antara keduanya, tuliskan file tersebut di bawah direktori kerja.

185 263

186<h2 id="configure-sandboxing">264<h2 id="configure-sandboxing">

187 Konfigurasi sandboxing265 Mengonfigurasi sandboxing

188</h2>266</h2>

189 267

190Sesuaikan perilaku sandbox melalui file `settings.json` Anda. Lihat [Settings](/docs/id/settings-reference#sandbox-settings) untuk referensi konfigurasi lengkap.268Sesuaikan perilaku sandbox melalui file `settings.json` Anda. Lihat [Pengaturan](/docs/id/settings-reference#sandbox-settings) untuk referensi konfigurasi lengkap.

191 269

192Secara default, perintah sandboxed dapat menulis ke direktori kerja saat ini, direktori temp per-pengguna, dan [direktori apa pun yang telah Anda tambahkan](/docs/id/permissions#additional-directories-grant-file-access-not-configuration) dengan `--add-dir`, `/add-dir`, atau `permissions.additionalDirectories`. Jika perintah subprocess seperti `kubectl`, `terraform`, atau `npm` perlu menulis di luar direktori tersebut, gunakan `sandbox.filesystem.allowWrite` untuk memberikan akses ke jalur tertentu:270Secara default, perintah yang berjalan di sandbox dapat menulis ke direktori kerja saat ini, direktori temp per pengguna, dan [direktori apa pun yang telah Anda tambahkan](/docs/id/permissions#additional-directories-grant-file-access-not-configuration) dengan `--add-dir`, `/add-dir`, atau `permissions.additionalDirectories`. Jika perintah subproses seperti `kubectl`, `terraform`, atau `npm` perlu menulis di luar direktori tersebut, gunakan `sandbox.filesystem.allowWrite` untuk memberikan akses ke path tertentu:

193 271

194```json theme={null}272```json theme={null}

195{273{

202}280}

203```281```

204 282

205Jalur ini diberlakukan pada tingkat OS, sehingga semua perintah yang berjalan di dalam sandbox, termasuk proses anak mereka, menghormatinya. Ini adalah pendekatan yang direkomendasikan ketika alat memerlukan akses tulis ke lokasi tertentu, daripada mengecualikan alat dari sandbox sepenuhnya dengan `excludedCommands`.283Path ini diberlakukan di tingkat OS, sehingga semua perintah yang berjalan di dalam sandbox, termasuk proses turunannya, mematuhinya. Ini adalah pendekatan yang direkomendasikan ketika sebuah tool memerlukan akses tulis ke lokasi tertentu, alih-alih mengecualikan tool tersebut dari sandbox sepenuhnya dengan `excludedCommands`.

206 284

207Ketika Anda menentukan array filesystem yang sama dalam beberapa [settings scopes](/docs/id/settings#settings-precedence), Claude Code menggabungkannya, menggabungkan jalur dari setiap scope daripada mengganti array satu scope dengan yang lain.285Ketika Anda mendefinisikan array filesystem yang sama di beberapa [cakupan pengaturan](/docs/id/settings#settings-precedence), Claude Code menggabungkannya, yaitu mengombinasikan path dari setiap cakupan alih-alih mengganti array dari satu cakupan dengan array dari cakupan lain.

208 286

209Jika Anda mengecualikan sumber dengan [`--setting-sources`](/docs/id/cli-reference) pada CLI atau [`settingSources`](/docs/id/agent-sdk/claude-code-features#control-filesystem-settings-with-settingsources) dalam Agent SDK, Claude Code mengabaikan entri `sandbox.filesystem` nya, aturan izin `Edit` nya, dan aturan penolakan `Read` nya saat membangun konfigurasi sandbox. Memerlukan Claude Code v2.1.246 atau lebih baru.287Jika Anda mengecualikan suatu sumber dengan [`--setting-sources`](/docs/id/cli-reference) di CLI atau [`settingSources`](/docs/id/agent-sdk/claude-code-features#control-filesystem-settings-with-settingsources) di Agent SDK, Claude Code mengabaikan entri `sandbox.filesystem`, aturan izin `Edit`, dan aturan deny `Read` dari sumber tersebut saat membangun konfigurasi sandbox. Memerlukan Claude Code v2.1.246 atau lebih baru.

210 288

211Ketika Anda mengedit daftar filesystem ini selama sesi, Claude Code [menerapkan perubahan ke sesi yang sedang berjalan](/docs/id/settings#when-edits-take-effect), sehingga perintah sandboxed berikutnya berjalan di bawah jalur baru.289Ketika Anda mengedit daftar filesystem ini selama sesi, Claude Code [menerapkan perubahan tersebut ke sesi yang sedang berjalan](/docs/id/settings#when-edits-take-effect), sehingga perintah sandbox berikutnya berjalan dengan path yang baru.

212 290

213Awalan jalur mengontrol bagaimana jalur diselesaikan:291Path filesystem sandbox menggunakan konvensi standar: `/tmp/build` adalah path absolut dan `~/.kube` relatif terhadap direktori home Anda. Ini berbeda dari [aturan izin Read dan Edit](/docs/id/permissions#read-and-edit), yang menggunakan `//path` untuk path absolut dan `/path` untuk path relatif terhadap proyek. Untuk path relatif, garis miring di akhir, dan wildcard, lihat [Prefiks path sandbox](/docs/id/settings-reference#sandbox-path-prefixes).

214 292

215| Awalan | Arti | Contoh |293Anda juga dapat menolak akses tulis atau baca menggunakan `sandbox.filesystem.denyWrite` dan `sandbox.filesystem.denyRead`, dan mengizinkan kembali path tertentu di dalam wilayah yang ditolak menggunakan `sandbox.filesystem.allowRead`. Ketika aturan baca tumpang tindih, aturan dengan path yang lebih sempit yang berlaku:

216| :- | :- | :- |

217| `/` | Jalur absolut dari akar filesystem | `/tmp/build` tetap `/tmp/build` |

218| `~/` | Relatif terhadap direktori home | `~/.kube` menjadi `$HOME/.kube` |

219| `./` atau tanpa awalan | Relatif terhadap akar proyek untuk pengaturan proyek, atau ke `~/.claude` untuk pengaturan pengguna | `./output` dalam `.claude/settings.json` diselesaikan ke `<project-root>/output` |

~~220~~

221Sintaks ini berbeda dari [Read and Edit permission rules](/docs/id/permissions#read-and-edit), yang menggunakan `//path` untuk absolut dan `/path` untuk relatif proyek. Jalur filesystem sandbox menggunakan konvensi standar: `/tmp/build` adalah absolut. Untuk bagaimana Claude Code memperlakukan garis miring di akhir atau wildcard dalam jalur ini, lihat [Sandbox path prefixes](/docs/id/settings-reference#sandbox-path-prefixes).

222 294

223Anda juga dapat menolak akses tulis atau baca menggunakan `sandbox.filesystem.denyWrite` dan `sandbox.filesystem.denyRead`, dan mengizinkan kembali jalur tertentu dalam wilayah yang ditolak menggunakan `sandbox.filesystem.allowRead`. Ketika aturan baca tumpang tindih, jalur yang lebih spesifik menang:295| Contoh aturan | Hasil |

~~224~~

225| Aturan contoh | Hasil |

226| :- | :- |296| :- | :- |

227| `"denyRead": ["~/"]` dengan `"allowRead": ["~/projects"]` | `~/projects` dapat dibaca dan sisa direktori home tetap diblokir. Izin yang lebih sempit membuka kembali bagian itu dari wilayah yang ditolak |297| `"denyRead": ["~/"]` dengan `"allowRead": ["~/projects"]` | `~/projects` dapat dibaca dan bagian lain dari direktori home tetap diblokir. Allow yang lebih sempit membuka kembali bagian tersebut dari wilayah yang ditolak |

228| `"allowRead": ["~/"]` dengan `"denyRead": ["~/.env"]` | `~/.env` tetap diblokir dan sisa direktori home dapat dibaca. Penolakan yang tepat berlaku di dalam izin yang lebih luas, jadi izin yang luas tidak dapat secara diam-diam membuka kembali rahasia |298| `"allowRead": ["~/"]` dengan `"denyRead": ["~/.env"]` | `~/.env` tetap diblokir dan bagian lain dari direktori home dapat dibaca. Deny tetap berlaku di dalam allow yang lebih luas, sehingga allow yang luas tidak dapat secara diam-diam mengekspos kembali sebuah rahasia |

229| `"allowRead": ["~/"]` dengan `"denyRead": ["~/**/.env"]` | Setiap `.env` di bawah direktori home tetap diblokir dan sisanya dapat dibaca. [Wildcard deny](/docs/id/settings-reference#sandbox-path-prefixes) berlaku di dalam izin yang lebih luas dengan cara yang sama seperti jalur yang tepat |299| `"allowRead": ["~/"]` dengan `"denyRead": ["~/**/.env"]` | Setiap `.env` di bawah direktori home tetap diblokir dan sisanya dapat dibaca. [Deny dengan wildcard](/docs/id/settings-reference#sandbox-path-prefixes) tetap berlaku di dalam allow yang lebih luas dengan cara yang sama seperti path yang persis |

230 300

231Contoh di bawah memblokir pembacaan dari seluruh direktori home sambil tetap memungkinkan pembacaan dari proyek saat ini. Tempatkan di `.claude/settings.json` proyek Anda, karena jalur relatif `.` diselesaikan ke akar proyek hanya ketika konfigurasi berada dalam pengaturan proyek:301Contoh di bawah ini memblokir pembacaan dari seluruh direktori home sambil tetap mengizinkan pembacaan dari proyek saat ini. Letakkan di `.claude/settings.json` proyek Anda, karena path relatif `.` di-resolve ke root proyek hanya ketika konfigurasi berada di pengaturan proyek:

232 302

233```json theme={null}303```json theme={null}

234{304{

242}312}

243```313```

244 314

245Jika Anda menempatkan konfigurasi yang sama dalam `~/.claude/settings.json`, `.` akan diselesaikan ke `~/.claude` sebagai gantinya, dan file proyek akan tetap diblokir oleh aturan `denyRead`.315Jika Anda meletakkan konfigurasi yang sama di `~/.claude/settings.json`, `.` akan di-resolve ke `~/.claude`, dan file proyek akan tetap diblokir oleh aturan `denyRead`.

316

317Untuk menolak akses baca perintah sandbox ke direktori home dan volume yang di-mount sambil menjaga direktori kerja tetap dapat dibaca, atur [`permissions.blockReadsOutsideWorkingDirectories`](/docs/id/settings-reference#permissions-blockreadsoutsideworkingdirectories) alih-alih menulis aturan path.

318

319<h3 id="run-commands-outside-the-sandbox-with-excludedcommands">

320 Menjalankan perintah di luar sandbox dengan `excludedCommands`

321</h3>

322

323Cantumkan pola perintah di [`sandbox.excludedCommands`](/docs/id/settings-reference#sandbox-excludedcommands) untuk menjalankan perintah yang cocok di luar sandbox, yang berarti tanpa pembatasan filesystem dan tanpa proxy jaringan. Gunakan ini untuk tool yang tidak dapat bekerja di dalam sandbox dan yang Anda percayai dengan akses penuh Anda. Tool yang memerlukan satu direktori atau satu host tambahan mungkin dapat bekerja dengan `allowWrite` atau `allowedDomains`, yang menjaga perintah tetap berada di dalam sandbox.

324

325Contoh ini mengeluarkan perintah `docker compose` dari sandbox. Simpan di `~/.claude/settings.json` untuk menerapkannya ke semua proyek Anda:

326

327```json theme={null}

328{

329 "sandbox": {

330 "enabled": true,

331 "excludedCommands": ["docker compose *"]

332 }

333}

334```

335

336Claude Code memeriksa entri Anda terhadap setiap panggilan Bash dan Monitor. Sebuah panggilan adalah seluruh baris perintah yang dikirim Claude, yang dapat merangkai beberapa perintah. Aturan berikut menentukan apakah sebuah panggilan keluar dari sandbox:

337

338* **Akhiri pola dengan ` *`**: entri menggunakan sintaks yang sama dengan [aturan izin](/docs/id/permissions#permission-rule-syntax) `Bash(...)`, di mana pola tanpa wildcard merupakan kecocokan persis. `docker` hanya cocok dengan `docker` tanpa argumen. `docker *` cocok dengan `docker` dengan atau tanpa argumen

339* **Setiap perintah dalam panggilan harus cocok**: `npm ci && docker compose build` tetap berada di dalam sandbox kecuali ada entri lain yang mencakup `npm ci`

340* **Claude Code mencocokkan teks panggilan**: skrip atau target `make` yang memanggil `docker` secara internal tidak cocok, begitu pula `/usr/local/bin/docker`

341* **Beberapa panggilan tetap berada di dalam sandbox**: redirect ke file, `cd`, atau command substitution seperti `$(...)` membuat seluruh panggilan tetap berada di dalam sandbox. [Entri referensi](/docs/id/settings-reference#sandbox-excludedcommands) mencantumkan lebih banyak panggilan yang tetap berada di dalam sandbox

342* **Lokasi penyimpanan entri dapat berpengaruh**: selama sandbox [diwajibkan oleh admin](#repository-settings-under-an-admin-required-sandbox), Claude Code mengabaikan entri di `.claude/settings.json` dan `.claude/settings.local.json`

343

344Perintah yang dikecualikan melewati alur izin biasa:

246 345

247Untuk menolak perintah sandboxed akses baca ke direktori home dan volume yang dipasang sambil menjaga direktori kerja tetap dapat dibaca, atur [`permissions.blockReadsOutsideWorkingDirectories`](/docs/id/settings-reference#permissions-blockreadsoutsideworkingdirectories) sebagai gantinya dari menulis aturan jalur.346* [Perintah read-only](/docs/id/permissions#read-only-commands) dan perintah yang dicakup oleh aturan allow Anda berjalan tanpa permintaan izin

347* Dalam auto mode, pengklasifikasi meninjau perintah lain yang dikecualikan

348* Dalam mode `bypassPermissions`, perintah yang dikecualikan berjalan tanpa permintaan izin kecuali ada aturan ask yang cocok dengannya

349

350Untuk memastikan sebuah entri cocok, beralihlah ke mode Manual dan minta Claude menjalankan perintah yang cocok yang mengubah sesuatu, seperti `docker compose up -d`. Dialog izin akan berjudul "Bash command (unsandboxed)".

351

352<Warning>

353 Perintah yang dikecualikan berjalan dengan akses penuh Anda. Entri yang luas seperti `docker *` mencakup semua hal yang dapat dilakukan tool tersebut. Jika Anda menulis pola yang mencakup interpreter, skrip di dalam direktori kerja Anda, atau tool yang bertindak atas file di sana, seperti yang dilakukan `docker compose` dengan file compose-nya, Claude dapat menulis file tersebut lalu menjalankannya di luar sandbox. Pola yang lebih sempit menyisakan lebih sedikit hal yang dapat dijalankan Claude di luar sandbox.

354</Warning>

248 355

249<h3 id="disable-filesystem-isolation">356<h3 id="disable-filesystem-isolation">

250 Nonaktifkan isolasi filesystem357 Menonaktifkan isolasi filesystem

251</h3>358</h3>

252 359

253Atur `sandbox.filesystem.disabled` ke `true` untuk melewati isolasi filesystem sambil menjaga isolasi jaringan. Contoh di bawah mematikan isolasi filesystem sambil menjaga daftar izin domain jaringan:360Atur `sandbox.filesystem.disabled` ke `true` untuk melewati isolasi filesystem sambil tetap mempertahankan isolasi jaringan. Contoh di bawah ini mematikan isolasi filesystem sambil tetap mempertahankan allowlist domain jaringan:

254 361

255```json theme={null}362```json theme={null}

256{363{

266}373}

267```374```

268 375

269Sandbox memiliki dua lapisan independen: [filesystem isolation](#filesystem-isolation) mengontrol jalur mana yang dapat dibaca dan ditulis perintah sandboxed, dan [network isolation](#network-isolation) mengontrol domain mana yang dapat mereka jangkau. Dengan lapisan filesystem mati, perintah sandboxed mendapatkan akses baca dan tulis tanpa batas ke filesystem host, sementara egress jaringan mereka tetap terbatas pada domain yang Anda izinkan. Matikan lapisan ketika Anda sandbox untuk mengontrol tempat perintah terhubung daripada apa yang mereka tulis.376Sandbox memiliki dua lapisan independen: [isolasi filesystem](#filesystem-isolation) mengontrol path mana yang dapat dibaca dan ditulis oleh perintah sandbox, dan [isolasi jaringan](#network-isolation) mengontrol domain mana yang dapat mereka jangkau. Dengan lapisan filesystem dimatikan, perintah sandbox mendapatkan akses baca dan tulis tanpa batas ke filesystem host, sementara lalu lintas jaringan keluarnya tetap terbatas pada domain yang Anda izinkan. Matikan lapisan ini ketika Anda menggunakan sandbox untuk mengontrol ke mana perintah terhubung, bukan apa yang mereka tulis.

270 377

271Pengaturan ini mati secara default dan berlaku pada platform tempat sandbox berjalan: macOS, Linux, dan WSL2. Memerlukan Claude Code v2.1.216 atau lebih baru.378`sandbox.filesystem.disabled` default ke `false`. Memerlukan Claude Code v2.1.216 atau lebih baru.

272 379

273<Warning>380<Warning>

274 Dengan isolasi filesystem mati dan perintah auto-allowed, perintah sandboxed dapat menulis file yang kemudian dijalankan atau dibaca perintah lain, seperti file startup shell, executable di `$PATH`, atau `~/.claude/settings.json`, dan menggunakannya untuk memperluas akses mereka sendiri pada run berikutnya. Atur `filesystem.disabled` ke `true` hanya untuk workload yang Anda percayai tidak akan meningkatkan akses mereka sendiri. Mengunci domain jaringan dengan [`allowManagedDomainsOnly`](#keep-developers-from-widening-the-policy) mempersempit risiko tetapi tidak menghilangkannya, karena kunci itu hanya berlaku untuk perintah yang berjalan di dalam sandbox.381 Dengan isolasi filesystem dimatikan dan perintah diizinkan secara otomatis, perintah sandbox dapat menulis file yang kemudian dijalankan atau dibaca oleh perintah berikutnya, seperti file startup shell, executable di `$PATH`, atau `~/.claude/settings.json`, dan menggunakannya untuk memperluas aksesnya sendiri pada eksekusi berikutnya. Atur `filesystem.disabled` ke `true` hanya untuk beban kerja yang Anda percayai tidak akan meningkatkan aksesnya sendiri. Mengunci domain jaringan dengan [`allowManagedDomainsOnly`](#keep-developers-from-widening-the-policy) mempersempit risiko tetapi tidak menghilangkannya, karena kunci tersebut hanya berlaku untuk perintah yang berjalan di dalam sandbox.

275</Warning>382</Warning>

276 383

277<h4 id="which-settings-can-disable-it">384<h4 id="which-settings-can-disable-it">

278 Pengaturan mana yang dapat menonaktifkannya385 Pengaturan mana yang dapat menonaktifkannya

279</h4>386</h4>

280 387

281Karena mematikan isolasi filesystem memperluas apa yang dapat dilakukan perintah sandboxed, Claude Code menghormati `filesystem.disabled` dari sumber pengaturan ini saja:388Karena mematikan isolasi filesystem memperluas apa yang dapat dilakukan perintah sandbox, Claude Code hanya menghormati `filesystem.disabled` dari sumber pengaturan berikut:

282 389

283* Pengaturan pengguna, pengaturan terkelola, dan bendera CLI `--settings` dapat mengaturnya. Pengaturan proyek dalam `.claude/settings.json` dan `.claude/settings.local.json` tidak dapat, jadi proyek yang diperiksa tidak dapat mematikan isolasi filesystem.390* Pengaturan pengguna, pengaturan terkelola, dan flag CLI `--settings` dapat mengaturnya. Pengaturan proyek di `.claude/settings.json` dan `.claude/settings.local.json` tidak dapat, sehingga proyek yang di-checkout tidak dapat mematikan isolasi filesystem.

284* Ketika pengaturan terkelola mengonfigurasi `sandbox.filesystem` sama sekali, atau mencantumkan entri `sandbox.credentials.files` apa pun dengan `"mode": "deny"`, hanya pengaturan terkelola yang dapat mengatur kunci. Ini menjaga pembatasan filesystem yang diterapkan administrator tetap berlaku; untuk melonggarkan penerapan seperti itu, atur `"disabled": true` dalam pengaturan terkelola.391* Ketika pengaturan terkelola mengonfigurasi `sandbox.filesystem` sama sekali, atau mencantumkan entri `sandbox.credentials.files` apa pun dengan `"mode": "deny"`, hanya pengaturan terkelola yang dapat mengatur kunci tersebut. Ini menjaga pembatasan filesystem yang di-deploy administrator tetap berlaku; untuk melonggarkan deployment semacam itu, atur `"disabled": true` di pengaturan terkelola.

285* Ketika [`CLAUDE_CODE_SUBPROCESS_ENV_SCRUB`](/docs/id/env-vars) diatur, Claude Code mengabaikan `filesystem.disabled` dari setiap sumber, termasuk pengaturan terkelola, dan menjaga isolasi filesystem tetap aktif.392* Ketika [`CLAUDE_CODE_SUBPROCESS_ENV_SCRUB`](/docs/id/env-vars) diatur, Claude Code mengabaikan `filesystem.disabled` dari setiap sumber, termasuk pengaturan terkelola, dan tetap mengaktifkan isolasi filesystem.

286 393

287Apakah entri `credentials.files` terkelola menyematkan `filesystem.disabled`, mengunci kunci ke pengaturan terkelola sehingga pengembang tidak dapat mematikan isolasi filesystem, tergantung pada `mode` entri dan apa yang terjadi pada entri ketika sandbox dimulai:394Entri `mask` yang [valid](/docs/id/settings-reference#invalid-credential-entries-in-managed-settings) tidak mengunci kunci tersebut, bahkan ketika Claude Code [melakukan fallback ke `deny`](#mask-credential-files) untuk entri tersebut saat startup. Cantumkan path yang tidak dapat di-mask, seperti direktori kredensial, sebagai entri `deny` eksplisit di pengaturan terkelola, yang mengunci kunci tersebut.

~~288~~

289| Entri terkelola | Menyematkan `filesystem.disabled` | Apa yang melindungi file ketika isolasi mati |

290| - | - | - |

291| `"mode": "deny"` | Ya | Tidak ada: blok baca adalah bagian dari lapisan filesystem |

292| `"mode": "mask"`, diterapkan sebagai mask | Tidak | Masking itu sendiri: [sentinel copy dan proxy](#mask-credential-files) di Linux dan WSL2, aturan baca sandbox itu sendiri di macOS |

293| `"mode": "mask"`, [jatuh kembali ke `deny`](#mask-credential-files) saat setup | Tidak | Tidak ada, sama seperti `deny`. Daftarkan jalur yang tidak dapat di-mask, seperti direktori, sebagai entri `deny` eksplisit, yang menyematkan kunci |

294| `"mode": "mask"`, [terdegradasi ke `deny` oleh validasi](/docs/id/managed-settings#invalid-entries-in-managed-settings) | Ya, seperti entri `deny` eksplisit | Tidak ada, sama seperti `deny` |

~~295~~

296Fallback terjadi ketika sandbox dimulai, setelah Claude Code telah membaca pengaturan yang pemeriksaan pin berjalan, jadi entri yang jatuh kembali tidak pernah menyematkan. Validasi menulis ulang entri yang tidak valid ke `deny` saat pengaturan dimuat, jadi entri yang terdegradasi menyematkan seperti yang Anda tulis sebagai `deny`.

297 395

298<h4 id="what-changes-when-filesystem-isolation-is-off">396<h4 id="what-changes-when-filesystem-isolation-is-off">

299 Apa yang berubah ketika isolasi filesystem mati397 Apa yang berubah saat isolasi filesystem dimatikan

300</h4>398</h4>

301 399

302Mengatur `filesystem.disabled` mengangkat perlindungan yang lapisan filesystem itu sendiri berlakukan. Perlindungan yang lapisan lain berlakukan terus berlaku:400Mengatur `filesystem.disabled` mencabut perlindungan yang diberlakukan oleh lapisan filesystem itu sendiri. Perlindungan yang diberlakukan oleh lapisan lain tetap berlaku:

303 401

304| Perlindungan | Dengan isolasi filesystem mati |402| Perlindungan | Dengan isolasi filesystem dimatikan |

305| - | - |403| - | - |

306| `filesystem.denyRead` dan [`credentials.files`](#protect-credentials) blok baca `deny` | Tidak diberlakukan. Lapisan filesystem menerapkan keduanya |404| `filesystem.denyRead` dan blokir baca `deny` [`credentials.files`](#protect-credentials) | Tidak diberlakukan. Lapisan filesystem yang menerapkan keduanya |

307| `credentials.envVars` entri `deny` dan `mask` | Diberlakukan. Scrubbing variabel lingkungan independen dari lapisan filesystem |405| Entri `deny` dan `mask` `credentials.envVars` | Diberlakukan. Pembersihan environment variable tidak bergantung pada lapisan filesystem |

308| [`credentials.files` entri `mask`](#mask-credential-files) diterapkan sebagai mask | Diberlakukan: masking independen dari lapisan filesystem. Entri yang [jatuh kembali ke `deny`](#mask-credential-files) tidak diberlakukan, seperti entri `deny` apa pun |406| [Entri `mask` `credentials.files`](#mask-credential-files) yang diterapkan sebagai mask | Diberlakukan: masking tidak bergantung pada lapisan filesystem. Entri yang [mengalami fallback ke `deny`](#mask-credential-files) tidak diberlakukan, seperti entri `deny` lainnya |

309 407

310Dua hal lain berubah:408Dua hal lain berubah:

311 409

312* Perintah sandboxed mewarisi `$TMPDIR` shell Anda daripada direktori temp per-pengguna, karena setiap direktori temp dapat ditulis dan Claude Code tidak lagi mengarahkan perintah ke yang per-pengguna.410* Perintah sandbox mewarisi `$TMPDIR` shell Anda alih-alih direktori temp per pengguna, karena setiap direktori temp dapat ditulis dan Claude Code tidak lagi mengarahkan perintah ke direktori per pengguna.

313 411

314 Di Linux variabel sering tidak diatur dalam shell induk. Panduan alat Bash memberi tahu Claude untuk membuat direktori scratch dengan `mktemp -d` daripada mengandalkan `$TMPDIR`.412 Di Linux, variabel ini sering kali tidak diatur di shell induk. Panduan tool Bash memberi tahu Claude untuk membuat direktori sementara dengan `mktemp -d` alih-alih mengandalkan `$TMPDIR`.

315* [`autoAllowBashIfSandboxed`](/docs/id/settings-reference#sandbox-autoallowbashifsandboxed) masih default ke `true`, jadi perintah sandboxed terus berjalan tanpa prompt. Atur ke `false` untuk meminta perintah sandboxed.413* [`autoAllowBashIfSandboxed`](/docs/id/settings-reference#sandbox-autoallowbashifsandboxed) tetap default ke `true`, sehingga perintah sandbox tetap berjalan tanpa permintaan izin. Atur ke `false` untuk meminta izin bagi perintah sandbox.

316 414

317<h3 id="protect-credentials">415<h3 id="protect-credentials">

318 Lindungi kredensial416 Melindungi kredensial

319</h3>417</h3>

320 418

321Pengaturan `sandbox.credentials` mendeklarasikan file kredensial dan variabel lingkungan yang harus dilindungi dari perintah sandboxed. Setiap entri memberi nama jalur file atau variabel lingkungan dan `mode`. Blok `credentials` khusus menjaga aturan kredensial dikelompokkan bersama dan terpisah dari aturan filesystem umum.419Pengaturan `sandbox.credentials` mendeklarasikan file kredensial dan environment variable yang akan dilindungi dari perintah sandbox. Setiap entri menyebutkan path file atau environment variable dan sebuah `mode`. Blok `credentials` khusus ini menjaga aturan kredensial tetap terkelompok dan terpisah dari aturan filesystem umum.

322 420

323Untuk entri dengan `"mode": "deny"`, jalur file ditolak untuk pembacaan di dalam sandbox, pembatasan yang sama yang diterapkan `filesystem.denyRead`, dan variabel lingkungan tidak diatur sebelum setiap perintah sandboxed berjalan. Perlindungan file adalah bagian dari lapisan filesystem, jadi tidak berlaku jika Anda [menonaktifkan isolasi filesystem](#disable-filesystem-isolation); perlindungan variabel lingkungan masih berlaku.421Untuk entri dengan `"mode": "deny"`, path file ditolak untuk dibaca di dalam sandbox, pembatasan yang sama dengan yang diterapkan `filesystem.denyRead`, dan environment variable dihapus sebelum setiap perintah sandbox dijalankan. Perlindungan file merupakan bagian dari lapisan filesystem, sehingga tidak berlaku jika Anda [menonaktifkan isolasi filesystem](#disable-filesystem-isolation); perlindungan environment variable tetap berlaku.

324 422

325Contoh di bawah memblokir pembacaan file kredensial AWS dan direktori SSH serta menghapus `GITHUB_TOKEN` dan `NPM_TOKEN` dari lingkungan perintah sandboxed:423Contoh di bawah ini memblokir pembacaan file kredensial AWS dan direktori SSH serta menghapus `GITHUB_TOKEN` dan `NPM_TOKEN` dari environment perintah sandbox:

326 424

327```json theme={null}425```json theme={null}

328{426{

342}440}

343```441```

344 442

345Entri variabel lingkungan dan entri file juga menerima `"mode": "mask"`, dijelaskan di bawah [Mask credentials](#mask-credentials).443Entri environment variable dan entri file juga menerima `"mode": "mask"`, yang dijelaskan di [Melakukan mask kredensial](#mask-credentials).

346 444

347Jalur file mengikuti [aturan awalan](/docs/id/settings-reference#sandbox-path-prefixes) yang sama dengan pengaturan `sandbox.filesystem.*`.445Path file mengikuti [aturan prefiks](/docs/id/settings-reference#sandbox-path-prefixes) yang sama dengan pengaturan `sandbox.filesystem.*`.

348 446

349Claude Code menggabungkan entri `deny` dari setiap [settings scope](/docs/id/settings#settings-precedence) yang dimuat sesi. Entri `deny` hanya pernah mempersempit akses, jadi scope apa pun dapat menambahkan satu, tetapi tidak ada scope yang dapat menghapus satu yang ditambahkan scope lain.447Claude Code menggabungkan entri `deny` dari setiap [cakupan pengaturan](/docs/id/settings#settings-precedence) yang dimuat sesi. Entri `deny` hanya pernah mempersempit akses, sehingga cakupan mana pun dapat menambahkannya, tetapi tidak ada cakupan yang dapat menghapus entri yang ditambahkan oleh cakupan lain.

350 448

351Ketika Anda [mengecualikan sumber pengaturan](#configure-sandboxing):449Ketika Anda [mengecualikan sumber pengaturan](#configure-sandboxing):

352 450

353* **Pengaturan proyek atau lokal**: Claude Code tidak menerapkan entri `credentials` apa pun dari mereka. Memerlukan Claude Code v2.1.246 atau lebih baru.451* **Pengaturan proyek atau lokal**: Claude Code tidak menerapkan satu pun entri `credentials` dari sumber tersebut. Memerlukan Claude Code v2.1.246 atau lebih baru.

354* **Pengaturan pengguna**: Claude Code masih menerapkan entri `deny` dalam `~/.claude/settings.json` dan menjaga [entri `mask` file](#mask-credential-files) nya sebagai pembatasan, tetapi menghapus [entri `mask` variabel lingkungan](#mask-environment-variables) nya.452* **Pengaturan pengguna**: Claude Code tetap menerapkan entri `deny` di `~/.claude/settings.json` dan mempertahankan [entri `mask` file](#mask-credential-files) sebagai pembatasan yang tidak lagi memberi wewenang kepada proxy untuk mensubstitusi nilai sebenarnya, tetapi membuang [entri `mask` environment variable](#mask-environment-variables).

355 453

356Tidak ada daftar penolakan kredensial bawaan, jadi hanya file dan variabel yang Anda daftarkan yang dibatasi.454Tidak ada daftar deny kredensial bawaan, sehingga hanya file dan variabel yang Anda cantumkan yang dibatasi.

357 455

358`sandbox.credentials` mempengaruhi perintah Bash sandboxed saja. Untuk menghapus kredensial dari semua subprocess terlepas dari sandboxing, atur [`CLAUDE_CODE_SUBPROCESS_ENV_SCRUB`](/docs/id/env-vars).456`sandbox.credentials` hanya memengaruhi perintah Bash sandbox. Untuk menghapus kredensial dari semua subproses terlepas dari sandboxing, atur [`CLAUDE_CODE_SUBPROCESS_ENV_SCRUB`](/docs/id/env-vars).

359 457

360<h3 id="mask-credentials">458<h3 id="mask-credentials">

361 Mask credentials459 Melakukan mask kredensial

362</h3>460</h3>

363 461

364Masking berjalan lebih jauh daripada entri `deny` di bawah [Protect credentials](#protect-credentials). Daripada memblokir kredensial, Claude Code menunjukkan perintah sandboxed placeholder, sentinel, dan [sandbox proxy](#network-isolation) menukar nilai asli pada permintaan keluar ke host yang Anda izinkan. Untuk file, substitusi adalah perilaku Linux dan WSL2; [macOS memblokir file sebagai gantinya](#mask-credential-files).462Ketika Anda melakukan mask pada kredensial, Claude Code menampilkan placeholder per sesi yang disebut sentinel kepada perintah sandbox, dan [proxy sandbox](#network-isolation) mensubstitusi nilai sebenarnya pada permintaan keluar ke host yang Anda izinkan. Entri `deny` di [Melindungi kredensial](#protect-credentials) justru memblokir kredensial. Untuk file di macOS, Claude Code [memblokir file tersebut](#mask-credential-files) alih-alih melakukan mask.

365 463

366<h4 id="mask-environment-variables">464Melakukan mask environment variable memerlukan Claude Code v2.1.199 atau lebih baru. Referensi [`sandbox.credentials`](/docs/id/settings-reference#sandbox-credentials) mencantumkan setiap field.

367 Mask environment variables

368</h4>

369 465

370`"mode": "mask"` melindungi kredensial sambil membuat alat yang mengotentikasi dengannya tetap berfungsi. `deny` menghapus variabel sepenuhnya, yang juga merusak alat yang membutuhkannya, seperti `gh` atau `npm`. Memerlukan Claude Code v2.1.199 atau lebih baru.466Masking memerlukan hal berikut:

371 467

372Dengan `mask`, perintah sandboxed melihat nilai sentinel per-sesi daripada yang asli. Setiap entri `mask` dapat mencantumkan `injectHosts`, host tempat nilai asli diizinkan untuk menjangkau. Ketika permintaan meninggalkan sandbox untuk salah satu dari mereka, [sandbox proxy](#network-isolation) mengganti sentinel dengan nilai asli. Perintah dan apa pun yang dicatat tidak pernah memegang kredensial asli, tetapi permintaannya tetap mengotentikasi.468* **Terminasi TLS**: proxy mensubstitusi nilai sebenarnya di dalam isi permintaan, sehingga proxy harus dapat melihatnya. Atur [`network.tlsTerminate`](/docs/id/settings-reference#sandbox-network-tlsterminate) agar proxy menghentikan TLS sendiri. Tanpanya, masking gagal tanpa mengekspos apa pun: perintah tetap hanya melihat sentinel, tetapi sentinel mencapai server tanpa perubahan dan autentikasi gagal. Claude Code melaporkan kesalahan konfigurasi ini saat startup.

469* **Tujuan yang diizinkan**: setiap entri `mask` dapat mencantumkan `injectHosts`, yaitu host yang diizinkan untuk dijangkau oleh nilai sebenarnya. Proxy hanya menyuntikkan pada koneksi yang diterima oleh [allowlist domain](#network-isolation), sehingga setiap host `injectHosts` juga harus dapat dijangkau melalui `network.allowedDomains`. Untuk entri `mask` tanpa `injectHosts`, proxy mensubstitusi nilai sebenarnya pada permintaan ke setiap host di `network.allowedDomains`.

470* **Cakupan pengaturan tepercaya**: masking memberi wewenang kepada proxy untuk mengirimkan kredensial sebenarnya Anda ke suatu tempat, sehingga Claude Code hanya menghormati entri `mask`, `network.tlsTerminate`, [`credentials.allowPlaintextInject`](/docs/id/settings-reference#sandbox-credentials-allowplaintextinject), `awsPairs`, dan `sigv4` dari pengaturan pengguna, pengaturan terkelola, dan flag `--settings`. Claude Code mengabaikannya di `.claude/settings.json` atau `.claude/settings.local.json` milik repositori. Ketika administrator Anda mengirimkan entri `mask`, `network.tlsTerminate`, atau `credentials.allowPlaintextInject` melalui pengaturan yang dikelola server, entri tersebut dihitung sebagai [pengaturan yang memerlukan persetujuan](/docs/id/server-managed-settings#security-approval-dialogs).

373 471

374Proxy mengganti kredensial di dalam konten permintaan, jadi harus melihatnya. Atur [`network.tlsTerminate`](/docs/id/settings-reference#sandbox-network-tlsterminate) sehingga proxy menghentikan TLS itu sendiri.472<h4 id="mask-environment-variables">

~~375~~ 473 Melakukan mask environment variable

376Tanpa itu, masking gagal tanpa mengekspos apa pun: perintah masih hanya melihat sentinel, tetapi sentinel mencapai server tidak berubah dan otentikasi gagal. Claude Code melaporkan kesalahan konfigurasi ini saat startup.474</h4>

~~377~~

378Substitusi mencakup header dan badan permintaan. Permintaan yang mengotentikasi dengan tanda tangan yang berasal dari kredensial, daripada kredensial itu sendiri, perlu ditandatangani ulang di proxy; [Re-sign AWS requests](#re-sign-aws-requests) mencakup bagaimana itu bekerja untuk AWS.

379 475

380Proxy menyuntik hanya pada koneksi yang [daftar domain allowlist](#network-isolation) mengakui, jadi setiap tujuan `injectHosts` juga harus dapat dijangkau melalui `network.allowedDomains`.476Untuk melakukan mask pada environment variable, atur `"mode": "mask"` pada entri `credentials.envVars`-nya. Perintah tersebut dan apa pun yang dicatatnya ke log tidak pernah memegang kredensial sebenarnya, tetapi permintaannya tetap terautentikasi. Ketika variabel yang sama dicantumkan dengan `deny` di cakupan mana pun, `deny` diutamakan.

381 477

382Contoh di bawah mask dua token. `GH_TOKEN` diganti hanya pada permintaan ke `api.github.com`, sementara `NPM_TOKEN` tidak memiliki `injectHosts` dan diganti pada permintaan ke setiap host dalam `network.allowedDomains`.478Contoh ini melakukan mask pada dua token. `GH_TOKEN` disubstitusi hanya pada permintaan ke `api.github.com`, sedangkan `NPM_TOKEN` tidak memiliki `injectHosts` dan disubstitusi pada permintaan ke setiap host di `network.allowedDomains`:

383 479

384```json theme={null}480```json theme={null}

385{481{

399}495}

400```496```

401 497

402<span id="ipv6-destinations-in-injecthosts" />Ejakan tujuan IPv6 secara berbeda dalam dua daftar, karena setiap daftar memiliki matcher-nya sendiri:498Masking mengganti seluruh nilai secara default. Untuk nilai yang memiliki struktur, seperti string koneksi `DATABASE_URL` atau JWT, gunakan [field `extract`, `decode`, `maskClaims`, dan `onExtractNoMatch`](/docs/id/settings-reference#sandbox-credentials-envvars) agar tool yang mem-parse nilai tersebut tetap berfungsi.

~~403~~

404* **`network.allowedDomains`**: [bentuk bracketed yang digunakan daftar domain](#ipv6-addresses-in-domain-lists), seperti `"[::1]"`. Proxy memeriksa daftar ini untuk mengakui koneksi.

405* **`injectHosts`**: alamat telanjang dalam bentuk kanonik terkompresinya, seperti `"::1"` atau `"2001:db8::1"`. Proxy mencocokkan setiap entri terhadap alamat tujuan koneksi yang telanjang, mengabaikan port, jadi ejakan bracketed, zone-ID, atau terkompresi secara berbeda tidak pernah cocok dan proxy tidak pernah menyuntik kredensial di sana.

~~406~~

407`claude doctor` menandai entri `injectHosts` yang tidak pernah dapat cocok dengan peringatan `Sandbox credential injectHosts entries can never match their destination`. Pemeriksaan ini memerlukan Claude Code v2.1.229 atau lebih baru.

~~408~~

409Tidak seperti `deny`, masking mengotorisasi proxy untuk mengirim kredensial asli Anda ke host yang terdaftar, jadi Claude Code menghormatinya hanya dari pengaturan yang Anda atau administrator Anda kontrol: pengaturan pengguna, pengaturan terkelola, dan bendera CLI `--settings`. Claude Code mengabaikan entri `mask` dalam `.claude/settings.json` atau `.claude/settings.local.json` repositori. Dalam file tersebut juga mengabaikan `network.tlsTerminate` dan [`credentials.allowPlaintextInject`](/docs/id/settings-reference#sandbox-credentials-allowplaintextinject), pengaturan yang memungkinkan proxy menyuntik kredensial ke permintaan yang tidak terenkripsi. Jika Anda [mengecualikan pengaturan pengguna](#configure-sandboxing), Claude Code menghapus entri `mask` variabel lingkungan dalam `~/.claude/settings.json` juga.

410 499

411Ketika administrator Anda mengirimkan entri `mask`, `network.tlsTerminate`, atau `credentials.allowPlaintextInject` melalui pengaturan terkelola server, mereka dihitung sebagai [pengaturan yang memerlukan persetujuan](/docs/id/server-managed-settings#security-approval-dialogs).500<span id="ipv6-destinations-in-injecthosts" />Untuk tujuan IPv6, tuliskan alamat secara berbeda di kedua daftar:

412 501

413Ketika variabel yang sama terdaftar dengan `deny` dalam scope apa pun, `deny` mengambil prioritas.502* **`network.allowedDomains`**: bentuk dalam kurung siku, seperti `"[::1]"`

503* **`injectHosts`**: alamat polos dalam bentuk terkompresi kanonisnya, seperti `"::1"`

414 504

415Masking mengganti seluruh nilai variabel secara default, yang cocok untuk token telanjang. Bidang entri opsional, yang memerlukan Claude Code v2.1.224 atau lebih baru, menangani nilai dengan struktur:505Proxy mencocokkan setiap entri `injectHosts` dengan alamat tujuan polos koneksi, dengan mengabaikan port, sehingga penulisan dengan kurung siku, zone-ID, atau kompresi yang berbeda tidak pernah cocok. `claude doctor` menandai entri yang tidak akan pernah cocok dengan peringatan `Sandbox credential injectHosts entries can never match their destination`. Pemeriksaan ini memerlukan Claude Code v2.1.229 atau lebih baru.

~~416~~

417* `extract`: ekspresi reguler yang Claude Code terapkan di seluruh nilai, mengganti hanya teks yang ditangkap oleh grup 1 dari setiap kecocokan, jadi alat yang mengurai nilai, seperti string koneksi `DATABASE_URL`, masih berfungsi di dalam sandbox. Pola harus berisi setidaknya satu grup penangkapan.

418* `onExtractNoMatch` mengontrol apa yang terjadi ketika pola tidak cocok dengan apa pun:

419 * `warn`, default, memperingatkan dan melewatkan variabel tanpa mask

420 * `deny` membatalkan pengaturan variabel di dalam sandbox

421 * `error` menghentikan setup sandbox sampai Anda memperbaiki konfigurasi

422* `decode: "jwt"`: untuk variabel yang menyimpan JSON Web Token (JWT). Claude Code memverifikasi nilai adalah JWT dan menggantinya dengan token palsu yang valid secara struktural, jadi kode di dalam sandbox yang mendekode token terus berfungsi. Tambahkan `maskClaims` untuk mencantumkan klaim payload tingkat atas untuk di-mask secara individual daripada mengganti seluruh token; klaim lainnya tetap dapat dibaca. Ketika nilai tidak memverifikasi sebagai JWT, atau tidak ada klaim yang terdaftar cocok, Claude Code melewatkan variabel tanpa mask dengan peringatan. `decode` tidak dapat digabungkan dengan `extract`.

~~423~~

424Lihat [baris `credentials.envVars[]` dalam referensi pengaturan](/docs/id/settings-reference#sandbox-settings) untuk daftar bidang lengkap.

425 506

426<h4 id="re-sign-aws-requests">507<h4 id="re-sign-aws-requests">

427 Re-sign AWS requests508 Menandatangani ulang permintaan AWS

428</h4>509</h4>

429 510

430Permintaan AWS membawa tanda tangan SigV4 di atas konten permintaan, jadi mask `AWS_ACCESS_KEY_ID` dan `AWS_SECRET_ACCESS_KEY` bersama-sama. Proxy mendeteksi permintaan SigV4 oleh sentinel kunci akses dan menandatangani ulang setelah mengganti nilai asli. Masking rahasia saja meninggalkan permintaan ditandatangani dengan placeholder, yang proxy tidak dapat mendeteksi, jadi mereka gagal di AWS; Claude Code memperingatkan tentang kasus ini saat startup, tetapi tidak ketika hanya ID kunci akses yang di-mask. Permintaan yang terdeteksi proxy tidak dapat menandatangani ulang, seperti yang kehilangan header `x-amz-date` nya, gagal dengan kesalahan proxy daripada mencapai server dengan tanda tangan yang rusak.511Permintaan AWS membawa tanda tangan SigV4 atas isi permintaan, jadi lakukan mask pada `AWS_ACCESS_KEY_ID` dan `AWS_SECRET_ACCESS_KEY` secara bersamaan. Proxy mendeteksi permintaan SigV4 melalui [sentinel](#mask-credentials) access key dan menandatangani ulang permintaan dengan nilai sebenarnya, yang memerlukan Claude Code v2.1.221 atau lebih baru. Jika Anda hanya melakukan mask pada secret, permintaan ditandatangani dengan placeholder yang tidak dapat dideteksi oleh proxy, sehingga permintaan tersebut gagal di AWS.

~~431~~

432Claude Code menghubungkan variabel `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, dan `AWS_SESSION_TOKEN` konvensional ke satu kredensial secara otomatis ketika Anda mask nilai seluruhnya. Jika kredensial AWS Anda berada dalam variabel dengan nama lain, kelompokkan sendiri dengan [`credentials.awsPairs`](/docs/id/settings-reference#sandbox-credentials-awspairs), yang memerlukan Claude Code v2.1.224 atau lebih baru. Contoh ini menambahkan pasangan ke konfigurasi yang sudah mask `MY_KEY_ID`, `MY_SECRET_KEY`, dan `MY_SESSION_TOKEN` seluruh-nilai, seperti dalam [konfigurasi masking di atas](#mask-environment-variables):

~~433~~

434```json theme={null}

435{

436 "sandbox": {

437 "credentials": {

438 "awsPairs": [

439 {

440 "accessKeyIdVar": "MY_KEY_ID",

441 "secretAccessKeyVar": "MY_SECRET_KEY",

442 "sessionTokenVar": "MY_SESSION_TOKEN"

443 }

444 ]

445 }

446 }

447}

448```

~~449~~

450Setiap entri mengikuti aturan ini:

~~451~~

452* `accessKeyIdVar` dan `secretAccessKeyVar` memberi nama entri `envVars` yang di-mask yang menyimpan ID kunci akses dan kunci rahasia. `sessionTokenVar` opsional memberi nama entri yang menyimpan token sesi untuk kredensial sementara; ketika diatur, proxy mengirim token asli sebagai `x-amz-security-token` pada permintaan yang ditandatangani ulang.

453* Setiap variabel yang dinamai harus entri `mask` yang mask seluruh nilainya, tanpa `extract` atau `decode`.

454* Proxy menandatangani ulang permintaan pada host yang terdaftar dalam entri ID kunci akses `injectHosts`.

455* Penamaan variabel konvensional apa pun dalam pasangan mengganti pasangan otomatis.

456 512

457Seperti entri `mask`, `awsPairs` dihormati hanya dari pengaturan pengguna, pengaturan terkelola, dan bendera CLI `--settings`.513Claude Code secara otomatis menautkan variabel konvensional `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, dan `AWS_SESSION_TOKEN` menjadi satu kredensial ketika Anda melakukan mask pada seluruh nilainya. Jika kredensial AWS Anda berada di variabel dengan nama lain, kelompokkan dengan [`credentials.awsPairs`](/docs/id/settings-reference#sandbox-credentials-awspairs), yang memerlukan Claude Code v2.1.224 atau lebih baru.

458 514

459Tiga bentuk permintaan AWS membawa tanda tangan yang proxy tidak dapat menghitung ulang. Ketika permintaan seperti itu ditandatangani dengan placeholder pasangan yang di-mask, proxy gagalkan daripada teruskan tanda tangan yang rusak; permintaan yang ditandatangani dengan kredensial yang tidak di-mask tidak pernah terpengaruh. Pengaturan [`credentials.sigv4`](/docs/id/settings-reference#sandbox-credentials-sigv4), yang memerlukan Claude Code v2.1.224 atau lebih baru, melonggarkan ini per bentuk: mengatur kunci bentuk ke `passthrough` meneruskan permintaan dengan tanda tangan yang diturunkan placeholder-nya, jadi alat yang memanggil menerima penolakan AWS sendiri daripada kesalahan proxy. Seperti `awsPairs`, `sigv4` dihormati hanya dari pengaturan pengguna, pengaturan terkelola, dan bendera CLI `--settings`.515Unggahan streaming, URL presigned, dan permintaan SigV4A membawa tanda tangan yang tidak dapat dihitung ulang oleh proxy. Ketika salah satu permintaan ini ditandatangani dengan placeholder dari pasangan yang di-mask, proxy menggagalkannya alih-alih meneruskan tanda tangan yang rusak. Permintaan yang ditandatangani dengan kredensial yang tidak di-mask tidak terpengaruh. Gunakan [`credentials.sigv4`](/docs/id/settings-reference#sandbox-credentials-sigv4), yang memerlukan Claude Code v2.1.224 atau lebih baru, untuk meneruskan salah satu bentuk permintaan ini sebagai gantinya. AWS tetap menolak permintaan tersebut, sehingga tool pemanggil menerima respons penolakan dari AWS sendiri alih-alih error proxy.

~~460~~

461| Bentuk permintaan | Kunci `sigv4` | Mengapa proxy tidak dapat menandatangani ulang |

462| :- | :- | :- |

463| unggahan streaming aws-chunked | `streaming` | Tanda tangan per-chunk berantai dari tanda tangan seed, jadi menandatangani ulang akan memerlukan menulis ulang badan |

464| URL yang sudah ditandatangani | `presigned` | Tanda tangan berada di URL itu sendiri, tanpa header `Authorization` |

465| Tanda tangan asimetris SigV4A | `sigv4a` | Tidak ada HMAC kunci bersama untuk menghitung ulang |

466 516

467<h4 id="mask-credential-files">517<h4 id="mask-credential-files">

468 Mask credential files518 Melakukan mask file kredensial

469</h4>519</h4>

470 520

471Entri file juga menerima `"mode": "mask"`, yang memerlukan Claude Code v2.1.221 atau lebih baru. Apa yang dilihat perintah sandboxed tergantung pada platform:521Untuk melakukan mask pada file kredensial, atur `"mode": "mask"` pada entri `credentials.files`-nya. Melakukan mask file memerlukan Claude Code v2.1.221 atau lebih baru. Apa yang dilihat perintah sandbox bergantung pada platform:

472 522

473* **Linux dan WSL2**: perintah sandboxed membaca salinan sentinel file, pengganti yang rahasianya diganti dengan nilai placeholder, dan [sandbox proxy](#network-isolation) mengganti nilai asli pada egress.523* **Linux dan WSL2**: perintah sandbox membaca salinan [sentinel](#mask-credentials) dari file, dan proxy mensubstitusi nilai sebenarnya pada permintaan keluar.

474* **macOS**: perintah sandboxed tidak dapat membaca file yang terdaftar sama sekali. Claude Code tidak membangun salinan sentinel dan tidak mengganti apa pun pada egress, jadi alat yang mengotentikasi dengan file tidak berfungsi di dalam sandbox, efek yang sama seperti `deny`. Tidak seperti entri `deny`, blok baca berlaku bahkan ketika Anda [menonaktifkan isolasi filesystem](#disable-filesystem-isolation).524* **macOS**: perintah sandbox sama sekali tidak dapat membaca file tersebut. Claude Code tidak membuat salinan sentinel, sehingga tool yang melakukan autentikasi dengan file tersebut tidak berfungsi di dalam sandbox, efek yang sama dengan `deny`. Blokir baca tetap berlaku bahkan ketika Anda [menonaktifkan isolasi filesystem](#disable-filesystem-isolation).

475 525

476Di setiap platform, Claude Code menerapkan persyaratan [`network.tlsTerminate`](/docs/id/settings-reference#sandbox-network-tlsterminate) dan `injectHosts` dengan cara yang sama seperti untuk [masked environment variables](#mask-environment-variables), dan mengabaikan pengaturan repositori dengan cara yang sama. Jika Anda [mengecualikan pengaturan pengguna](#configure-sandboxing), Claude Code menjaga entri `mask` file dalam `~/.claude/settings.json` sebagai pembatasan, tetapi entri tidak lagi mengotorisasi proxy untuk mengganti nilai asli.526Contoh ini melakukan mask pada token GitHub yang disimpan di `~/.config/gh/hosts.yml`. Pola `extract` menandai bagian mana dari file yang merupakan rahasia, sehingga di Linux dan WSL2 `gh` tetap dapat mem-parse bagian lain dari konfigurasinya:

~~477~~

478Contoh di bawah mask token GitHub yang disimpan dalam `~/.config/gh/hosts.yml`; pola `extract`, dijelaskan di bawah, memberi tahu Claude Code bagian file mana yang rahasianya. Di Linux dan WSL2, perintah sandboxed yang membaca file mendapatkan sentinel sebagai pengganti token, dan proxy mengganti token asli pada permintaan ke `api.github.com`:

479 527

480```json theme={null}528```json theme={null}

481{529{

499}547}

500```548```

501 549

502Untuk mengkonfirmasi mask aktif, minta Claude menjalankan `cat ~/.config/gh/hosts.yml` dalam perintah sandboxed: di Linux dan WSL2 output menunjukkan nilai sentinel sebagai pengganti token, dan di macOS pembacaan gagal sebagai gantinya.550Untuk memastikan mask aktif, minta Claude menjalankan `cat ~/.config/gh/hosts.yml` dalam perintah sandbox. Di Linux dan WSL2 output menampilkan sentinel sebagai pengganti token, dan di macOS pembacaan gagal.

~~503~~

504Di Linux dan WSL2, pola `extract` adalah apa yang menjaga sisa `hosts.yml` dapat dibaca. Claude Code menerapkan ekspresi reguler di seluruh file dan mengganti hanya teks yang ditangkap oleh grup 1 dari setiap kecocokan, jadi `gh` masih mengurai konfignya dan hanya token yang placeholder. Gunakan `extract` untuk file terstruktur apa pun yang alat urai, seperti `.netrc`, JSON, atau YAML; pola harus berisi setidaknya satu grup penangkapan. Tanpa `extract`, Claude Code mengganti seluruh konten file dengan satu nilai sentinel, yang cocok untuk file yang menyimpan satu rahasia telanjang dan tidak ada yang lain.

~~505~~

506Untuk file yang menyimpan JSON Web Token (JWT), atur `decode: "jwt"` daripada, atau bersama dengan, `extract`. `decode` memerlukan Claude Code v2.1.224 atau lebih baru. Claude Code menemukan kandidat JWT dengan pola bawaan, atau dengan pola `extract` Anda ketika diatur, memverifikasi setiap kandidat adalah JWT, dan menggantinya dengan token palsu yang valid secara struktural, jadi kode yang mendekode token di dalam sandbox terus berfungsi. Tambahkan `maskClaims` untuk mask hanya klaim payload tingkat atas yang dinamai di dalam setiap token yang diverifikasi dan biarkan klaim lainnya dapat dibaca. Ketika tidak ada kandidat yang memverifikasi, atau tidak ada klaim yang dinamai cocok, bidang `onExtractNoMatch` di bawah mengatur hasil, seperti yang dilakukan untuk pola yang tidak cocok dengan apa pun.

~~507~~

508Dua bidang opsional menyempurnakan bagaimana perilaku pencocokan. Keduanya berlaku hanya ketika `mode` adalah `mask` dan `extract` atau `decode` diatur. Di macOS, Claude Code menerapkan entri `mask` sebagai `deny` sebelum pola berjalan kapan pun isolasi filesystem aktif, jadi bidang ini, dan hasil no-match di bawah, berlaku di sana hanya ketika [isolasi filesystem mati](#disable-filesystem-isolation):

509 551

510* `onExtractNoMatch` mengontrol apa yang terjadi ketika pencocokan menemukan tidak ada yang di-mask dalam file:552Tanpa `extract` atau `decode`, Claude Code mengganti seluruh file dengan satu sentinel, yang cocok untuk file yang berisi satu rahasia polos. Gunakan [field `extract`, `decode`, `maskClaims`, `onExtractNoMatch`, dan `maskDuplicates`](/docs/id/settings-reference#sandbox-credentials-files) untuk mengontrol masking parsial dan apa yang terjadi ketika pola tidak cocok dengan apa pun.

511 553

512 * `warn`, default, memperingatkan dan melewati entri, jadi perintah sandboxed dapat membaca file asli tanpa mask. Default cocok untuk kredensial yang mungkin secara sah tidak ada; jika rahasia mungkin ada tetapi pola mungkin melewatkannya, gunakan `deny`554<Warning>

513 * `deny` membuat file tidak dapat dibaca sebagai gantinya555 Ketika pencocokan tidak menemukan apa pun untuk di-mask, nilai default `onExtractNoMatch`, yaitu `warn`, melewati entri tersebut, sehingga perintah sandbox dapat membaca file sebenarnya tanpa di-mask. Di macOS, Claude Code menerapkan entri `mask` sebagai `deny` sebelum pola dijalankan setiap kali isolasi filesystem aktif, sehingga hasil tanpa kecocokan hanya berlaku di sana ketika [isolasi filesystem dimatikan](#disable-filesystem-isolation). Default ini cocok untuk kredensial yang mungkin memang tidak ada. Jika rahasia mungkin ada tetapi pola mungkin melewatkannya, gunakan [`deny`](/docs/id/settings-reference#mask-fields-for-files).

514 * `error` menghentikan setup sandbox sampai Anda memperbaiki konfigurasi556</Warning>

~~515~~

516 Claude Code memperlakukan `deny` sebagai `error` kapan pun blok baca tidak akan diberlakukan: ketika Anda [menonaktifkan isolasi filesystem](#disable-filesystem-isolation), dan ketika entri `filesystem.allowRead` dari sumber pengaturan apa pun membuka kembali jalur file.

517* `maskDuplicates` juga mengganti salinan verbatim dari setiap nilai kredensial yang di-mask, tangkapan `extract` atau token yang diverifikasi `decode`, ditemukan di luar rentang yang cocok, untuk rahasia yang diulang di mana pencocokan tidak menjangkau. Ini mencocokkan substring mentah, jadi nilai pendek atau umum akan diganti di mana pun muncul; cadangkan untuk rahasia panjang, high-entropy. Default: false.

518 557

519`mask` berlaku untuk satu file, jadi daftarkan setiap file kredensial secara individual. Claude Code jatuh kembali ke `deny` untuk entri `mask` yang tidak dapat di-mask dengan aman: jalur direktori, pola glob, file lebih besar dari 8 MiB, atau file yang bukan teks UTF-8. Tulis direktori sebagai entri `deny` eksplisit sebagai gantinya; tabel di bawah [Which settings can disable it](#which-settings-can-disable-it) mencakup apakah setiap bentuk menyematkan `filesystem.disabled` dan bagaimana perilakunya dengan isolasi filesystem mati.558`mask` berlaku untuk satu file, jadi cantumkan setiap file kredensial secara individual. Claude Code melakukan fallback ke `deny` untuk entri `mask` yang tidak dapat di-mask dengan aman: path direktori, pola glob, file yang lebih besar dari 8 MiB, atau file yang bukan teks UTF-8.

520 559

521<h2 id="how-sandboxing-works">560<h2 id="how-sandboxing-works">

522 Cara sandboxing bekerja561 Cara kerja sandboxing

523</h2>562</h2>

524 563

525<h3 id="filesystem-isolation">564<h3 id="filesystem-isolation">

526 Isolasi filesystem565 Isolasi sistem file

527</h3>566</h3>

528 567

529Alat Bash sandboxed membatasi akses sistem file ke direktori tertentu:568Tool Bash yang di-sandbox membatasi akses sistem file ke direktori tertentu:

530 569

531* **Perilaku penulisan default**: akses baca dan tulis ke direktori kerja saat ini dan subdirektorinya, direktori apa pun yang telah Anda tambahkan dengan `--add-dir`, `/add-dir`, atau [`permissions.additionalDirectories`](/docs/id/settings-reference#permissions-additionaldirectories), ditambah direktori temp per-pengguna yang ditunjuk oleh `$TMPDIR`570* **Perilaku tulis default**: akses baca dan tulis ke direktori kerja saat ini dan subdirektorinya, direktori apa pun yang telah Anda tambahkan dengan `--add-dir`, `/add-dir`, atau [`permissions.additionalDirectories`](/docs/id/settings-reference#permissions-additionaldirectories), ditambah direktori temp per pengguna yang ditunjuk oleh `$TMPDIR`

532* **Perilaku pembacaan default**: akses baca ke seluruh komputer, kecuali direktori tertentu yang ditolak. Perhatikan bahwa default ini masih memungkinkan pembacaan file kredensial seperti `~/.aws/credentials` dan `~/.ssh/`. Gunakan [`sandbox.credentials`](#protect-credentials) untuk memblokir pembacaan file-file ini dan membatalkan penetapan variabel lingkungan rahasia, atau tambahkan jalur ke `denyRead`.571* **Perilaku baca default**: akses baca ke seluruh komputer, kecuali direktori tertentu yang ditolak. Default ini tetap mengizinkan pembacaan file kredensial, jadi [lindungi kredensial](#protect-credentials) yang tidak ingin Anda biarkan dibaca oleh perintah.

533* **Blok baca**: dengan [`permissions.blockReadsOutsideWorkingDirectories`](/docs/id/settings-reference#permissions-blockreadsoutsideworkingdirectories) aktif, perintah sandboxed juga kehilangan akses baca ke direktori home Anda dan direktori lain yang menyimpan file pengguna, terlepas dari jalur yang [Perintah sandboxed di bawah blok](/docs/id/settings-reference#sandboxed-commands-under-the-block) daftarkan. Bagian itu juga mengatakan kapan bagian blok ini tidak berlaku.572* **Pemblokiran baca**: dengan [`permissions.blockReadsOutsideWorkingDirectories`](/docs/id/settings-reference#permissions-blockreadsoutsideworkingdirectories) diaktifkan, perintah yang di-sandbox juga kehilangan akses baca ke direktori home Anda dan direktori lain yang menyimpan file pengguna, kecuali jalur yang dicantumkan dalam [Perintah yang di-sandbox di bawah pemblokiran](/docs/id/settings-reference#sandboxed-commands-under-the-block). Bagian tersebut juga menjelaskan kapan bagian pemblokiran ini tidak berlaku.

534* **Akses terblokir**: tidak dapat memodifikasi file di luar direktori kerja, direktori yang ditambahkan, dan direktori temp per-pengguna tanpa izin eksplisit, termasuk file konfigurasi shell seperti `~/.bashrc` dan binari sistem di `/bin/`573* **Git worktree**: ketika direktori kerja adalah [git worktree yang ditautkan](/docs/id/worktrees), sandbox juga mengizinkan penulisan ke direktori `.git` bersama milik repositori utama sehingga perintah seperti `git commit` dapat memperbarui ref dan index. Penulisan ke `hooks/` dan `config` di dalam direktori tersebut tetap ditolak.

535* **Git worktrees**: ketika direktori kerja adalah [linked git worktree](/docs/id/worktrees), sandbox juga memungkinkan penulisan ke direktori `.git` bersama dari repositori utama sehingga perintah seperti `git commit` dapat memperbarui refs dan indeks. Penulisan ke `hooks/` dan `config` di dalam direktori tersebut tetap ditolak.

536* **Dapat dikonfigurasi**: tentukan jalur yang diizinkan dan ditolak khusus melalui pengaturan

537 574

538Untuk melewati isolasi filesystem sepenuhnya sambil mempertahankan isolasi jaringan, atur [`sandbox.filesystem.disabled`](#disable-filesystem-isolation).575Untuk melewati isolasi sistem file sepenuhnya sambil tetap mempertahankan isolasi jaringan, atur [`sandbox.filesystem.disabled`](#disable-filesystem-isolation).

539 576

540<h3 id="protected-paths">577<h3 id="protected-paths">

541 Jalur yang dilindungi578 Jalur yang dilindungi

542</h3>579</h3>

543 580

544Di dalam direktori yang dapat ditulis oleh perintah sandboxed, sandbox masih menolak penulisan ke file yang dimuat konfigurasi dan kode Claude Code. Perintah yang dapat mengedit file-file tersebut dapat memberikan izin kepada dirinya sendiri, atau menambahkan hook atau server MCP yang dijalankan Claude Code di luar sandbox. Sistem izin memiliki [jalur yang dilindungi](/docs/id/permission-modes#protected-paths) sendiri, yang mengontrol apa yang disetujui Claude Code sebelum alat berjalan; daftar sandbox berlaku untuk perintah yang sudah berjalan. Ini mencakup empat kelompok jalur:581Di dalam direktori yang dapat ditulisi oleh perintah yang di-sandbox, sandbox tetap menolak penulisan ke file tempat Claude Code memuat konfigurasi dan kode. Perintah yang dapat mengedit file tersebut dapat memberikan izin kepada dirinya sendiri, atau menambahkan hook atau server MCP yang dijalankan Claude Code di luar sandbox. Sistem izin memiliki [jalur yang dilindungi](/docs/id/permission-modes#protected-paths) tersendiri, yang mengontrol apa yang disetujui Claude Code sebelum sebuah tool berjalan; daftar milik sandbox berlaku untuk perintah yang sudah berjalan. Daftar ini mencakup empat kelompok jalur:

545 582

546* **Di direktori kerja Anda dan direktori di atasnya**: file pengaturan `.claude`, direktori `.claude/skills`, `.claude/agents`, `.claude/commands`, dan `.claude/hooks`, `.mcp.json`, dan file yang dijalankan Claude Code sendiri, seperti `.claude/workflows` dan `.claude/scheduled_tasks.json`583* **Di direktori kerja Anda dan direktori di atasnya**: file pengaturan `.claude`, direktori `.claude/skills`, `.claude/agents`, `.claude/commands`, dan `.claude/hooks`, `.mcp.json`, serta file yang dijalankan Claude Code dengan sendirinya, seperti `.claude/workflows` dan `.claude/scheduled_tasks.json`

547* **Di direktori kerja Anda saja**: file startup shell seperti `.bashrc` dan `.zshrc`, `.gitconfig`, direktori `.vscode` dan `.idea`, dan `hooks` dan `config` di dalam `.git`584* **Hanya di direktori kerja Anda**: file startup shell seperti `.bashrc` dan `.zshrc`, `.gitconfig`, direktori `.vscode` dan `.idea`, serta `hooks` dan `config` di dalam `.git`

548* **File yang akan mengubah direktori kerja Anda menjadi repositori git bare**: `HEAD`, `objects`, dan `refs` di tingkat atas, ditambah `config` dan `hooks` di sana ketika `HEAD` berada di sebelahnya. File bernama `config` ditolak bahkan tanpa `HEAD`. Di Linux dan WSL2, sandbox menghapus file `HEAD` tingkat atas atau direktori `objects` atau `refs` yang muncul saat perintah sandboxed berjalan585* **File yang akan mengubah direktori kerja Anda menjadi repositori git bare**: `HEAD`, `objects`, dan `refs` di tingkat teratas, ditambah entri `config` dan `hooks` yang sudah ada di sana ketika terdapat `HEAD` di sampingnya. File bernama `config` ditolak bahkan tanpa `HEAD`. Di Linux dan WSL2, sandbox menghapus file `HEAD` atau direktori `objects` atau `refs` di tingkat teratas yang muncul saat perintah yang di-sandbox sedang berjalan

549* **Di `~/.claude`, atau direktori yang ditunjuk `CLAUDE_CONFIG_DIR`**: sebagian besar isinya, ditambah `~/.claude.json` dan penyimpanan kredensial `.credentials.json`586* **Di `~/.claude`, atau direktori yang ditunjuk oleh `CLAUDE_CONFIG_DIR`**: sebagian besar isinya, ditambah `~/.claude.json` dan penyimpanan kredensial `.credentials.json`

550 587

551Jika symlink muncul di jalur file pengaturan yang dilindungi selama sesi, sandbox juga menolak penulisan ke file yang ditunjuknya, mulai dari perintah berikutnya.588Jika sebuah symlink muncul di jalur file pengaturan yang dilindungi selama sesi, sandbox juga menolak penulisan ke file yang ditunjuknya, dimulai dari perintah berikutnya.

552 589

553Tidak ada cara untuk mengecualikan salah satu jalur ini: entri `allowWrite` atau aturan izin `Edit` yang mencakup jalur tidak menghilangkan perlindungan. Satu-satunya cara untuk mematikan perlindungan adalah [`filesystem.disabled`](#disable-filesystem-isolation), yang mematikan isolasi filesystem untuk setiap jalur. Untuk melihat sebagian besar jalur ini diselesaikan untuk mesin Anda, jalankan `/sandbox` dan buka tab **Config**, yang mencantumnya di bawah **Denied within allowed**, dicampur dengan entri `denyWrite` Anda sendiri.590Tidak ada cara untuk mengecualikan salah satu jalur ini: entri `allowWrite` atau aturan izin `Edit` yang mencakup jalur tersebut tidak mencabut perlindungannya. Satu-satunya cara untuk mematikan perlindungan adalah [`filesystem.disabled`](#disable-filesystem-isolation), yang mematikan isolasi sistem file untuk setiap jalur. Untuk melihat sebagian besar jalur ini sebagaimana diterapkan di mesin Anda, jalankan `/sandbox` dan buka tab **Config**, yang mencantumkannya di bawah **Denied within allowed**, bercampur dengan entri `denyWrite` Anda sendiri.

554 591

555Jika `git merge` atau `git checkout` gagal dengan `unable to unlink old` pada salah satu jalur ini, lihat [Troubleshooting](#troubleshooting).592Jika `git merge` atau `git checkout` gagal dengan `unable to unlink old` pada salah satu jalur ini, lihat [Perintah git gagal dengan `unable to unlink old`](#a-git-command-fails-with-unable-to-unlink-old).

556 593

557<h3 id="network-isolation">594<h3 id="network-isolation">

558 Isolasi jaringan595 Isolasi jaringan

559</h3>596</h3>

560 597

561Akses jaringan dikendalikan melalui server proxy yang berjalan di luar sandbox:598Perintah yang di-sandbox tidak memiliki rute langsung ke jaringan:

562 599

563* **Pembatasan domain**: Claude Code tidak memungkinkan domain apa pun secara default. Pertama kali perintah memerlukan domain baru, Claude Code meminta persetujuan; dalam [mode otomatis](/docs/id/permission-modes#eliminate-prompts-with-auto-mode), Claude malah menamai host yang dibutuhkan perintah pada perintah itu sendiri, per [Domain yang diizinkan per perintah](#per-command-allowed-domains-in-auto-mode).600* **Linux dan WSL2**: perintah berjalan di network namespace terpisah yang tidak memiliki koneksi ke jaringan Anda

564* **Pilihan persetujuan**: jika Anda memilih Ya saat diminta, Claude Code memungkinkan host untuk sisa sesi saat ini dan tidak meminta lagi untuk koneksi nanti ke host yang sama. Jika Anda memilih "Ya, dan jangan tanya lagi", Claude Code menyimpan aturan izin `WebFetch(domain:...)` ke [pengaturan lokal](/docs/id/permissions#permission-system) Anda, sehingga host tetap diizinkan di sesi mendatang.601* **macOS**: framework sandbox Seatbelt secara default memblokir koneksi selain koneksi ke proxy sandbox

565* **Domain yang diizinkan sebelumnya**: izinkan domain sebelumnya dengan [`allowedDomains`](/docs/id/settings-reference#sandbox-network-alloweddomains) untuk menghindari prompt sepenuhnya. Claude Code juga memungkinkan domain sebelumnya dari aturan izin `WebFetch(domain:...)`, seperti dijelaskan dalam [Aturan izin](#permission-rules).

566* **Allowlist ketat**: jika Anda mengatur [`strictAllowlist`](/docs/id/settings-reference#sandbox-network-strictallowlist) ke `true` dalam pengaturan pengguna, terkelola, atau CLI `--settings`, Claude Code menolak akses perintah sandboxed ke host apa pun di luar allowlist alih-alih meminta. Allowlist adalah yang sama dengan yang diminta sandbox sebaliknya: `allowedDomains` ditambah domain dari aturan izin `WebFetch(domain:...)`, atau hanya entri pengaturan terkelola ketika `allowManagedDomainsOnly` diatur. Claude Code memberlakukan ini hanya untuk perintah sandboxed; alat dalam proses seperti `WebFetch` masih mengikuti [aturan izin](#permission-rules) mereka. Mengaturnya di `.claude/settings.json` atau `.claude/settings.local.json` repositori tidak berpengaruh. Memerlukan Claude Code v2.1.219 atau lebih baru.

567* **Lockdown terkelola**: jika [`allowManagedDomainsOnly`](/docs/id/settings-reference#sandbox-network-allowmanageddomainsonly) diatur dalam pengaturan terkelola, domain yang tidak diizinkan diblokir secara otomatis alih-alih meminta, dan hanya `allowedDomains` dan aturan izin `WebFetch(domain:...)` dari pengaturan terkelola yang dihormati.

568* **Proxy korporat**: ketika jaringan Anda memerlukan lalu lintas keluar untuk melewati proxy korporat, atur `HTTPS_PROXY`, `HTTP_PROXY`, dan `NO_PROXY` seperti yang dijelaskan [konfigurasi proxy](/docs/id/network-config#proxy-configuration), dalam blok `env` pengaturan Anda sehingga [agen latar belakang](/docs/id/network-config#set-network-variables-in-settings-not-the-shell) mendapatkannya juga, atau di lingkungan tempat Anda meluncurkan Claude Code. Claude Code memberlakukan allowlist domain dan kemudian menerowongi koneksi yang diizinkan melalui proxy hulu tersebut.

569* **Dukungan proxy khusus**: pengguna tingkat lanjut dapat menerapkan aturan khusus pada lalu lintas keluar

570* **Cakupan komprehensif**: pembatasan berlaku untuk semua skrip, program, dan subprocess yang dihasilkan oleh perintah

571 602

572Dalam aturan `WebFetch(domain:...)`, sandbox menghormati dua bentuk wildcard: `*.` terdepan, seperti `*.example.com`, dan `*` bare. Bentuk `*` bare memerlukan Claude Code v2.1.186 atau lebih baru. Wildcard di posisi lain, seperti `WebFetch(domain:example.*)`, masih cocok dengan fetch tetapi tidak berpengaruh pada perintah sandboxed.603Claude Code menjalankan proxy sandbox di mesin Anda, di luar sandbox, dan mengarahkan perintah ke proxy tersebut dengan `HTTP_PROXY`, `HTTPS_PROXY`, `ALL_PROXY`, dan environment variable terkait. Proxy memeriksa hostname setiap koneksi terhadap domain yang diizinkan dan ditolak milik Anda.

604

605Apa yang dapat dijangkau oleh sebuah tool bergantung pada apakah tool tersebut menggunakan proxy:

606

607* **Tool yang membaca variabel proxy**: `curl`, `npm`, `git` melalui HTTPS, dan tool serupa dapat terhubung setelah host-nya diizinkan. Entri `allowedDomains` tanpa port mengizinkan setiap port pada host tersebut

608* **Tool yang mengabaikan variabel proxy**: `ssh` biasa, sebagian besar driver database, dan tool serupa tidak dapat terhubung, bahkan ke host yang diizinkan. Lihat [Klien database atau tool non-HTTP lainnya gagal menjangkau host yang diizinkan](#a-database-client-or-other-non-http-tool-fails-to-reach-an-allowed-host)

609* **Apa pun yang bukan TCP**: UDP, HTTP/3 melalui QUIC, dan tool ICMP seperti `ping` tidak dapat keluar dari sandbox

610

611Pengaturan dan perilaku berikut mengontrol host mana yang diizinkan oleh proxy:

612

613* **Pembatasan domain**: domain yang diizinkan milik Anda awalnya kosong. [Host di luar domain yang diizinkan](#hosts-outside-your-allowed-domains) menjelaskan apa yang terjadi saat pertama kali sebuah perintah memerlukan domain baru.

614* **Pilihan persetujuan**: jika Anda memilih Yes saat diminta, Claude Code mengizinkan host tersebut selama sisa sesi saat ini. Jika Anda memilih "Yes, and don't ask again", Claude Code menyimpan aturan izin `WebFetch(domain:...)` ke [pengaturan lokal](/docs/id/permissions#permission-system) Anda, sehingga host tetap diizinkan di sesi mendatang. Selama sandbox bersifat [wajib oleh admin](#repository-settings-under-an-admin-required-sandbox), Claude Code menyimpan aturan tersebut ke pengaturan pengguna Anda, yang berlaku di setiap proyek.

615* **Domain yang diizinkan sebelumnya**: izinkan domain terlebih dahulu dengan [`allowedDomains`](/docs/id/settings-reference#sandbox-network-alloweddomains) untuk menghindari permintaan persetujuan sepenuhnya. Claude Code juga mengizinkan terlebih dahulu domain dari aturan izin `WebFetch(domain:...)`, seperti yang dijelaskan dalam [Aturan izin](#permission-rules).

616* **Allowlist ketat**: jika Anda mengatur [`strictAllowlist`](/docs/id/settings-reference#sandbox-network-strictallowlist) ke `true` di pengaturan pengguna, pengaturan terkelola, atau pengaturan CLI `--settings`, Claude Code menolak akses perintah yang di-sandbox ke host apa pun di luar allowlist alih-alih meminta persetujuan. Allowlist terdiri dari `allowedDomains` ditambah domain dari aturan izin `WebFetch(domain:...)`, atau hanya entri pengaturan terkelola ketika `allowManagedDomainsOnly` diatur. [Penguncian yang berlaku tanpa sandbox wajib oleh admin](#locks-that-apply-without-an-admin-required-sandbox) menjelaskan entri milik repositori. Claude Code hanya menerapkan ini untuk perintah yang di-sandbox; tool dalam proses seperti `WebFetch` tetap mengikuti [aturan izin](#permission-rules) masing-masing. Mengaturnya di `.claude/settings.json` atau `.claude/settings.local.json` milik repositori tidak berpengaruh. Memerlukan Claude Code v2.1.219 atau yang lebih baru.

617* **Penguncian terkelola**: jika [`allowManagedDomainsOnly`](/docs/id/settings-reference#sandbox-network-allowmanageddomainsonly) diatur di pengaturan terkelola, domain yang tidak diizinkan diblokir secara otomatis alih-alih meminta persetujuan, dan hanya aturan izin `allowedDomains` dan `WebFetch(domain:...)` dari pengaturan terkelola yang dipatuhi.

618* **Proxy perusahaan**: ketika jaringan Anda mengharuskan lalu lintas keluar melewati proxy perusahaan, atur `HTTPS_PROXY`, `HTTP_PROXY`, dan `NO_PROXY` seperti yang dijelaskan dalam [konfigurasi proxy](/docs/id/network-config#proxy-configuration), di blok `env` pengaturan Anda agar [agent latar belakang](/docs/id/network-config#set-network-variables-in-settings-not-the-shell) juga mendapatkannya, atau di environment tempat Anda meluncurkan Claude Code. Claude Code menerapkan allowlist domain lalu meneruskan koneksi yang diizinkan melalui proxy upstream tersebut. URL proxy `http://` dan `https://` dapat digunakan, dengan autentikasi basic di URL jika Anda memerlukannya.

619

620Dalam aturan `WebFetch(domain:...)`, sandbox mematuhi dua bentuk wildcard: `*.` di awal, seperti `*.example.com`, dan `*` tunggal. Bentuk `*` tunggal memerlukan Claude Code v2.1.186 atau yang lebih baru. Wildcard di posisi lain, seperti `WebFetch(domain:example.*)`, tetap cocok dengan pengambilan tetapi tidak berpengaruh pada perintah yang di-sandbox.

573 621

574<Note>622<Note>

575 Proxy bawaan memberlakukan allowlist berdasarkan hostname yang diminta dan, secara default, tidak menghentikan atau memeriksa lalu lintas TLS. Pengaturan eksperimental [`network.tlsTerminate`](/docs/id/settings-reference#sandbox-network-tlsterminate), tersedia di Claude Code v2.1.199 dan lebih baru, membuat proxy bawaan menghentikan TLS itu sendiri, yang [entri kredensial `mask`](#mask-credentials) memerlukan. Lihat [Batasan keamanan](#security-limitations) untuk implikasi default, dan [Konfigurasi proxy khusus](#custom-proxy-configuration) jika model ancaman Anda memerlukan inspeksi TLS.623 Proxy bawaan menerapkan allowlist berdasarkan hostname yang diminta dan, secara default, tidak mengakhiri atau memeriksa lalu lintas TLS. Pengaturan eksperimental [`network.tlsTerminate`](/docs/id/settings-reference#sandbox-network-tlsterminate), yang tersedia di Claude Code v2.1.199 dan yang lebih baru, membuat proxy bawaan mengakhiri TLS sendiri, yang diperlukan oleh [entri kredensial `mask`](#mask-credentials). Lihat [Keterbatasan keamanan](#security-limitations) untuk implikasi dari perilaku default, dan [Konfigurasi proxy kustom](#custom-proxy-configuration) jika model ancaman Anda memerlukan inspeksi TLS.

576</Note>624</Note>

577 625

626<h4 id="hosts-outside-your-allowed-domains">

627 Host di luar domain yang diizinkan

628</h4>

629

630Ketika perintah yang di-sandbox terhubung ke host yang tidak ada dalam domain yang diizinkan milik Anda, perintah tetap berada di sandbox dan menunggu keputusan. Dalam sesi terminal interaktif, keputusan bergantung pada mode izin Anda:

631

632| Mode izin | Apa yang terjadi pada koneksi |

633| :- | :- |

634| Mode `bypassPermissions`, dan plan mode dengan [bypass permissions tersedia](/docs/id/permission-modes#skip-all-checks-with-bypasspermissions-mode) | Diizinkan tanpa permintaan persetujuan |

635| Mode manual, mode `acceptEdits`, dan plan mode dalam kondisi lainnya | Anda mendapatkan permintaan persetujuan |

636| Auto mode | Ditolak kecuali perintah tersebut [mencantumkan host](#per-command-allowed-domains-in-auto-mode) dan pengklasifikasi menyetujui daftarnya |

637| Mode `dontAsk` | Ditolak |

638

639Dengan [`strictAllowlist`](/docs/id/settings-reference#sandbox-network-strictallowlist) atau [`allowManagedDomainsOnly`](/docs/id/settings-reference#sandbox-network-allowmanageddomainsonly) diaktifkan, proxy sandbox bawaan menolak koneksi di setiap mode izin. Dalam mode `bypassPermissions`, host di luar domain yang diizinkan milik Anda diizinkan kecuali salah satu pengaturan tersebut diaktifkan. [Jalan keluar retry tanpa sandbox](#the-unsandboxed-retry-escape-hatch) menjelaskan kapan sebuah perintah dapat keluar dari sandbox dalam mode tersebut. Koneksi ke host di [`deniedDomains`](/docs/id/settings-reference#sandbox-network-denieddomains) juga ditolak di setiap mode izin.

640

641<h4 id="hostnames-that-resolve-to-local-addresses">

642 Hostname yang di-resolve ke alamat lokal

643</h4>

644

645Setelah sebuah hostname lolos allowlist, proxy sandbox me-resolve-nya dan menolak koneksi ketika nama tersebut hanya di-resolve ke alamat lokal. Alamat lokal mencakup alamat loopback seperti `127.0.0.1`, alamat link-local seperti endpoint metadata cloud `169.254.169.254`, dan alamat yang ditetapkan ke mesin Anda sendiri. Nama `localhost` dan `*.localhost` diizinkan untuk di-resolve ke loopback.

646

647Hostname intranet yang diizinkan yang di-resolve ke rentang privat seperti `10.0.0.0/8` dapat terhubung. Untuk membiarkan sebuah nama di-resolve ke alamat yang ditolak, tambahkan alamat IP tersebut ke `allowedDomains`, seperti `"127.0.0.1:8080"`.

648

649Pemeriksaan ini berlaku untuk hostname. Domain yang diizinkan dan mode izin Anda menentukan koneksi ke alamat IP. Proxy juga melewati pemeriksaan untuk koneksi yang dikirimkannya melalui proxy perusahaan upstream, karena proxy tersebut yang me-resolve nama.

650

578<h4 id="per-command-allowed-domains-in-auto-mode">651<h4 id="per-command-allowed-domains-in-auto-mode">

579 Domain yang diizinkan per perintah dalam mode otomatis652 Domain yang diizinkan per perintah dalam auto mode

580</h4>653</h4>

581 654

582Dalam [mode otomatis](/docs/id/permission-modes#eliminate-prompts-with-auto-mode) dengan sandboxing aktif, Claude menamai host yang dibutuhkan perintah pada perintah itu sendiri alih-alih memicu persetujuan jaringan untuk setiap koneksi. Setiap perintah Bash, PowerShell, atau [Monitor](/docs/id/tools-reference#monitor-tool) yang berjalan dalam sandbox dapat membawa daftar host di luar allowlist sandbox: domain seperti `registry.npmjs.org`, wildcard seperti `*.pythonhosted.org`, atau alamat IP, masing-masing dengan `:port` opsional. Pengklasifikasi meninjau host bersama dengan perintah. Memerlukan Claude Code v2.1.271 atau lebih baru.655Dalam [auto mode](/docs/id/permission-modes#eliminate-prompts-with-auto-mode) dengan sandboxing aktif, Claude menyebutkan host yang diperlukan sebuah perintah pada perintah itu sendiri alih-alih memicu persetujuan jaringan untuk setiap koneksi. Setiap perintah Bash, PowerShell, atau [Monitor](/docs/id/tools-reference#monitor-tool) yang berjalan di sandbox dapat membawa daftar host di luar allowlist sandbox: domain seperti `registry.npmjs.org`, wildcard seperti `*.pythonhosted.org`, atau alamat IP, masing-masing dengan `:port` opsional. Pengklasifikasi meninjau host tersebut bersama dengan perintahnya. Memerlukan Claude Code v2.1.271 atau yang lebih baru.

583 656

584Daftar yang disetujui membuka host tersebut hanya untuk perintah itu saja, selama berjalan. Tidak ada yang ditambahkan ke host yang diizinkan sesi Anda atau pengaturan Anda; perintah berikutnya menamai host-nya sendiri.657Daftar yang disetujui membuka host tersebut hanya untuk satu perintah itu, selama perintah tersebut berjalan. Tidak ada yang ditambahkan ke host yang diizinkan dalam sesi Anda atau ke pengaturan Anda; perintah berikutnya menyebutkan host-nya sendiri.

585 658

586Perintah yang membawa host pergi ke pengklasifikasi alih-alih disetujui oleh aturan izin atau [mode auto-allow](#sandbox-modes) sandbox. Jika [aturan ask](/docs/id/permissions#manage-permissions) memaksa prompt untuk perintah, dialog izin di terminal Anda mencantumkan host di sebelahnya, dan menyetujui di sana mencakup keduanya.659Perintah yang membawa host dikirim ke pengklasifikasi alih-alih disetujui oleh aturan izin atau [mode auto-allow](#sandbox-modes) milik sandbox. Jika sebuah [aturan ask](/docs/id/permissions#manage-permissions) memaksa permintaan persetujuan untuk perintah tersebut, dialog izin di terminal Anda mencantumkan host di sampingnya, dan menyetujui di sana mencakup keduanya.

587 660

588Daftar per perintah memperluas hanya apa yang ditolak sandbox secara default. Entri [`deniedDomains`](/docs/id/settings-reference#sandbox-network-denieddomains) masih memblokir. Ketika [`strictAllowlist`](/docs/id/settings-reference#sandbox-network-strictallowlist) atau [`allowManagedDomainsOnly`](/docs/id/settings-reference#sandbox-network-allowmanageddomainsonly) mengunci allowlist, Claude Code menolak daftar per perintah.661Daftar per perintah hanya memperluas apa yang ditolak sandbox secara default. Entri [`deniedDomains`](/docs/id/settings-reference#sandbox-network-denieddomains) tetap memblokir. Ketika [`strictAllowlist`](/docs/id/settings-reference#sandbox-network-strictallowlist) atau [`allowManagedDomainsOnly`](/docs/id/settings-reference#sandbox-network-allowmanageddomainsonly) mengunci allowlist, Claude Code menolak daftar per perintah.

589 662

590Sementara daftar per perintah berlaku, Claude Code menolak koneksi ke host yang tidak ada perintah yang disetujui daftarkan, tanpa prompt atau pemeriksaan pengklasifikasi. Penolakan menamai host dalam hasil perintah, dan Claude menjalankan kembali perintah dengan host ditambahkan.663Selama daftar per perintah berlaku, Claude Code menolak koneksi ke host yang tidak dicantumkan oleh perintah mana pun yang disetujui, tanpa permintaan persetujuan atau pemeriksaan pengklasifikasi. Penolakan tersebut menyebutkan host dalam hasil perintah, dan Claude menjalankan ulang perintah dengan host tersebut ditambahkan.

591 664

592<h4 id="ipv6-addresses-in-domain-lists">665<h4 id="ipv6-addresses-in-domain-lists">

593 Alamat IPv6 dalam daftar domain666 Alamat IPv6 dalam daftar domain

594</h4>667</h4>

595 668

596Daftar domain sandbox adalah `allowedDomains`, `deniedDomains`, dan aturan `WebFetch(domain:...)` yang memberinya makan. Untuk mencocokkan alamat IPv6 di salah satunya, tulis literal dalam tanda kurung: `"[::1]"` cocok dengan alamat itu di setiap port, dan `"[::1]:443"` cocok dengannya hanya di port 443. Tulis port sebagai angka dari 1 hingga 65535 tanpa nol terdepan. Bentuk dalam tanda kurung memerlukan Claude Code v2.1.229 atau lebih baru. Sebelum v2.1.229, ketika teks setelah titik dua terakhir entri adalah nomor port, Claude Code membacanya sebagai satu, jadi `::1:443` menamai alamat `::1` di port 443.669Untuk mencocokkan alamat IPv6 di `allowedDomains`, `deniedDomains`, atau aturan `WebFetch(domain:...)`, tulis alamat tersebut dalam kurung siku: `"[::1]"` cocok dengan alamat tersebut di setiap port, dan `"[::1]:443"` hanya cocok dengannya di port 443. Bentuk berkurung siku memerlukan Claude Code v2.1.229 atau yang lebih baru.

~~597~~

598Ketika Anda memilih "Ya, dan jangan tanya lagi" di prompt persetujuan jaringan untuk alamat IPv6, Claude Code menyimpan aturan `WebFetch(domain:...)` dengan alamat dalam tanda kurung, sehingga aturan terus mencocokkan alamat di sesi mendatang.

599 670

600Entri tanpa tanda kurung dengan dua atau lebih titik dua ambigu: `::1:443` adalah alamat IPv6 lengkap dan alamat diikuti oleh port. Claude Code memberlakukan ejaan ambigu secara konservatif alih-alih menebak pembacaan mana yang Anda maksudkan:671Entri tanpa kurung siku seperti `::1:443` bersifat ambigu antara sebuah alamat dan alamat yang diikuti port:

601 672

602* **Daftar penolakan**: Claude Code menolak setiap pembacaan yang diuraikan entri, jadi pembacaan mana pun yang Anda maksudkan diblokir. Untuk entri tanpa pembacaan yang dapat diuraikan, Claude Code tidak memblokir apa pun.673* **Daftar penolakan**: Claude Code menolak setiap pembacaan yang dapat di-parse dari entri tersebut, sehingga pembacaan mana pun yang Anda maksud akan diblokir. Untuk entri tanpa pembacaan yang dapat di-parse, Claude Code tidak memblokir apa pun

603* **Daftar izin**: Claude Code tidak pernah memungkinkan lebih dari yang Anda tulis. Ini menulis ulang entri ambigu ke pembacaan host-dan-port ketika pembacaan itu diuraikan dengan bersih, dan mungkin menjatuhkan entri sepenuhnya daripada memperluas allowlist.674* **Daftar izin**: Claude Code tidak pernah mengizinkan lebih dari yang Anda tulis. Claude Code menulis ulang entri ambigu ke pembacaan host-dan-port ketika pembacaan tersebut dapat di-parse dengan bersih, dan dapat membuang entri tersebut sepenuhnya alih-alih memperluas allowlist

604 675

605Jalankan `claude doctor` di terminal Anda untuk menemukan entri yang terpengaruh: peringatan `Sandbox network domain entries have unreliable spellings` menamai hingga tiga dari mereka dan menghitung sisanya. Tulis ulang masing-masing dalam bentuk dalam tanda kurung untuk menghapus peringatan. Peringatan juga menamai entri yang ejaannya tidak dapat diandalkan karena alasan lain, seperti `@`, karakter jalur atau kueri, atau wildcard di dalam tanda kurung.676Untuk menemukan entri yang ambigu, jalankan `claude doctor` di terminal Anda dan cari peringatan `Sandbox network domain entries have unreliable spellings`. Tulis ulang setiap entri yang ambigu dalam bentuk berkurung siku.

606 677

607<h3 id="os-level-enforcement">678<h3 id="os-level-enforcement">

608 Penegakan tingkat OS679 Penerapan tingkat OS

609</h3>680</h3>

610 681

611Alat Bash sandboxed menggunakan primitif keamanan sistem operasi:682Tool Bash yang di-sandbox menggunakan primitif keamanan sistem operasi:

612 683

613* **macOS**: menggunakan Seatbelt untuk penegakan sandbox684* **macOS**: menggunakan Seatbelt untuk penerapan sandbox

614* **Linux**: menggunakan [bubblewrap](https://github.com/containers/bubblewrap) untuk isolasi685* **Linux**: menggunakan [bubblewrap](https://github.com/containers/bubblewrap) untuk isolasi

615* **WSL2**: menggunakan bubblewrap, sama seperti Linux686* **WSL2**: menggunakan bubblewrap, sama seperti Linux

616 687

617WSL1 tidak didukung karena bubblewrap memerlukan fitur kernel yang hanya tersedia di WSL2.688Anda juga dapat menjalankan paket [`@anthropic-ai/sandbox-runtime`](https://github.com/anthropics/sandbox-runtime) secara mandiri untuk membungkus proses Claude Code. Lihat [Sandbox runtime](/docs/id/sandbox-environments#sandbox-runtime).

~~618~~

619Primitif yang sama tersedia sebagai paket [`@anthropic-ai/sandbox-runtime`](https://github.com/anthropic-experimental/sandbox-runtime) mandiri, yang halaman [Sandbox environments](/docs/id/sandbox-environments#sandbox-runtime) mencakup sebagai pendekatan terpisah untuk membungkus seluruh proses Claude Code.

620 689

621<h2 id="how-sandboxing-relates-to-permissions-and-permission-modes">690<h2 id="how-sandboxing-relates-to-permissions-and-permission-modes">

622 Bagaimana sandboxing berhubungan dengan izin dan mode izin691 Bagaimana sandboxing berhubungan dengan izin dan mode izin

679 748

680Untuk memerlukan sandbox untuk setiap pengembang, berikan kunci `sandbox` melalui [managed settings](/docs/id/managed-settings#delivery-mechanisms), baik sebagai file yang dikelola oleh MDM Anda atau melalui [server-managed settings](/docs/id/server-managed-settings) di claude.ai.749Untuk memerlukan sandbox untuk setiap pengembang, berikan kunci `sandbox` melalui [managed settings](/docs/id/managed-settings#delivery-mechanisms), baik sebagai file yang dikelola oleh MDM Anda atau melalui [server-managed settings](/docs/id/server-managed-settings) di claude.ai.

681 750

682Konfigurasi pengaturan terkelola berikut mengaktifkan sandbox, menolak untuk memulai Claude Code jika sandbox tidak dapat diinisialisasi, dan mencegah model dari mencoba kembali perintah di luar sandbox:751Konfigurasi pengaturan terkelola berikut mengaktifkan sandbox, menolak untuk memulai Claude Code ketika platform tidak didukung atau ada dependensi yang hilang, dan mencegah model mencoba ulang perintah di luar sandbox:

683 752

684```json theme={null}753```json theme={null}

685{754{

693 762

694Dua kunci di luar `enabled` mengontrol apa yang terjadi ketika sandbox tidak dapat menjalankan perintah:763Dua kunci di luar `enabled` mengontrol apa yang terjadi ketika sandbox tidak dapat menjalankan perintah:

695 764

696* **`failIfUnavailable`**: dependensi yang hilang seperti bubblewrap di Linux memblokir Claude Code dari memulai daripada menampilkan peringatan dan kembali ke eksekusi unsandboxed765* **`failIfUnavailable`**: dependensi yang hilang seperti bubblewrap di Linux memblokir Claude Code dari memulai alih-alih kembali ke eksekusi unsandboxed

697* **`allowUnsandboxedCommands: false`**: Claude Code mengabaikan escape hatch `dangerouslyDisableSandbox`, sehingga ketika perintah gagal di bawah sandbox, Claude tidak dapat mencoba ulangnya tanpa sandbox766* **`allowUnsandboxedCommands: false`**: Claude Code mengabaikan escape hatch `dangerouslyDisableSandbox`, sehingga ketika perintah gagal di bawah sandbox, Claude tidak dapat mencoba ulangnya tanpa sandbox

698 767

699Dua penambahan layak dipertimbangkan bersama mereka. Tambahkan `excludedCommands` untuk alat yang disetujui organisasi apa pun yang harus berjalan tanpa isolasi. Tambahkan entri [`sandbox.credentials`](#protect-credentials) untuk direktori kredensial seperti `~/.aws` dan `~/.ssh` dan untuk variabel lingkungan rahasia, karena kebijakan pembacaan default masih memungkinkan mereka.768Pertimbangkan penambahan berikut bersama keduanya:

769

770* Tambahkan `excludedCommands` untuk alat apa pun yang disetujui organisasi yang harus berjalan tanpa isolasi, karena konfigurasi ini [mencegah pengaturan repositori mengeluarkan perintah dari sandbox](#repository-settings-under-an-admin-required-sandbox)

771* Tambahkan entri [`sandbox.credentials`](#protect-credentials) untuk direktori kredensial seperti `~/.aws` dan `~/.ssh` dan untuk environment variable rahasia, karena kebijakan pembacaan default masih mengizinkannya

700 772

701Konfigurasi ini melakukan sandboxing pada perintah yang dijalankan Claude. Pengembang masih dapat mengetik perintah di [prompt shell-mode `!`](/docs/id/interactive-mode#shell-mode-with-prefix) dan menjalankannya di luar sandbox, dengan akses yang sama yang mereka miliki di terminal apa pun di luar Claude Code. Lihat [The unsandboxed retry escape hatch](#the-unsandboxed-retry-escape-hatch) untuk sesi di mana perintah yang diketik dijalankan dengan sandbox.773Konfigurasi ini melakukan sandboxing pada perintah yang dijalankan Claude. Pengembang masih dapat mengetik perintah di [prompt shell-mode `!`](/docs/id/interactive-mode#shell-mode-with-prefix) dan menjalankannya di luar sandbox, dengan akses yang sama yang mereka miliki di terminal apa pun di luar Claude Code. Lihat [mode sandbox ketat](#turn-off-the-retry-with-strict-sandbox-mode) untuk sesi di mana perintah yang diketik dijalankan dengan sandbox.

702 774

703Sandbox tidak berjalan di Windows asli, jadi jika armada Anda mencakup host Windows, batasi konfigurasi ini ke macOS dan Linux atau minta pengguna tersebut menjalankan Claude Code di dalam WSL2 atau container.775Sandbox tidak berjalan di Windows asli, sehingga dengan `failIfUnavailable` diatur, Claude Code keluar saat startup di mesin tersebut. Jika armada Anda mencakup host Windows, Anda dapat:

776

777* **Memberikan konfigurasi berdasarkan sistem operasi**: terapkan melalui MDM Anda atau sebagai [file pengaturan terkelola](/docs/id/managed-settings#delivery-mechanisms) hanya di mesin macOS dan Linux. [Server-managed settings](/docs/id/server-managed-settings#current-limitations) berlaku untuk semua pengguna di organisasi

778* **Memindahkan pengguna Windows ke lingkungan yang didukung**: minta mereka menjalankan Claude Code di dalam WSL2 atau container

704 779

705<h3 id="keep-developers-from-widening-the-policy">780<h3 id="keep-developers-from-widening-the-policy">

706 Cegah pengembang memperluas kebijakan781 Cegah pengembang memperluas kebijakan

707</h3>782</h3>

708 783

709Untuk kunci boolean seperti `enabled` dan `failIfUnavailable`, Claude Code menggunakan nilai terkelola dan mengabaikan apa pun yang ditetapkan pengembang secara lokal. Untuk kunci array seperti `excludedCommands` dan `allowRead`, Claude Code menggabungkan entri dari setiap scope yang dimuat sesi, sehingga pengembang dapat menambahkan entri yang memperluas kebijakan.784Ketika pengaturan terkelola menetapkan kunci Boolean seperti `enabled` atau `failIfUnavailable`, Claude Code menggunakan nilai terkelola dan mengabaikan apa pun yang ditetapkan pengembang secara lokal. Untuk kunci array seperti `allowRead`, Claude Code menggabungkan entri dari cakupan yang dimuat sesi, sehingga pengembang dapat menambahkan entri yang memperluas kebijakan kecuali ada kunci pengunci yang mencakup kunci tersebut.

785

786Kecuali pengaturan terkelola menetapkannya, pengaturan pengguna milik pengembang atau `--settings` dapat mengaktifkan kunci berikut. `.claude/settings.json` milik repositori juga dapat melakukannya, kecuali sandbox bersifat [diwajibkan admin](#repository-settings-under-an-admin-required-sandbox). Masing-masing melemahkan sandbox, jadi atur ke `false` dalam pengaturan terkelola jika Anda tidak ingin kunci tersebut digunakan:

787

788* [`enableWeakerNestedSandbox`](/docs/id/settings-reference#sandbox-enableweakernestedsandbox)

789* [`enableWeakerNetworkIsolation`](/docs/id/settings-reference#sandbox-enableweakernetworkisolation)

790* [`network.allowAllUnixSockets`](/docs/id/settings-reference#sandbox-network-allowallunixsockets)

791* [`network.allowLocalBinding`](/docs/id/settings-reference#sandbox-network-allowlocalbinding)

792* [`allowAppleEvents`](/docs/id/settings-reference#sandbox-allowappleevents), yang tidak dapat diaktifkan oleh repositori

793

794Atur `allowManagedReadPathsOnly` ke `true` dalam pengaturan terkelola sehingga hanya entri `allowRead` dari pengaturan terkelola yang dihormati. Ini mencegah pengembang memperluas akses baca di luar jalur yang disetujui organisasi.

710 795

711Atur `allowManagedReadPathsOnly` ke `true` dalam pengaturan terkelola sehingga hanya entri `allowRead` dari pengaturan terkelola yang dihormati. Ini mencegah pengembang memperluas akses baca di luar jalur yang disetujui organisasi. Untuk mengunci domain jaringan ke nilai terkelola dengan cara yang sama, atur [`allowManagedDomainsOnly`](/docs/id/settings-reference#sandbox-network-allowmanageddomainsonly).796Untuk mengunci domain jaringan ke nilai terkelola dengan cara yang sama, atur [`allowManagedDomainsOnly`](/docs/id/settings-reference#sandbox-network-allowmanageddomainsonly). Dengan penguncian ini aktif, hanya pengaturan terkelola yang dapat menetapkan [port proxy](#custom-proxy-configuration).

712 797

713Ketika pengaturan terkelola mengonfigurasi `sandbox.filesystem` atau mencantumkan entri `sandbox.credentials.files` apa pun dengan `"mode": "deny"`, hanya pengaturan terkelola yang dapat mengatur [`filesystem.disabled`](#disable-filesystem-isolation), sehingga pengembang tidak dapat mematikan pembatasan filesystem yang diterapkan administrator. Apakah entri `mask` mengikat kunci tergantung pada cara penyelesaiannya; tabel di bawah [Which settings can disable it](#which-settings-can-disable-it) mencakup empat kasus.798Ketika pengaturan terkelola mengonfigurasi `sandbox.filesystem` atau mencantumkan entri `sandbox.credentials.files` apa pun dengan `"mode": "deny"`, hanya pengaturan terkelola yang dapat mengatur [`filesystem.disabled`](#disable-filesystem-isolation), sehingga pengembang tidak dapat mematikan pembatasan filesystem yang diterapkan administrator. Entri `mask` yang [valid](/docs/id/settings-reference#invalid-credential-entries-in-managed-settings) tidak mengunci kunci tersebut. Lihat [Which settings can disable it](#which-settings-can-disable-it).

714 799

715`excludedCommands` tidak memiliki lockdown hanya terkelola yang setara, sehingga pengembang selalu dapat menambahkan entri yang menjalankan perintah tambahan di luar sandbox. Jaga daftar terkelola tetap sempit.800<h4 id="repository-settings-under-an-admin-required-sandbox">

801 Pengaturan repositori di bawah sandbox yang diwajibkan admin

802</h4>

803

804Sandbox bersifat diwajibkan admin selama salah satu pengaturan berikut berlaku:

805

806* [`allowUnsandboxedCommands`](/docs/id/settings-reference#sandbox-allowunsandboxedcommands) diatur ke `false` dalam pengaturan terkelola, atau dengan flag `--settings` kecuali pengaturan terkelola mengaturnya ke `true`

807* [`allowManagedDomainsOnly`](/docs/id/settings-reference#sandbox-network-allowmanageddomainsonly) diatur ke `true` dalam pengaturan terkelola

808

809Pengaturan ini tidak mengaktifkan sandbox, jadi atur juga `enabled`.

810

811Selama sandbox diwajibkan admin, Claude Code mengambil pengaturan yang melonggarkannya hanya dari pengaturan terkelola, flag `--settings`, dan `~/.claude/settings.json` milik setiap pengembang. Claude Code mengabaikan pengaturan berikut di `.claude/settings.json` dan `.claude/settings.local.json` milik repositori:

812

813| Pengaturan repositori | Apa yang diabaikan Claude Code |

814| :- | :- |

815| `excludedCommands`, `ignoreViolations`, `network.allowedDomains`, `network.allowUnixSockets`, `network.allowMachLookup`, `network.httpProxyPort`, `network.socksProxyPort` | Setiap entri |

816| `filesystem.allowWrite`, aturan izinkan `Edit(...)`, `permissions.additionalDirectories` | Akses tulis yang diberikan setiap entri kepada perintah yang di-sandbox. Tool file Claude tetap mengikuti aturan `Edit(...)` dan direktori tambahan |

817| Aturan izinkan `WebFetch(domain:...)` | Host yang ditambahkan setiap aturan ke allowlist sandbox. Tool WebFetch tetap mengikuti aturan tersebut |

818| `enableWeakerNestedSandbox`, `enableWeakerNetworkIsolation`, `network.allowAllUnixSockets`, `network.allowLocalBinding` | `true`. Nilai `false` tetap berlaku |

819| `enabled`, `failIfUnavailable` | `false`, ketika `~/.claude/settings.json` milik pengembang menetapkan `true` |

820| `filesystem.allowRead` | Entri pada atau di bawah jalur yang dilarang untuk dibaca oleh pengaturan terkelola, `--settings`, atau pengaturan pengguna, atau glob yang dapat mencocokkan salah satunya |

821

822Pengaturan berikut tetap berlaku selama sandbox diwajibkan admin:

823

824* **Di file repositori**: entri deny dan nilai `autoAllowBashIfSandboxed`. Atur kunci tersebut dalam pengaturan terkelola untuk mencegah repositori mengubahnya

825* **Di pengaturan milik pengembang sendiri**: pengaturan dalam tabel tetap berlaku dari `~/.claude/settings.json` atau `--settings`, kecuali penguncian khusus terkelola seperti `allowManagedDomainsOnly` mencakupnya. Sebagian besar di antaranya, seperti `excludedCommands` dan `filesystem.allowWrite`, tidak memiliki penguncian khusus terkelola

826

827Konfigurasi di bawah [Memberlakukan sandboxing dengan pengaturan terkelola](#enforce-sandboxing-with-managed-settings) membuat sandbox diwajibkan admin. Tambahkan entri `excludedCommands`, `allowWrite`, dan socket yang dibutuhkan alat yang Anda setujui ke pengaturan terkelola, karena repositori tidak dapat menyediakannya.

828

829Memerlukan Claude Code v2.1.285 atau lebih baru. Dari v2.1.282 hingga v2.1.284, pengaturan yang sama membuat Claude Code mengabaikan entri `excludedCommands` milik repositori.

830

831<h4 id="locks-that-apply-without-an-admin-required-sandbox">

832 Penguncian yang berlaku tanpa sandbox yang diwajibkan admin

833</h4>

834

835Beberapa pengaturan membuat Claude Code mengabaikan kunci repositori yang secara langsung menimpa satu pembatasan, bahkan ketika sandbox tidak diwajibkan admin. Masing-masing memiliki efek ini hanya ketika Anda mengaturnya di file yang disebutkan dalam barisnya, dan pengaturan sandbox lain milik repositori tetap berlaku. Memerlukan Claude Code v2.1.285 atau lebih baru.

836

837| Pengaturan | Tempat Anda mengaturnya | Apa yang diabaikan Claude Code dalam pengaturan repositori |

838| :- | :- | :- |

839| `network.deniedDomains` atau aturan deny `WebFetch(domain:...)` | Pengaturan terkelola, `--settings` | `httpProxyPort` dan `socksProxyPort` |

840| `network.strictAllowlist` | Pengaturan terkelola, `--settings`, pengaturan pengguna | Port proxy, `allowedDomains`, dan aturan izinkan `WebFetch(domain:...)` |

841| `filesystem.denyRead`, aturan deny `Read(...)`, atau entri `credentials.files` | Pengaturan terkelola, `--settings` | Entri `allowRead`, `allowWrite`, izinkan `Edit(...)`, atau `additionalDirectories` pada atau di bawah jalur yang dilarang untuk dibaca oleh pengaturan terkelola, `--settings`, atau pengaturan pengguna, atau glob yang dapat mencocokkan salah satunya |

842

843Penguncian ini mengubah apa yang dapat dijangkau oleh perintah yang di-sandbox. Tool WebFetch dan tool file Claude tetap mengikuti aturan dan direktori tambahan milik repositori.

716 844

717<h3 id="custom-proxy-configuration">845<h3 id="custom-proxy-configuration">

718 Konfigurasi proxy khusus846 Konfigurasi proxy khusus

719</h3>847</h3>

720 848

721Untuk organisasi yang memerlukan keamanan jaringan lanjutan, Anda dapat menerapkan proxy khusus untuk:849Untuk memeriksa, memfilter, atau mencatat lalu lintas sandbox dengan alat Anda sendiri, ganti proxy sandbox bawaan dengan proxy yang Anda jalankan di mesin yang sama.

722 850

723* Mendekripsi dan memeriksa lalu lintas HTTPS851Untuk merutekan lalu lintas sandbox melalui proxy perusahaan di tempat lain dalam jaringan Anda, atur `HTTPS_PROXY` sebagai gantinya, seperti yang dijelaskan entri **Corporate proxy** di bawah [Network isolation](#network-isolation). Dengan cara itu, allowlist Claude Code tetap berlaku.

724* Menerapkan aturan penyaringan khusus

725* Mencatat semua permintaan jaringan

726* Mengintegrasikan dengan infrastruktur keamanan yang ada

727 852

728Untuk menunjukkan Claude Code ke proxy Anda, atur port proxy dalam [sandbox settings](/docs/id/settings-reference#sandbox-settings):853Untuk mengarahkan perintah yang di-sandbox ke proxy Anda, atur port localhost yang didengarkannya dalam [sandbox settings](/docs/id/settings-reference#sandbox-settings):

729 854

730```json theme={null}855```json theme={null}

731{856{

738}863}

739```864```

740 865

866Jika Anda mengatur port dan juga mengatur `HTTPS_PROXY` atau `HTTP_PROXY`, Claude Code tidak meneruskan apa yang dikirim perintah yang di-sandbox ke proxy Anda kepada proxy yang disebutkan oleh variabel tersebut. Untuk menjangkau proxy perusahaan, konfigurasikan proxy Anda sendiri agar meneruskan ke sana.

867

868File mana yang dapat mengatur port bergantung pada pengaturan sandbox Anda yang lain:

869

870* **`allowManagedDomainsOnly` aktif**: hanya pengaturan terkelola

871* **Sandbox [diwajibkan admin](#repository-settings-under-an-admin-required-sandbox), atau [penguncian jaringan yang lebih sempit](#locks-that-apply-without-an-admin-required-sandbox) berlaku**: pengaturan terkelola, `--settings`, dan pengaturan pengguna

872* **Selain itu**: file pengaturan apa pun

873

874Claude Code mengabaikan port yang diatur di tempat lain. Sebelum v2.1.285, file pengaturan apa pun dapat mengatur port.

875

876<Warning>

877 Setelah salah satu port berlaku, proxy Anda bertanggung jawab untuk memfilter semua yang dikirim kepadanya. Kontrol jaringan milik Claude Code sendiri, seperti `allowedDomains`, `deniedDomains`, `strictAllowlist`, permintaan persetujuan, dan [pemeriksaan alamat lokal](#hostnames-that-resolve-to-local-addresses), tidak lagi berlaku untuk lalu lintas tersebut. Perintah yang di-sandbox dapat terhubung ke salah satu proxy, sehingga jika Anda hanya mengatur satu port, daftar domain Claude Code pada proxy lainnya tidak membatasi apa yang dijangkau perintah melalui proxy Anda.

878</Warning>

879

741<h2 id="troubleshooting">880<h2 id="troubleshooting">

742 Pemecahan masalah881 Pemecahan masalah

743</h2>882</h2>

744 883

745Beberapa perintah gagal di dalam sandbox meskipun bekerja di luar itu. Perbaikan di bawah mencakup kasus paling umum.884Beberapa perintah gagal di dalam sandbox meskipun bekerja di luar itu. Temukan judul yang sesuai dengan gejala atau pesan kesalahan Anda.

885

886Jika sandbox organisasi Anda bersifat [wajib oleh admin](#repository-settings-under-an-admin-required-sandbox), Claude Code mengabaikan pengaturan yang disebutkan oleh perbaikan ini di file pengaturan proyek, jadi simpan pengaturan tersebut di `~/.claude/settings.json`, tempat pengaturan itu berlaku di setiap proyek. Jika suatu perbaikan tetap tidak berpengaruh, pengaturan terkelola organisasi Anda mungkin menetapkan kunci tersebut.

887

888Perbaikan yang menambahkan pola `excludedCommands` menghapus sandbox dari perintah yang cocok dengan pola tersebut. Lihat [apa yang dapat dilakukan perintah yang dikecualikan](#run-commands-outside-the-sandbox-with-excludedcommands).

889

890<h3 id="commands-fail-with-a-host-not-allowed-error">

891 Perintah gagal dengan kesalahan host-not-allowed

892</h3>

893

894Banyak tool CLI perlu menjangkau host tertentu. Setujui host saat diminta, atau tambahkan ke [`allowedDomains`](/docs/id/settings-reference#sandbox-network-alloweddomains). Jika organisasi Anda mengunci allowlist dengan `allowManagedDomainsOnly`, tidak ada permintaan izin, jadi minta administrator Anda untuk menambahkan host tersebut.

895

896<h3 id="jest-hangs-or-fails">

897 `jest` hang atau gagal

898</h3>

899

900`watchman` tidak kompatibel dengan sandbox. Jalankan `jest --no-watchman` sebagai gantinya.

901

902<h3 id="go-based-clis-fail-tls-verification-on-macos">

903 Go-based CLIs gagal verifikasi TLS di macOS

904</h3>

905

906Tool seperti `gh`, `gcloud`, dan `terraform` mungkin gagal verifikasi TLS di bawah [Seatbelt](#os-level-enforcement). Untuk menjalankan tool ini di luar sandbox, tambahkan pola untuk setiap tool, seperti `gh *`, ke [`excludedCommands`](#run-commands-outside-the-sandbox-with-excludedcommands). Tool tersebut kemudian berjalan dengan akses penuh Anda dan kredensial yang tersimpan. Jika Anda menggunakan `httpProxyPort` dengan proxy MITM dan CA khusus, atur [`enableWeakerNetworkIsolation`](/docs/id/settings-reference#sandbox-enableweakernetworkisolation) ke `true` sebagai gantinya.

907

908<h3 id="open-osascript-or-browser-based-auth-flows-fail-with-error-600-on-macos">

909 `open`, `osascript`, atau alur autentikasi berbasis browser gagal dengan kesalahan `-600` di macOS

910</h3>

911

912Sandbox memblokir Apple Events secara default. Atur [`allowAppleEvents`](/docs/id/settings-reference#sandbox-allowappleevents) ke `true` dalam pengaturan pengguna, terkelola, atau CLI Anda untuk mengizinkannya. Claude Code mengabaikan kunci ini dalam pengaturan proyek.

913

914Mengaktifkan `allowAppleEvents` menghilangkan isolasi eksekusi kode, karena perintah sandboxed kemudian dapat meluncurkan aplikasi lain tanpa sandbox tanpa permintaan izin pengguna, dan dapat mengirim perintah AppleScript ke aplikasi yang berjalan, tunduk pada permintaan persetujuan otomasi macOS (TCC). Alternatifnya, tambahkan pola seperti `open *` ke [`excludedCommands`](#run-commands-outside-the-sandbox-with-excludedcommands). Setiap panggilan `open` kemudian melalui alur izin, dan `open` dapat meluncurkan file atau aplikasi apa pun, termasuk yang ditulis oleh Claude.

915

916<h3 id="docker-commands-fail">

917 Perintah `docker` gagal

918</h3>

919

920`docker` tidak kompatibel dengan sandbox. Keluarkan perintah `docker` yang Anda butuhkan dari sandbox dengan pola `excludedCommands` seperti `docker compose *`. [Menjalankan perintah di luar sandbox dengan `excludedCommands`](#run-commands-outside-the-sandbox-with-excludedcommands) menjelaskan apa yang dapat dijangkau oleh perintah `docker` yang dikecualikan. Pola yang lebih sempit mengeluarkan lebih sedikit perintah dari sandbox.

921

922<h3 id="pbcopy-xclip-or-wl-copy-doesn’t-update-the-clipboard">

923 `pbcopy`, `xclip`, atau `wl-copy` tidak memperbarui clipboard

924</h3>

925

926Utilitas clipboard `pbcopy`, `xclip`, dan `wl-copy` dapat gagal menjangkau clipboard sistem dari dalam sandbox, dalam hal ini teks yang dialirkan ke dalamnya tidak tiba.

927

928Untuk menempatkan output Claude di clipboard Anda, minta Claude untuk mencetaknya dalam responsnya, kemudian jalankan [`/copy`](/docs/id/commands). `/copy` menulis ke clipboard dari proses Claude Code daripada dari perintah sandboxed.

929

930Ketika Claude mengalirkan teks ke salah satu tool ini, menambahkan tool ke [`excludedCommands`](/docs/id/settings-reference#sandbox-excludedcommands) tidak mengeluarkan panggilan itu dari sandbox dengan sendirinya.

931

932<h3 id="a-git-command-fails-with-unable-to-unlink-old">

933 Perintah git gagal dengan `unable to unlink old`

934</h3>

935

936`git merge`, `git checkout`, dan perintah serupa gagal dengan `unable to unlink old` ketika mereka perlu mengganti file yang penulisannya ditolak oleh sandbox. Di Linux dan WSL2 kesalahan berakhir dengan `Read-only file system`. File tersebut dapat berada di salah satu lokasi berikut:

937

938* Di bawah [jalur yang dilindungi](#protected-paths) seperti `.claude/skills`

939* Di bawah salah satu entri `denyWrite` Anda

940* Di luar direktori yang sama sekali diizinkan sandbox untuk ditulisi oleh perintah

941

942Setelah kegagalan, Claude mungkin [menawarkan untuk menjalankan kembali perintah di luar sandbox](#the-unsandboxed-retry-escape-hatch). Setujui retry itu, atau jalankan perintah git sendiri di terminal lain. Jika Anda telah menetapkan `allowUnsandboxedCommands` ke `false`, Claude tidak dapat menawarkan retry, jadi jalankan perintah sendiri.

943

944<h3 id="bubblewrap-fails-to-start-inside-a-container">

945 Bubblewrap gagal memulai di dalam container

946</h3>

947

948Dalam container tanpa privilege, [bubblewrap](#os-level-enforcement) tidak dapat memasang filesystem `/proc` baru, sehingga perintah sandboxed gagal dengan kesalahan `bwrap` seperti `Can't mount proc on /newroot/proc: Operation not permitted`. Atur [`enableWeakerNestedSandbox`](/docs/id/settings-reference#sandbox-enableweakernestedsandbox) ke `true` sehingga sandbox melakukan bind-mount terhadap `/proc` yang sudah ada milik container sebagai gantinya. Hanya gunakan pengaturan ini ketika container luar sudah menyediakan batas isolasi yang Anda butuhkan, karena pengaturan ini mengekspos informasi proses ke perintah sandboxed yang akan disembunyikan oleh mount `/proc` baru.

949

950<h3 id="0-byte-read-only-files-appear-at-claude-settings-paths-and-yes-and-don’t-ask-again-doesn’t-save">

951 File read-only 0-byte muncul di jalur pengaturan `.claude`, dan "Ya, dan jangan tanya lagi" tidak menyimpan

952</h3>

953

954Di Linux dan WSL2, sandbox menahan penolakan penulisan pada file yang belum ada dengan membuat placeholder read-only 0-byte di sana sementara perintah sandboxed berjalan. Sandbox menghapus placeholder setelahnya. Jika sesi dihentikan paksa sebelum pembersihan itu berjalan, misalnya oleh SIGKILL, placeholder tetap tertinggal. Sesi berikutnya mengikat placeholder tersebut sebagai read-only lagi pada setiap awal, sehingga penulisan pengaturan seperti menyimpan pilihan izin gagal di jalur tempat placeholder masih ada.

955

956Jalankan `claude doctor` di terminal Anda untuk membuat daftar file placeholder yang tersisa. Peringatan [`Stale sandbox mask files left by a killed session`](/docs/id/errors#stale-sandbox-mask-files-left-by-a-killed-session) menyebutkan beberapa di antaranya dan menghitung sisanya. Hapus setiap file dengan `rm` sementara tidak ada sesi Claude Code lain yang berjalan di proyek itu. Sebelum v2.1.257, Claude Code meninggalkan placeholder yang sama tanpa menandainya.

957

958<h3 id="git-over-ssh-fails-with-the-sandbox-on">

959 `git` melalui SSH gagal saat sandbox aktif

960</h3>

961

962Di macOS, `git fetch`, `git pull`, dan `git push` terhadap remote SSH gagal di dalam sandbox bahkan ketika host diizinkan. Di Linux dan WSL2, perintah tersebut berfungsi setelah host diizinkan. Claude Code menyalurkan koneksi SSH git melalui [proxy sandbox](#network-isolation), dan tunnel macOS tidak dapat melakukan autentikasi ke proxy tersebut.

963

964Di Linux dan WSL2, periksa hal-hal berikut jika koneksi masih gagal:

965

966* **Host diizinkan pada port 22**: entri `allowedDomains` tanpa port, seperti `"git.example.com"`, mencakupnya

967* **Proxy perusahaan Anda mengizinkan port 22**: jika jaringan Anda memerlukan proxy upstream, tunnel juga melewatinya

968* **Kunci dapat dibaca sebagai file**: sandbox dapat memblokir socket `ssh-agent`, dan entri `denyRead` atau `credentials` untuk `~/.ssh` menyembunyikan file kunci Anda

969

970Di macOS, ubah remote ke HTTPS, yang memerlukan kredensial HTTPS seperti personal access token:

971

972```bash theme={null}

973git remote set-url origin https://git.example.com/example-org/example-repo.git

974```

975

976Jika Anda harus mempertahankan remote SSH, keluarkan perintah jaringan git dari sandbox dengan [`excludedCommands`](#run-commands-outside-the-sandbox-with-excludedcommands):

977

978```json theme={null}

979{

980 "sandbox": {

981 "excludedCommands": ["git fetch *", "git pull *", "git push *"]

982 }

983}

984```

985

986Entri ini cocok dengan `git push origin main`. Panggilan yang menambahkan `cd`, menggunakan `git -C`, atau berisi command substitution tetap berada di dalam sandbox. Perintah git yang dikecualikan dapat menjangkau host mana pun, tidak hanya yang ada di `allowedDomains`.

987

988`ssh`, `scp`, dan `rsync` biasa melalui SSH gagal karena alasan yang diberikan oleh [entri klien database](#a-database-client-or-other-non-http-tool-fails-to-reach-an-allowed-host).

989

990<h3 id="a-database-client-or-other-non-http-tool-fails-to-reach-an-allowed-host">

991 Klien database atau tool non-HTTP lainnya gagal menjangkau host yang diizinkan

992</h3>

993

994Tool yang mengabaikan environment variable proxy tidak dapat terhubung dari dalam sandbox, bahkan ke host yang ada di `allowedDomains`. Perintah sandboxed [tidak memiliki rute langsung ke jaringan](#network-isolation), sehingga tool yang membuka koneksinya sendiri akan gagal. Sebagian besar driver database, `ssh` biasa, dan tool yang menggunakan UDP berperilaku seperti ini.

995

996Kegagalan tampak seperti kesalahan jaringan atau resolusi nama:

997

998* **macOS**: `Operation not permitted`, atau kesalahan resolusi nama seperti `Could not resolve host`

999* **Linux dan WSL2**: `Network is unreachable`, atau kesalahan resolusi nama seperti `Temporary failure in name resolution`

1000

1001Tool yang menggunakan proxy gagal dengan cara berbeda ketika host-nya tidak diizinkan. Anda mendapatkan permintaan izin jaringan, atau tool menerima respons `403` dari proxy.

1002

1003Untuk memungkinkan tool terhubung, jalankan perintah yang memerlukannya di luar sandbox dengan [`excludedCommands`](#run-commands-outside-the-sandbox-with-excludedcommands). Contoh ini mengecualikan satu skrip dan menambahkan [aturan ask](/docs/id/permissions) sehingga Anda menyetujui setiap eksekusi:

1004

1005```json theme={null}

1006{

1007 "sandbox": {

1008 "excludedCommands": ["python scripts/load_orders.py *"]

1009 },

1010 "permissions": {

1011 "ask": ["Bash(python scripts/load_orders.py *)"]

1012 }

1013}

1014```

1015

1016Skrip berjalan dengan akses penuh Anda, dan Claude dapat mengedit skrip yang berada di dalam direktori kerja Anda, jadi tinjau skrip tersebut saat permintaan izin muncul.

1017

1018<h3 id="a-command-fails-to-reach-a-server-on-localhost">

1019 Perintah gagal menjangkau server di localhost

1020</h3>

1021

1022Secara default, perintah sandboxed tidak dapat terhubung langsung ke server yang berjalan di mesin Anda di luar sandbox, seperti dev server atau database dalam container. Apa yang dapat Anda ubah bergantung pada platform Anda:

746 1023

747* **Perintah gagal dengan kesalahan host-not-allowed**: banyak alat CLI perlu menjangkau host tertentu. Memberikan izin saat diminta menambahkan host ke daftar yang diizinkan sehingga alat berjalan di dalam sandbox di masa depan.1024* **macOS**: atur [`network.allowLocalBinding`](/docs/id/settings-reference#sandbox-network-allowlocalbinding) ke `true`. Perintah sandboxed kemudian dapat mendengarkan pada port jaringan dan terhubung ke port mana pun di localhost, yang mencakup setiap layanan lain yang mendengarkan di sana. Layanan localhost yang tidak memerlukan autentikasi, seperti debugger, kemudian dapat bertindak atas nama perintah di luar sandbox, dan perintah yang mendengarkan pada alamat non-loopback menerima koneksi dari mesin lain

748* **`jest` hang atau gagal**: `watchman` tidak kompatibel dengan sandbox. Jalankan `jest --no-watchman` sebagai gantinya.1025* **Linux dan WSL2**: `localhost` milik perintah sandboxed bersifat privat untuk perintah tersebut. Perintah dapat mendengarkan pada port dan menjangkau server yang dimulainya sendiri. Koneksi langsung ke `localhost` atau `127.0.0.1` tidak menjangkau server di host, dan `allowLocalBinding` tidak berpengaruh. Jalankan perintah yang memerlukan server host di luar sandbox dengan [`excludedCommands`](#run-commands-outside-the-sandbox-with-excludedcommands), tempat perintah tersebut tidak memiliki batasan filesystem atau jaringan. Untuk koneksi yang melalui proxy sandbox, lihat [Hostname yang di-resolve ke alamat lokal](#hostnames-that-resolve-to-local-addresses)

749* **Go-based CLIs gagal verifikasi TLS di macOS**: alat seperti `gh`, `gcloud`, dan `terraform` mungkin gagal verifikasi TLS di bawah Seatbelt. Daftar alat ini dalam [`excludedCommands`](/docs/id/settings-reference#sandbox-excludedcommands). Jika Anda menggunakan `httpProxyPort` dengan proxy MITM dan CA khusus, atur [`enableWeakerNetworkIsolation`](/docs/id/settings-reference#sandbox-enableweakernetworkisolation) ke `true` sebagai gantinya.

750* **Perintah `open`, `osascript`, atau alur autentikasi berbasis browser gagal dengan kesalahan `-600` di macOS**: sandbox memblokir Apple Events secara default. Atur [`allowAppleEvents`](/docs/id/settings-reference#sandbox-allowappleevents) ke `true` dalam pengaturan pengguna, terkelola, atau CLI Anda untuk mengizinkannya. Pengaturan proyek diabaikan untuk kunci ini. Mengaktifkannya menghilangkan isolasi eksekusi kode, karena perintah sandboxed kemudian dapat meluncurkan aplikasi lain tanpa sandbox tanpa prompt pengguna dan mengirim perintah AppleScript ke aplikasi yang berjalan, tunduk pada prompt otomasi-persetujuan macOS (TCC). Alternatifnya, tambahkan perintah ke [`excludedCommands`](/docs/id/settings-reference#sandbox-excludedcommands).

751* **Perintah `docker` gagal**: `docker` tidak kompatibel dengan sandbox. Tambahkan `docker *` ke [`excludedCommands`](/docs/id/settings-reference#sandbox-excludedcommands).

752* **`pbcopy`, `xclip`, atau `wl-copy` tidak memperbarui clipboard**: utilitas clipboard ini dapat gagal menjangkau clipboard sistem dari dalam sandbox, dalam hal ini teks yang dialirkan ke dalamnya tidak tiba.

753 1026

754 Untuk menempatkan output Claude di clipboard Anda, minta Claude untuk mencetaknya dalam responsnya, kemudian jalankan [`/copy`](/docs/id/commands). `/copy` menulis ke clipboard dari proses Claude Code daripada dari perintah sandboxed.1027Contoh ini mengaktifkan pengaturan untuk macOS:

755 1028

756 Ketika Claude mengalirkan teks ke salah satu alat ini, menambahkan alat ke [`excludedCommands`](/docs/id/settings-reference#sandbox-excludedcommands) tidak mengeluarkan panggilan itu dari sandbox dengan sendirinya.1029```json theme={null}

757* **Perintah git gagal dengan `unable to unlink old`**: `git merge`, `git checkout`, dan perintah serupa gagal dengan cara ini ketika mereka perlu mengganti file yang sandbox tolak penulisannya, apakah file itu berada di bawah [jalur yang dilindungi](#protected-paths) seperti `.claude/skills`, di bawah salah satu entri `denyWrite` Anda, atau di luar direktori yang sandbox izinkan perintah untuk menulis sama sekali. Di Linux dan WSL2 kesalahan berakhir dengan `Read-only file system`.1030{

1031 "sandbox": {

1032 "network": {

1033 "allowLocalBinding": true

1034 }

1035 }

1036}

1037```

1038

1039Entri `allowedDomains` untuk `localhost` berlaku untuk koneksi yang melalui proxy, sehingga tidak mengubah koneksi langsung. Claude Code menetapkan `NO_PROXY` untuk perintah sandboxed sehingga perintah tersebut terhubung ke `localhost` secara langsung alih-alih melalui proxy. Entri tersebut juga mengekspos setiap port di localhost mesin Anda ke perintah yang memang menggunakan proxy. Untuk hostname pengembangan yang mengarah ke `127.0.0.1`, lihat [Hostname yang diizinkan ditolak dengan `resolved to a loopback address`](#an-allowed-hostname-is-refused-with-resolved-to-a-loopback-address).

1040

1041<h3 id="an-allowed-hostname-is-refused-with-resolved-to-a-loopback-address">

1042 Hostname yang diizinkan ditolak dengan `resolved to a loopback address`

1043</h3>

1044

1045Proxy sandbox menolak hostname yang diizinkan yang [di-resolve ke alamat lokal](#hostnames-that-resolve-to-local-addresses), yang memengaruhi nama pengembangan seperti `myapp.test` yang mengarah ke `127.0.0.1`. Perintah melihat respons `403` yang isinya menyebutkan jenis alamat, seperti `Connection to myapp.test blocked: resolved to a loopback address`.

1046

1047Tambahkan alamat IP tempat nama tersebut di-resolve bersama hostname di `allowedDomains`, masing-masing dengan port tempat server Anda mendengarkan:

1048

1049```json theme={null}

1050{

1051 "sandbox": {

1052 "network": {

1053 "allowedDomains": ["myapp.test:3000", "127.0.0.1:3000"]

1054 }

1055 }

1056}

1057```

758 1058

759 Setelah kegagalan, Claude mungkin [menawarkan untuk menjalankan kembali perintah di luar sandbox](#the-unsandboxed-retry-escape-hatch); setujui retry itu, atau jalankan perintah git sendiri di terminal lain. Jika Anda telah menetapkan `allowUnsandboxedCommands` ke `false`, Claude tidak dapat menawarkan retry, jadi jalankan perintah sendiri. Jika perintah git yang sama sering gagal, tambahkan ke [`excludedCommands`](/docs/id/settings-reference#sandbox-excludedcommands).1059Entri alamat IP tanpa port memungkinkan perintah sandboxed menjangkau setiap layanan yang mendengarkan pada alamat tersebut.

760* **Bubblewrap gagal memulai di dalam container**: dalam container tanpa privilege, bubblewrap tidak dapat memasang filesystem `/proc` segar, sehingga perintah sandboxed gagal dengan kesalahan `bwrap` seperti `Can't mount proc on /newroot/proc: Operation not permitted`. Atur [`enableWeakerNestedSandbox`](/docs/id/settings-reference#sandbox-enableweakernestedsandbox) ke `true` sehingga sandbox dalam bind-mount `/proc` yang ada dari container sebagai gantinya. Hanya gunakan pengaturan ini ketika container luar sudah menyediakan batas isolasi yang Anda butuhkan, karena mengekspos informasi proses ke perintah sandboxed yang mount `/proc` segar akan menyembunyikan.

761* **File read-only 0-byte muncul di jalur pengaturan `.claude`, dan "Ya, dan jangan tanya lagi" tidak menyimpan**: di Linux dan WSL2, sandbox menahan penolakan penulisan pada file yang belum ada dengan membuat placeholder read-only 0-byte di sana sementara perintah sandboxed berjalan. Sandbox menghapus placeholder setelahnya. Jika sesi dibunuh sebelum pembersihan itu berjalan, misalnya oleh SIGKILL, placeholder tetap tertinggal. Sesi kemudian mengikatnya read-only lagi pada setiap awal, jadi penulisan pengaturan seperti menyimpan pilihan izin gagal di mana satu duduk.

762 1060

763 Jalankan `claude doctor` untuk membuat daftar file placeholder yang tersisa. Peringatan [`Stale sandbox mask files left by a killed session`](/docs/id/errors#stale-sandbox-mask-files-left-by-a-killed-session) menamai hingga tiga di antaranya dan menghitung sisanya. Hapus setiap file dengan `rm` sementara tidak ada sesi Claude Code lain yang berjalan di proyek itu. Sebelum v2.1.257, Claude Code meninggalkan placeholder yang sama tanpa menandainya.1061Sebelum v2.1.284, proxy terhubung ke alamat apa pun tempat hostname yang diizinkan di-resolve.

764* **`--dangerously-skip-permissions` gagal sebagai root**: flag ini diblokir saat menjalankan sebagai root atau melalui sudo di Linux dan macOS, karena akses root dikombinasikan dengan tidak ada prompt izin dapat memodifikasi file atau layanan apa pun di sistem. Pemeriksaan dilewati secara otomatis di dalam sandbox yang dikenali. Untuk menjalankan secara otonom dalam container, gunakan konfigurasi [dev container](/docs/id/devcontainer), yang menjalankan Claude Code sebagai pengguna non-root.1062

1063<h3 id="/sandbox-fails-with-sandbox-settings-are-overridden-by-a-higher-priority-configuration">

1064 `/sandbox` gagal dengan `Sandbox settings are overridden by a higher-priority configuration`

1065</h3>

1066

1067`/sandbox` mencetak `Error: Sandbox settings are overridden by a higher-priority configuration and cannot be changed locally.` alih-alih membuka panelnya ketika [tingkat pengaturan](/docs/id/settings#settings-precedence) yang lebih tinggi menetapkan `sandbox.enabled`, `sandbox.autoAllowBashIfSandboxed`, atau `sandbox.allowUnsandboxedCommands`. Panel menyimpan pilihan Anda ke `.claude/settings.local.json`, dan nilai yang disimpan di sana tidak dapat menimpa tingkat-tingkat tersebut.

1068

1069Pengaturan terkelola dan `--settings` memiliki peringkat di atas pengaturan lokal. Untuk melihat mana di antaranya yang dimuat oleh sesi ini, jalankan `/status` dan baca baris `Setting sources`:

1070

1071* **`Command line arguments`**: jika Anda memulai Claude Code dengan [`--settings`](/docs/id/settings#change-a-setting-for-one-session), periksa apakah file atau JSON yang Anda berikan menetapkan salah satu kunci tersebut. Jika ya, ubah nilainya di sana, atau mulai Claude Code lagi tanpa kunci-kunci tersebut.

1072* **`Enterprise managed settings`**: pengaturan terkelola organisasi Anda dimuat. Jika pengaturan tersebut menetapkan salah satu kunci tersebut, Anda tidak dapat mengubah kunci itu dari `/sandbox` atau dari file pengaturan apa pun yang Anda kendalikan, jadi tanyakan kepada administrator Anda.

765 1073

766<h2 id="limitations">1074<h2 id="limitations">

767 Keterbatasan1075 Keterbatasan

781 1089

782* **Eskalasi privilege melalui soket Unix**: konfigurasi `allowUnixSockets` dapat secara tidak sengaja memberikan akses ke layanan sistem yang dapat menyebabkan bypass sandbox. Misalnya, mengizinkan akses ke `/var/run/docker.sock` secara efektif memberikan akses ke sistem host melalui soket Docker. Pertimbangkan dengan hati-hati soket Unix apa pun yang Anda izinkan melalui sandbox.1090* **Eskalasi privilege melalui soket Unix**: konfigurasi `allowUnixSockets` dapat secara tidak sengaja memberikan akses ke layanan sistem yang dapat menyebabkan bypass sandbox. Misalnya, mengizinkan akses ke `/var/run/docker.sock` secara efektif memberikan akses ke sistem host melalui soket Docker. Pertimbangkan dengan hati-hati soket Unix apa pun yang Anda izinkan melalui sandbox.

783* **Eskalasi izin filesystem**: izin penulisan filesystem yang terlalu luas dapat memungkinkan serangan eskalasi privilege. Mengizinkan penulisan ke direktori yang berisi executable dalam `$PATH`, direktori konfigurasi sistem, atau file konfigurasi shell pengguna seperti `.bashrc` atau `.zshrc` dapat menyebabkan eksekusi kode dalam konteks keamanan yang berbeda ketika pengguna lain atau proses sistem mengakses file ini.1091* **Eskalasi izin filesystem**: izin penulisan filesystem yang terlalu luas dapat memungkinkan serangan eskalasi privilege. Mengizinkan penulisan ke direktori yang berisi executable dalam `$PATH`, direktori konfigurasi sistem, atau file konfigurasi shell pengguna seperti `.bashrc` atau `.zshrc` dapat menyebabkan eksekusi kode dalam konteks keamanan yang berbeda ketika pengguna lain atau proses sistem mengakses file ini.

784* **Kekuatan sandbox Linux**: implementasi Linux menyediakan isolasi filesystem dan jaringan yang kuat tetapi mencakup mode `enableWeakerNestedSandbox` yang memungkinkannya bekerja di dalam lingkungan Docker tanpa namespace istimewa, atau pada host Linux di mana user namespaces tanpa privilege dinonaktifkan oleh sysctl. Opsi ini secara konsiderabel melemahkan keamanan dan hanya boleh digunakan ketika isolasi tambahan sebaliknya diberlakukan.1092* **Kekuatan sandbox Linux**: implementasi Linux menyediakan isolasi filesystem dan jaringan yang kuat tetapi mencakup mode `enableWeakerNestedSandbox` yang memungkinkannya bekerja di dalam lingkungan Docker tanpa namespace istimewa. Opsi ini secara konsiderabel melemahkan keamanan dan hanya boleh digunakan ketika isolasi tambahan sebaliknya diberlakukan.

785* **Apple Events pada macOS**: sandbox macOS memblokir Apple Events secara default. Pengaturan `allowAppleEvents` menghapus pembatasan ini sehingga alat seperti `open` dan `osascript` berfungsi, tetapi menghilangkan isolasi eksekusi kode: perintah sandboxed dapat meluncurkan aplikasi lain tanpa sandbox tanpa prompt pengguna, dan dapat mengirim perintah AppleScript ke aplikasi yang sedang berjalan, tunduk pada prompt persetujuan otomasi macOS per-aplikasi (TCC). Ini hanya dihormati dari pengaturan pengguna, terkelola, atau CLI. Pengaturan proyek tidak dapat mengaktifkannya.1093* **Apple Events pada macOS**: sandbox macOS memblokir Apple Events secara default. Pengaturan `allowAppleEvents` menghapus pembatasan ini sehingga alat seperti `open` dan `osascript` berfungsi, tetapi menghilangkan isolasi eksekusi kode: perintah sandboxed dapat meluncurkan aplikasi lain tanpa sandbox tanpa prompt pengguna, dan dapat mengirim perintah AppleScript ke aplikasi yang sedang berjalan, tunduk pada prompt persetujuan otomasi macOS per-aplikasi (TCC). Ini hanya dihormati dari pengaturan pengguna, terkelola, atau CLI. Pengaturan proyek tidak dapat mengaktifkannya.

786 1094

787<h3 id="platform-and-tool-compatibility">

788 Kompatibilitas platform dan alat

789</h3>

~~790~~

791* **Dukungan platform**: mendukung macOS, Linux, dan WSL2. WSL1 dan Windows asli tidak didukung.

792* **Overhead kinerja**: minimal, tetapi beberapa operasi filesystem mungkin sedikit lebih lambat.

793* **Kompatibilitas alat**: beberapa alat yang memerlukan pola akses sistem tertentu mungkin memerlukan penyesuaian konfigurasi, atau mungkin perlu dijalankan di luar sandbox.

~~794~~

795<h3 id="scope">1095<h3 id="scope">

796 Cakupan1096 Cakupan

797</h3>1097</h3>

798 1098

799Sandbox mengisolasi subprocess Bash. Alat lain beroperasi di bawah batas yang berbeda:1099Sandbox mengisolasi perintah shell dan proses turunannya. [Apa yang berjalan di luar sandbox](#what-runs-outside-the-sandbox) mencantumkan tool dan proses pembantu yang tidak dicakupnya. Penggunaan komputer dan subagent berkaitan dengan sandbox sebagai berikut:

800 1100

801* **Alat file bawaan**: Read, Edit, dan Write menggunakan sistem izin secara langsung daripada berjalan melalui sandbox. Lihat [permissions](/docs/id/permissions).

802* **Penggunaan komputer**: ketika Claude membuka aplikasi dan mengontrol layar Anda, itu berjalan di desktop aktual Anda daripada di lingkungan terisolasi. Prompt izin per-aplikasi membatasi setiap aplikasi. Lihat [computer use in the CLI](/docs/id/computer-use) atau [computer use in Desktop](/docs/id/desktop#let-claude-use-your-computer).1101* **Penggunaan komputer**: ketika Claude membuka aplikasi dan mengontrol layar Anda, itu berjalan di desktop aktual Anda daripada di lingkungan terisolasi. Prompt izin per-aplikasi membatasi setiap aplikasi. Lihat [computer use in the CLI](/docs/id/computer-use) atau [computer use in Desktop](/docs/id/desktop#let-claude-use-your-computer).

803* **Variabel lingkungan**: perintah Bash sandboxed mewarisi lingkungan proses induk secara default, termasuk kredensial apa pun yang ditetapkan di sana. Gunakan [`sandbox.credentials`](#protect-credentials) untuk menghapus atau menutupi variabel tertentu untuk perintah sandboxed, atau atur [`CLAUDE_CODE_SUBPROCESS_ENV_SCRUB`](/docs/id/env-vars) untuk menghapus kredensial dari semua subprocess.

804* **Subagents**: [subagents](/docs/id/sub-agents) berjalan dalam proses yang sama dengan sesi induk dan menggunakan konfigurasi sandbox yang sama. Perintah Bash di dalam subagent di-sandbox ketika sandboxing diaktifkan dalam sesi induk.1102* **Subagents**: [subagents](/docs/id/sub-agents) berjalan dalam proses yang sama dengan sesi induk dan menggunakan konfigurasi sandbox yang sama. Perintah Bash di dalam subagent di-sandbox ketika sandboxing diaktifkan dalam sesi induk.

1103* **Mods**: [mod](/docs/id/plugins/mods/overview) adalah plugin yang menjalankan kodenya sendiri di dalam Claude Code, dan proses yang dimulai oleh mod berjalan di luar sandbox. Lihat [Apa yang dapat dijangkau mod](/docs/id/plugins/mods/overview#what-a-mod-can-reach).

805 1104

806<Warning>1105<Warning>

807 Sandboxing yang efektif memerlukan isolasi filesystem dan jaringan. Tanpa isolasi jaringan, agen yang dikompromikan dapat mengeksfiltrasikan file sensitif seperti kunci SSH. Tanpa isolasi filesystem, baik dari kebijakan yang permisif atau dari [menonaktifkan lapisan filesystem](#disable-filesystem-isolation), agen yang dikompromikan dapat memasang pintu belakang pada sumber daya sistem untuk mendapatkan akses jaringan. Ketika Anda memperluas default, periksa bahwa jalur `allowWrite`, entri `allowedDomains` yang luas, atau pengecualian `excludedCommands` tidak membatalkan pembatasan di sisi lain.1106 Sandboxing yang efektif memerlukan isolasi filesystem dan jaringan. Tanpa isolasi jaringan, agent yang dikompromikan dapat mengeksfiltrasikan file sensitif seperti kunci SSH. Tanpa isolasi filesystem, baik dari kebijakan yang permisif atau dari [menonaktifkan lapisan filesystem](#disable-filesystem-isolation), agent yang dikompromikan dapat memasang pintu belakang pada sumber daya sistem untuk mendapatkan akses jaringan. Ketika Anda memperluas default, periksa bahwa jalur `allowWrite`, entri `allowedDomains` yang luas, atau pengecualian `excludedCommands` tidak membatalkan pembatasan di sisi lain.

808</Warning>1107</Warning>

809 1108

810<h2 id="see-also">1109<h2 id="see-also">

sandboxing.md 2026-10-01 23:59 UTC to 2026-10-02 13:00 UTC

Konfigurasikan tool Bash dengan sandbox

Apa yang dibatasi oleh sandbox

Apa yang berjalan di luar sandbox

Memulai

Jalankan /sandbox

Pilih mode

Jalankan perintah Bash

Memastikan perintah berjalan di dalam sandbox

Menyiapkan Linux dan WSL2

Mode sandbox

Mode auto-allow

Mode regular permissions

Jalan keluar retry tanpa sandbox

Matikan retry dengan strict sandbox mode

Direktori sementara

Mengonfigurasi sandboxing

Menjalankan perintah di luar sandbox dengan `excludedCommands`

Menonaktifkan isolasi filesystem

Pengaturan mana yang dapat menonaktifkannya

Apa yang berubah saat isolasi filesystem dimatikan

Melindungi kredensial

Melakukan mask kredensial

Melakukan mask environment variable

Menandatangani ulang permintaan AWS

Melakukan mask file kredensial

Cara kerja sandboxing

Isolasi sistem file

Jalur yang dilindungi

Isolasi jaringan

Host di luar domain yang diizinkan

Hostname yang di-resolve ke alamat lokal

Domain yang diizinkan per perintah dalam auto mode

Alamat IPv6 dalam daftar domain

Penerapan tingkat OS

Bagaimana sandboxing berhubungan dengan izin dan mode izin

Aturan izin

Mode izin

Konfigurasi sandbox untuk organisasi Anda

Memberlakukan sandboxing dengan pengaturan terkelola

Cegah pengembang memperluas kebijakan

Pengaturan repositori di bawah sandbox yang diwajibkan admin

Penguncian yang berlaku tanpa sandbox yang diwajibkan admin

Konfigurasi proxy khusus

Pemecahan masalah

Perintah gagal dengan kesalahan host-not-allowed

`jest` hang atau gagal

Go-based CLIs gagal verifikasi TLS di macOS

`open`, `osascript`, atau alur autentikasi berbasis browser gagal dengan kesalahan `-600` di macOS

Perintah `docker` gagal

`pbcopy`, `xclip`, atau `wl-copy` tidak memperbarui clipboard

Perintah git gagal dengan `unable to unlink old`

Bubblewrap gagal memulai di dalam container

File read-only 0-byte muncul di jalur pengaturan `.claude`, dan "Ya, dan jangan tanya lagi" tidak menyimpan

`git` melalui SSH gagal saat sandbox aktif

Klien database atau tool non-HTTP lainnya gagal menjangkau host yang diizinkan

Perintah gagal menjangkau server di localhost

Hostname yang diizinkan ditolak dengan `resolved to a loopback address`

`/sandbox` gagal dengan `Sandbox settings are overridden by a higher-priority configuration`

Keterbatasan

Keterbatasan keamanan

Cakupan

Lihat juga