Lewati ke konten

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.

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, 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, 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 alat bash harness kembali ke sanitasi lingkungan plus kebijakan perintah, dan Claude Code mewarisi lingkungan host melalui NoSandboxAdapter. Server menyebutkan kasus mana yang berlaku di log startup-nya. Periksa milik Anda di bawah.

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
  1. Buka Pengaturan → Ruang kerja → Izin agen
  2. 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 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.

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

  1. Buka Pengaturan → Server → Diagnostik & privasi
  2. 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.
  3. 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 : hanya run yang dipertanggungjawabkan kepada pemilik server yang dimulai, tanpa dibungkus, dan run orang lain ditolak
    • agent sandbox DISABLED by --sandbox off: run setiap anggota dimulai tanpa dibungkus
  4. Baris exposure yang dicetak saat startup mengatakan hal yang sama dalam satu kata: sandbox=native, sandbox=off atau sandbox=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.

  1. Buka Pengaturan → Ruang kerja → Izin agen
  2. 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.

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.

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.