Konfigurasi kebijakan sandbox

Apakah sebuah run agen di-sandbox ditentukan di server, saat boot (--sandbox). Tombol Aktifkan sandboxing dan pemilih Backend di bawah Pengaturan → Server → Diagnostik & privasi adalah preferensi yang disimpan di perangkat Anda. Deteksi host pada kartu Sandboxing melaporkan apa yang dapat dibungkus oleh host server.

Dua kontrol menjangkau sebuah run dan panduan ini membahas keduanya: aturan aksi di Pengaturan → Ruang kerja → Izin agen, yang menentukan apa yang boleh di-push, dibuka, atau dijangkau agen, dan flag --sandbox milik server sendiri.

Apa yang membatasi sebuah run agen

Seorang agen dibatasi oleh enam hal. Yang pertama adalah sandbox OS dan itulah yang bersyarat — lima sisanya berlaku di setiap host.

Batas	Apa yang dilakukannya
Sandbox OS	Seatbelt di macOS, bubblewrap di Linux dan WSL2. Membungkus Claude Code CLI, adapter ACP, dan alat `bash` harness. Tidak ada di Windows dan di Linux tanpa `bwrap` dan `socat`
Worktree-nya sendiri	Setiap percakapan mendapat checkout copy-on-write. Checkout asli dilipat ke dalam run sebagai jalur tolak-tulis dan sandbox-lah yang menegakkannya
Kredensial yang dijembatani	Broker kredensial membuat lingkungan per-run dan mencabutnya saat pembongkaran. Token GitHub di dalamnya dapat membaca tetapi tidak dapat push: push melewati Control Center, yang lebih dulu menanyakan aturan push
Pagar pengaman tindakan	Setiap alat yang memutasi mendeklarasikan kelas efeknya dan pagar menyelesaikannya sebelum panggilan berjalan. Sebuah `prompt` tanpa penyetuju yang terhubung ditolak
Sanitasi lingkungan	ACP dan alat `bash` harness mendapat lingkungan yang difilter. Claude Code melalui `NoSandboxAdapter` mewarisi lingkungan host
Permukaan alat mode	Mode hanya-baca menghapus alat yang memutasi worktree mentah-mentah dan menyematkan verb keluaran mode itu sendiri agar tetap dapat menyerahkan hasil

Tiga hal tetap lebih lemah daripada tampilannya:

Hanya harness bawaan yang menegakkan gerbang alat, kontrak penyelesaian, dan aturan mode yang struktural. Adapter Claude Code tidak. Khususnya Claude Code diluncurkan dengan --dangerously-skip-permissions, karena claude -p yang non-interaktif akan tersendat selamanya pada prompt-nya sendiri — sehingga panggilan read, write, dan edit milik Claude tidak terlihat maupun dijaga oleh Control Center, dan perintah bash-nya hanya diperiksa oleh hook yang membaca baris perintah. Di tempat sandbox menyala, sandbox itulah batas di sekelilingnya.
Alat berkas dalam proses milik harness (read, write, edit, apply patch, search, find, search_files) berjalan di dalam proses server, jadi tidak ada profil sandbox yang membatasinya. Hanya alat bash yang melewati runner perintah yang di-sandbox. Alat-alat itu dibatasi oleh pembatasan jalur miliknya sendiri plus pagar pengaman tindakan.
Di host tanpa backend, baris pertama sama sekali tidak berlaku. ACP dan alat bash harness kembali ke sanitasi lingkungan plus kebijakan perintah; Claude Code mewarisi lingkungan host melalui NoSandboxAdapter. Server mengatakannya di log startup-nya. Periksa milik Anda di bawah.

Tentukan apa yang boleh di-push agen

Tidak ada tombol per agen untuk git push, GitHub, ticketing, atau jaringan. Masing-masing adalah aturan aksi:

Aturan	Default bawaan	Apa yang dicakupnya
Push ke remote	Tanyakan dulu	Setiap `git push` ke GitHub, adapter apa pun
Buka pull request	Tanyakan dulu	`gh pr create` dan alat pull request
Publikasikan review atau merge	Tanyakan dulu	`gh pr merge`, `gh pr review`, `gh pr comment`, `gh pr close`
Tulis ke pelacak eksternal	Tanyakan dulu	Penulisan tiket melalui alat Control Center dan `gh issue`
Akses jaringan	Izinkan	Apakah sandbox punya jaringan sama sekali, dan alat web milik harness

