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
Bagian berjudul “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, tempat hanya run milik pemilik server yang dimulai |
| 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 melepaskannya 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, karenaclaude -pyang 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
bashyang melewati runner perintah yang di-sandbox. Alat-alat itu dibatasi oleh pembatasan jalur miliknya sendiri plus pagar pengaman tindakan. - Di host tanpa backend, hanya run yang dipertanggungjawabkan kepada pemilik server yang dimulai, dan untuk run tersebut baris pertama sama sekali tidak berlaku. Run milik orang lain ditolak. Di bawah
--sandbox off, setiap run anggota dimulai tanpa baris pertama. Dalam kedua kasus, ACP dan alatbashharness kembali ke sanitasi lingkungan plus kebijakan perintah, dan Claude Code mewarisi lingkungan host melaluiNoSandboxAdapter. Server menyebutkan kasus mana yang berlaku di log startup-nya. Periksa milik Anda di bawah.
Tentukan apa yang boleh di-push agen
Bagian berjudul “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 | Alat pull request Control Center. gh pr create tidak berfungsi dalam run |
| Perbarui atau gabungkan pull request | Tanyakan dulu | Komentar agen pada pull request-nya, perubahan judul atau deskripsinya, dan review yang dipublikasikan, melalui alat Control Center. gh pr comment, gh pr edit, gh pr review, gh pr merge, dan gh pr close tidak berfungsi dalam run |
| 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 hanya mencakup satu
repositori run dan tidak dapat push: ia dapat membaca konten dan, ketika anggota yang
bertanggung jawab dapat push, berkomentar di 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
bashmilik harness dan, melalui hook, di alatBashmilik 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_fetchdanweb_searchmilik harness tetap bertanya di setiap panggilan. Selama jaringan menyala, GitHub selalu ada di daftar izin egress.
Periksa apakah run agen Anda di-sandbox
Bagian berjudul “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_serverberjalan, 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 ONplus catatan backend: run dibungkusno OS-native agent sandbox on this hostplus petunjuk pemasangan bila ada : hanya run yang dipertanggungjawabkan kepada pemilik server yang dimulai, tanpa dibungkus, dan run orang lain ditolakagent sandbox DISABLED by --sandbox off: run setiap anggota dimulai tanpa dibungkus
- Baris exposure yang dicetak saat startup mengatakan hal yang sama dalam satu kata:
sandbox=native,sandbox=offatausandbox=unavailable.
GET /healthz tidak melaporkan status sandbox, jadi log startup-lah
pemeriksaannya.
Hanya pemilik server yang memutuskan menjalankan tanpa sandbox. Untuk melakukannya
bagi semua orang, jalankan server dengan --sandbox off, atau setel
CC_SERVER_SANDBOX=off. Agen setiap anggota lalu berjalan tanpa kurungan di mesin
itu, jadi ini keputusan tentang semua orang yang memakai server, dibuat sekali saat
boot. Default-nya on: ia membungkus setiap run bila host memiliki backend dan,
bila tidak, hanya memulai run milik pemilik.
Dua situasi tidak pernah mendapat pembungkus sandbox native. Di Windows,
probe native selalu melaporkan tidak tersedia dan tidak ada yang perlu dipasang,
sehingga hanya run milik pemilik server yang dimulai kecuali pemilik memberi
--sandbox off. 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, dan hanya run milik pemilik yang
dimulai.
Di Linux/WSL2 dengan bubblewrap terpasang, glob berkas rahasia milik kebijakan
standar tidak dapat ditegakkan untuk berkas yang dibuat agen belakangan, sehingga
setiap run native gagal alih-alih diam-diam mengabaikan aturannya, termasuk milik
pemilik. Probe boot yang positif karena itu tidak berarti dispatch Linux dapat
dimulai: saat ini server Linux menjalankan agen dengan --sandbox off, atau tanpa
bubblewrap hanya untuk pemilik. --sandbox off adalah pengabaian tanpa kurungan
yang disengaja, bukan pengganti batas keamanan.
Ketahui apa yang sudah dilarang oleh sebuah mode
Bagian berjudul “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 dua belas 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), jalankan perintah di host |
| Tinjauan | Hanya-baca | Dua belas hal yang sama. Tidak dapat dipilih pengguna — penyusun pesan hanya menawarkan Agen, Rencana, dan Orkestrasi |
| Orkestrasi | Hanya-baca | Dua belas 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
Bagian berjudul “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
Bagian berjudul “Pemecahan masalah”Agen tidak dapat push dan saya tidak pernah menolaknya
Bagian berjudul “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 tidak ada token push yang dapat dibuat: pasang GitHub App di repo itu atau hubungkan GitHub.
Run agen saya ditolak dengan “Server ini tidak memiliki sandbox”
Bagian berjudul “Run agen saya ditolak dengan “Server ini tidak memiliki sandbox””Run menampilkan Agen memerlukan sandbox di server ini dengan “Server ini tidak memiliki sandbox, sehingga hanya pemiliknya yang dapat menjalankan agen di sini. Pemilik dapat memasang sandbox atau mematikan sandboxing untuk semua orang.” Host server tidak memiliki sandbox OS, dan orang yang bertanggung jawab atas run ini bukan pemilik server, sehingga tidak ada yang dimulai. Untuk jadwal, webhook, atau otomatisasi lain, orang yang bertanggung jawab adalah orang yang diikat otomatisasi itu, bukan siapa pun yang sedang melihatnya.
Hanya pemilik server yang dapat mengubah ini. Di Linux dan WSL2 mereka memasang
bubblewrap dan socat lalu memulai ulang server (tetapi baca dulu catatan Linux
di atas). Di Windows tidak ada backend untuk dipasang. Pilihan lainnya adalah
memulai ulang server dengan --sandbox off, yang menjalankan agen setiap anggota
tanpa kurungan di mesin itu.
Kartu Sandboxing melaporkan tidak ada sandbox native
Bagian berjudul “Kartu Sandboxing melaporkan tidak ada sandbox native”Berarti run agen di host itu tidak dibungkus oleh Seatbelt atau bubblewrap: hanya
run milik pemilik server yang dimulai, dan batas-batas yang tersisa itulah yang
mereka 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 untuk run milik pemilik sendiri
sebagai gantinya: lihat
Konfigurasi pagar pengaman.
Agen menjangkau berkas di luar worktree-nya
Bagian berjudul “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 ditolak). Di bawah
--sandbox off, atau untuk run milik pemilik sendiri di host tanpa backend, tidak
satu pun dari itu berlaku. Apa pun caranya, pagar pengaman dapat
menolak Tulis di luar pohon kerja mentah-mentah.
Panduan terkait
Bagian berjudul “Panduan terkait”- Konfigurasi pagar pengaman
- Buat dan konfigurasi agen
- Diagnosis agen
- Backend sandbox
- CLI cc_server: flag
--sandbox