Buka Pengaturan → Ruang kerja → Izin agen
Pilih cakupan — Ruang kerja, Agen, atau Space — lalu pada baris aturan, pilih Izinkan, Tanyakan dulu, atau Tolak

Aturan push yang dibatasi ke branch, seperti aturan yang menolak push ke main, juga berlaku: lihat Pagar pengaman.

Titik periksa: minta agen melakukan push sebuah branch. Dengan Tanyakan dulu Anda mendapat persetujuan yang menyebutkan repo dan ref-nya; dengan Tolak, git mencetak ! [remote rejected] <ref> (Control Center policy: …).

Bagaimana setiap aturan menjangkau run:

Push ditegakkan lewat apa yang dipegang run. Token GitHub-nya adalah token instalasi GitHub App hanya-baca yang dapat membaca konten dan bekerja dengan pull request. Konfigurasi git-nya mengirim setiap push GitHub ke gateway loopback di cc_server, yang menanyakan aturan dan baru kemudian meneruskan push dengan token tulis yang tidak pernah dilihat agen. Gateway hanya meneruskan ke repo milik worktree itu sendiri atau ke repo GitHub yang ditautkan ke ruang kerja. Ini berlaku untuk setiap adapter.
Pull request dan issue dari shell dikenali dari baris perintah, di alat bash milik harness dan, melalui hook, di alat Bash milik Claude Code. Agen yang menyembunyikan perintahnya (skrip, eval, panggilan API langsung) lolos dari pemeriksaan ini, tetapi tidak dari gateway push.
Kunci ticketing tidak pernah ditaruh di sandbox. Agen menulis tiket melalui alat MCP Control Center, yang menanyakan aturan.
Jaringan diselesaikan sekali, saat run dimulai. Tolak mematikan jaringan sandbox; Izinkan dan Tanyakan dulu membiarkannya menyala, dan dengan Tanyakan dulu alat web_fetch dan web_search milik harness tetap bertanya di setiap panggilan. Selama jaringan menyala, GitHub selalu ada di daftar izin egress.

Periksa apakah run agen Anda di-sandbox

Dua hal yang menentukannya, keduanya di server: apakah host menyediakan backend dan apakah --sandbox menyala. Periksa keduanya dalam urutan itu.

Buka Pengaturan → Server → Diagnostik & privasi
Baca kartu Sandboxing. Fakta Host adalah mesin tempat cc_server berjalan, bukan mesin yang sedang Anda lihat. Kolom Backend mencantumkan Sandbox native (Seatbelt di macOS, bubblewrap di Linux dan WSL2) atau Tanpa isolasi. Fakta Berlaku adalah preferensi perangkat ini, bukan pembungkus yang sebenarnya digunakan server.
Baca log startup server. Log itu mencetak tepat salah satu dari tiga baris:
- agent sandbox ON plus catatan backend — run dibungkus
- no OS-native agent sandbox on this host plus petunjuk pemasangan bila ada — run tidak dibungkus
- agent sandbox DISABLED by --sandbox off — pengabaian yang disengaja

GET /healthz tidak melaporkan status sandbox, jadi log startup-lah pemeriksaannya.

Untuk mematikan sandbox secara sengaja — host tempat profil berperilaku salah adalah alasan fitur ini ada — jalankan server dengan --sandbox off, atau setel CC_SERVER_SANDBOX=off. Default-nya on dan on berarti “gunakan backend bila host memilikinya”, tidak pernah “wajibkan satu”.

Dua situasi tidak pernah mendapat pembungkus sandbox native. Di Windows, probe native selalu melaporkan tidak tersedia dan tidak ada yang perlu dipasang — pengiriman agen memakai none. Backend microvm terpisah (terminal interaktif dan rig) dan digerbangi probe pada runtime-nya sendiri. Di Linux dan WSL2, baik bwrap maupun socat harus ada di PATH; tanpa keduanya, probe melaporkan tidak tersedia dan menyebutkan paket yang hilang.

Di Linux/WSL2 dengan bubblewrap terpasang, glob berkas rahasia milik kebijakan standar tidak dapat ditegakkan untuk berkas yang dibuat agen belakangan. Run native semacam itu sekarang gagal alih-alih diam-diam mengabaikan aturannya. Probe boot yang positif karena itu tidak menjamin bahwa pengiriman di Linux dapat dimulai. --sandbox off adalah pengabaian tanpa kurungan yang disengaja, bukan pengganti batas keamanan.

Ketahui apa yang sudah dilarang oleh sebuah mode

Mode disimpan per space dan menjadi masukan bagi penyelesai pagar pengaman sebagai lapisan preset mode. Tiga dari empat mode bersifat hanya-baca dan mode hanya-baca menolak sebelas kelas efek mentah-mentah:

Mode	Worktree	Ditolak oleh prasetel
Agen (`chat`)	Dapat ditulisi	Tidak ada — default bawaan yang berlaku
Rencana	Hanya-baca	Hapus file, tulis di luar pohon kerja, buat commit, push ke remote, buka pull request, publikasikan review atau merge, tulis ke pelacak eksternal, instal paket, jalankan proses, ubah struktur ruang kerja, boot atau kendalikan enclosure (rig)
Tinjauan	Hanya-baca	Sebelas hal yang sama. Tidak dapat dipilih pengguna — penyusun pesan hanya menawarkan Agen, Rencana, dan Orkestrasi
Orkestrasi	Hanya-baca	Sebelas hal yang sama

Akses jaringan dan akses secret sengaja tidak ditolak oleh mode hanya-baca: penelitian adalah inti dari mode itu.

Wajibkan persetujuan sebelum sebuah tindakan berjalan

Persetujuan adalah keputusan pagar pengaman, bukan pengaturan sandbox.

Buka Pengaturan → Ruang kerja → Izin agen
Setel kelas tindakan ke Tanyakan dulu pada cakupan ruang kerja, agen, atau space

Keputusan Tanyakan dulu menginterupsi run dan menanyakan kepada Anda. Tanpa penyetuju yang terhubung, keputusan ini fail-closed dan tindakannya ditolak. Lihat Konfigurasi pagar pengaman untuk urutan penyelesaian selengkapnya.

Pemecahan masalah

Agen tidak dapat push dan saya tidak pernah menolaknya

Baca apa yang dicetak git. Control Center policy: … berarti sebuah aturan menolak push atau Tanyakan dulu tidak dijawab. … is not linked to this workspace berarti push menuju repo yang bukan repo milik worktree dan tidak ditautkan ke ruang kerja. Control Center has no GitHub credential that can push … berarti GitHub App tidak terpasang di repo itu dan tidak ada kredensial fallback yang dapat push: pasang App di repo tersebut atau hubungkan GitHub.

Kartu Sandboxing melaporkan tidak ada sandbox native

Berarti run agen di host itu tidak dibungkus oleh Seatbelt atau bubblewrap dan batas-batas yang tersisa itulah yang Anda miliki. Di Linux dan WSL2, pasang kedua alat yang hilang — sudo apt-get install bubblewrap socat — lalu jalankan ulang server; log startup selanjutnya akan menyebutkan sandbox menyala. Di Windows tidak ada backend native untuk dipasang, jadi perketat pagar pengamannya sebagai gantinya: lihat Konfigurasi pagar pengaman.

Agen menjangkau berkas di luar worktree-nya

Alat mana yang menjangkaunya menentukan apakah ini wajar.

Alat berkas dalam proses milik harness (read, write, edit, apply patch, search, find, search_files) berjalan di dalam proses server, jadi tidak ada profil sandbox yang berlaku untuknya — batasnya adalah pembatasan jalur miliknya sendiri plus pagar pengaman. Perintah bash atau CLI Claude Code memang dibungkus di tempat backend ada dan checkout terdaftar Anda bersifat tolak-tulis di dalam pembungkus itu pada setiap mode, termasuk ejaan yang telah diselesaikan symlink-nya (di macOS jalur yang dicapai melalui /tmp atau /var/folders diselesaikan di bawah /private dan kedua ejaan itu kini ditolak). Di host tanpa backend, tidak satu pun dari itu berlaku. Apa pun caranya, pagar pengaman dapat menolak Tulis di luar pohon kerja mentah-mentah.