Bahagian belakang kotak pasir

cc_server menyiasat hos sekali semasa permulaan dan membalut penghantaran ejen dalam bahagian belakang natif apabila siasatan melaporkan satu tersedia dan --sandbox bukan off. Kedua-dua sambungan penghantaran dibalut: CLI Claude Code melalui port kotak pasir, dan ACP serta alat bash harness terbina melalui pengurus kotak pasir.

Di mana siasatan melaporkan tiada bahagian belakang — Windows sentiasa dan Linux atau WSL2 tanpa bwrap dan socat — larian ejen tidak dikotak pasirkan. ACP dan alat bash harness masih dilancarkan dengan sanitasi persekitaran; Claude Code melalui NoSandboxAdapter dan mewarisi persekitaran hos. Sempadan yang tinggal ialah worktree larian itu sendiri (copy-on-write di mana rift disertakan; git worktree pada Windows), token hos kod baca sahaja yang diuruskan melalui broker setiap pelancaran dan ditarik balik semasa pembongkaran, push yang mesti melepasi peraturan push di gerbang larian ejen, polisi perintah mengikut modus, guardrail tindakan bersatu (gagal-tertutup), sanitasi persekitaran pada laluan ACP dan bash harness, serta permukaan alat yang dibenarkan oleh modusnya.

Alat fail dalam proses harness (read, write, edit, apply patch, search, find, search_files) berada di luar kotak pasir pada setiap hos: ia berjalan dalam proses pelayan, jadi hanya bash dibalut.

Gambaran keseluruhan bahagian belakang

Bahagian belakang	Nilai	Platform	Ketersediaan
VM terasing	`microvm`	macOS, Linux, Windows (microVM hypervisor)	Bersyarat siasatan pada masa jalan microVM; terpakai pada terminal interaktif — shell berjalan di dalam stesen, bukan pada hos
Natif	`native`	macOS (Seatbelt), Linux dan WSL2 (bubblewrap)	Disiasat semasa permulaan; Linux menolak larian yang memerlukan penolakan tulis glob nama fail, yang tidak dapat dikuatkuasakan bubblewrap
Tiada	`none`	Semua	Lalai penghuraian, lalai terminal dan patah balik apabila tiada bahagian belakang tersedia atau `--sandbox off` ditetapkan

SandboxBackend.fromName mengembalikan none untuk nilai tersimpan yang nol atau tidak dikenali. "docker" yang tersimpan dipetakan kepada native.

microvm ialah satu-satunya bahagian belakang dengan sempadan kernel — beban kerja itu benar-benar tidak berjalan pada hos. Ia tidak pernah menjadi patah balik senyap dalam mana-mana arah: memintanya secara eksplisit pada hos yang tidak boleh but VM gagal dengan lantang (“saya minta VM tetapi dapat komputer riba saya” ialah satu-satunya kemerosotan yang tidak mampu ditanggung oleh persekitaran terasing), dan hanya lalai yang tidak dinyatakan yang turun ke native, dengan baris log yang menyatakannya. Bahagian belakang sebenar sesi itu dilaporkan kembali kepada klien dan diberikan lencana, jadi sesuatu terminal tidak boleh sekali-kali mendakwa ia terasing sedangkan ia berjalan pada hos. Kitaran hayat, imej dan keluar bagi VM itu sendiri diliputi oleh rujukan stesen.

Windows tiada kotak pasir natif. NativeSandboxAdapter.probe mengembalikan available: false pada setiap hos yang bukan macOS atau Linux/WSL2. Oleh itu penghantaran ejen pada Windows menggunakan none. Bahagian belakang microvm adalah berasingan: ia bersyarat siasatan pada masa jalan microVM dan terpakai pada terminal interaktif serta stesen, bukan untuk membalut bash pada hos.

Keputusan siasatan

Siasatan itulah yang menentukan penguatkuasaan. Ia berjalan sekali, semasa permulaan pelayan.

Hos	`available`	Nota / petunjuk
macOS	`true`	`sandbox-exec` (Seatbelt) — pengasingan namespace, tiada sempadan kernel
Linux atau WSL2 dengan `bwrap` dan `socat`	`true`	bubblewrap — pengasingan namespace, tiada sempadan kernel
Linux atau WSL2 yang kekurangan salah satu alat	`false`	`requiresInstall: true`, dengan petunjuk pemasangan yang menamakan pakej yang hilang
Mana-mana platform lain	`false`	Kotak pasir natif tidak ditawarkan pada platform ini

Pelayan mencatat hasilnya pada satu baris permulaan: agent sandbox ON beserta nota, no OS-native agent sandbox on this host beserta petunjuk, atau agent sandbox DISABLED by --sandbox off. GET /healthz tidak membawa medan kotak pasir.

--sandbox / CC_SERVER_SANDBOX menerima on (lalai) atau off. Ia penarikan diri, bukan pengaktifan: on bermaksud “balut apabila hos menawarkan bahagian belakang”, bukan sekali-kali “wajibkan satu”.

Bahagian belakang natif

macOS: Seatbelt

Menggunakan mekanisme kotak pasir Seatbelt Apple (sistem yang sama digunakan oleh App Sandbox macOS).

Profil yang dijana permisif secara lalai ((allow default)) dan mengukir penolakan, kerana profil yang menolak secara lalai sepenuhnya menjadikan shell interaktif tidak boleh digunakan — terlalu banyak panggilan dyld, XPC dan Mach untuk disenaraikan. Akibat praktikalnya ialah ejen masih boleh membaca sebahagian besar hos; checkout berdaftar anda dilindungi oleh penolakan tulis dan penamaan semula yang eksplisit, bukan oleh ketaknampakan.

Bacaan sistem fail: ditolak untuk laluan rahsia (~/.ssh, ~/.aws, ~/.gnupg, ~/.config/gh, ~/Library/Keychains dan seluruh set tolak-baca yang lain)
Tulisan sistem fail: ditetapkan semula kepada tolak, kemudian benarkan sub-laluan yang eksplisit, dengan laluan wajib-tolak (fail rc shell, .git/hooks, konfigurasi Claude, checkout yang dilindungi) disekat walaupun di dalam akar yang boleh ditulis. file-write-unlink ditolak pada setiap laluan yang ditolak dan nenek moyangnya, jadi penamaan semula tidak dapat memintas penolakan tulis
Proses: penolakan process-exec untuk binari yang sentiasa berbahaya, serta sekatan ke atas pelaksanaan apa-apa daripada direktori yang boleh ditulis
Rangkaian: terhad kepada port proksi dalam proses serta DNS — loopback tidak dibenarkan secara menyeluruh dan soket Unix tidak dibenarkan. Proksi menguatkuasakan senarai benarkan domain bagi setiap sesi (lihat Keluar rangkaian)
Konfigurasi: profil dijana bagi setiap pelancaran daripada SandboxSpec

Keperluan:

sandbox-exec (/usr/bin/sandbox-exec), sebahagian daripada setiap pemasangan macOS — tiada alat tambahan diperlukan

Linux: bubblewrap

Menggunakan bubblewrap (bwrap) untuk mencipta namespace mount dan PID.

Sistem fail: mencipta namespace mount dengan hanya laluan yang diikat kelihatan
Rangkaian: berjalan dalam namespace rangkaian yang tidak dikongsi; trafik sampai ke proksi hos melalui jambatan soket Unix socat
Proses: pengasingan namespace PID

Keperluan:

bubblewrap dan socat dipasang (sudo apt-get install bubblewrap socat pada Debian/Ubuntu)
Sokongan namespace kernel (standard pada Linux moden)

Bubblewrap boleh menaungi laluan sedia ada tetapi tidak boleh melarang fail .env, *.key atau *.pem yang baharu di dalam bind yang boleh ditulis. Polisi penghantaran standard memerlukan penolakan glob nama fail ini, jadi penghantaran ejen natif kini gagal tertutup pada Linux/WSL2 walaupun siasatan menemui bubblewrap. Ia tidak berjalan dengan polisi yang lebih lemah secara senyap. Bahagian belakang dengan peraturan nama fail pada masa penciptaan diperlukan untuk memulihkan penghantaran natif Linux. Mematikan kotak pasir ialah penarikan diri tanpa kekangan yang eksplisit, bukan jalan pintas yang setara.

Bahagian belakang none

Tiada kotak pasir. Proses berjalan terus pada hos dengan akses sistem fail, rangkaian dan proses hos. ACP dan alat bash harness masih mendapat sanitasi persekitaran dan polisi perintah; Claude Code melalui NoSandboxAdapter mewarisi persekitaran hos. Inilah yang menjadi patah balik penghantaran ejen pada hos tanpa bahagian belakang tersedia atau dengan --sandbox off, dan ia ialah lalai terminal apabila klien tidak menamakan mana-mana satu.

Terminal yang dihoskan pelayan

Terminal dikotak pasirkan mengikut syaratnya sendiri, bukan oleh siasatan penghantaran. defaultBackend TerminalSessionService ialah none dan cc_server tidak mengatasinya, jadi sesi terminal menjalankan shell hos melainkan klien meminta native secara eksplisit — panel terminal desktop tidak berbuat demikian.

Apabila native diminta, shell dibalut melalui SandboxManager di bawah profil terminal tetap: $HOME dan direktori kerja sesi boleh ditulis, rangkaian terbuka dan ~/.ssh, ~/.aws, ~/.gnupg, ~/.config/gh serta ~/Library/Keychains ditolak bacaannya. Token hos kod baca sahaja dan gerbang push tidak terpakai — itu urusan penghantaran. Jika balutan tidak disokong, sesi itu gagal dan bukannya memaparkan lencana natif pada PTY shell hos.

Keluar rangkaian

Apabila kotak pasir dilancarkan, akses rangkaian keluar dikuatkuasakan oleh proksi dalam proses, bukan oleh peraturan firewall kernel. Pada hos tanpa bahagian belakang tersedia, tiada satu pun daripada ini terpakai dan proses yang dilancarkan mencapai rangkaian tepat seperti yang akan dilakukan oleh pengguna pelayan.

Masa jalan kotak pasir menjalankan proksi HTTP/HTTPS dan proksi SOCKS5 pada 127.0.0.1 di dalam proses cc_server, satu pasangan bagi setiap sesi terhad (http_proxy.dart, socks_proxy.dart). Larian serentak tidak berkongsi pasangan.
Proses berkotak pasir menerima pemboleh ubah persekitaran proksi (HTTP_PROXY/HTTPS_PROXY → proksi HTTP, ALL_PROXY → proksi SOCKS; GIT_SSH_COMMAND menghalakan git-melalui-SSH melalui proksi SOCKS). Pada Linux namespace rangkaian tidak dikongsi, jadi proksi ialah satu-satunya jalan keluar; pada macOS kotak pasir berkongsi loopback hos dan bercakap terus dengannya.
Hos sasaran setiap sambungan dipadankan dengan senarai benarkan domain sesi itu; apa-apa selainnya ditolak. Dua bentuk kad liar, setiap satu dengan tepat satu *: *.example.com di hadapan memadankan mana-mana subdomain (termasuk a.b.example.com) tetapi bukan puncak domain itu sendiri; bedrock.*.amazonaws.com dengan label tengah memadankan tepat satu label (bedrock.us-east-1.amazonaws.com, bukan bedrock.evil.attacker.amazonaws.com).
Senarai benarkan itu diselesaikan bagi setiap sesi daripada dasar asas yang dikurasi (kBaselineAllowedDomains: penyedia LLM, hos Git, daftar pakej), serta domain GitHub (kGithubDomains), serta SandboxSpec.egressAllowlist. Laluan penghantaran tidak pernah menghantar entri egressAllowlist tambahan, jadi dalam praktiknya setiap larian mendapat dasar asas serta GitHub.
Senarai tolak tetap (kBaselineDeniedDomains: titik akhir metadata awan, pengumpul telemetri) mengatasi semua kebenaran.
networkEnabled: false tetap memulakan proksi setiap sesi, tetapi senarai benarkannya kosong jadi setiap sambungan keluar ditolak. Penghantaran menetapkannya apabila larian bermula daripada peraturan Akses rangkaian: tolak mematikan rangkaian, benarkan dan tanya dahulu membiarkannya hidup.

SandboxSpec

Spesifikasi yang dihantar kepada SandboxPort.launch:

Medan	Jenis	Keterangan
`sessionId`	`String`	Pengecam sesi yang stabil (biasanya id ruang)
`workspaceId`	`String`	Id ruang kerja yang memilikinya
`agentId`	`String?`	Ejen yang sedang terikat pada kotak pasir, jika ada
`bindMounts`	`List<SandboxBindMount>`	Mount hos→tetamu; kotak pasir hanya melihat laluan hos yang disenaraikan di sini
`networkEnabled`	`bool` (lalai `true`)	Ditetapkan semasa penghantaran daripada peraturan keluar rangkaian (mati hanya apabila ia diselesaikan kepada tolak). Apabila dimatikan, proksi setiap sesi tetap bermula tetapi senarai benarkannya kosong jadi setiap sambungan keluar ditolak
`egressAllowlist`	`List<String>` (lalai `[]`)	Domain keluar tambahan yang dibenarkan; kad liar disokong (`*.example.com`, serta bentuk tengah satu label). Penghantaran tidak pernah mengisi ini, jadi larian yang dibalut mendapat dasar asas yang dikurasi serta domain GitHub
`guestWorkdir`	`String?`	Direktori kerja lalai di dalam kotak pasir; panggilan `exec` individu boleh mengatasinya
`mode`	`Mode` (lalai `chat`)	Mengukir peraturan tulis sistem fail: `chat` mengekalkan mount bind boleh ditulis; `review`, `plan` dan `orchestrate` adalah baca sahaja
`protectedPaths`	`List<String>` (lalai `[]`)	Laluan hos yang tidak boleh sama sekali ditulis di dalam kotak pasir, dalam mana-mana modus
`runnerStateDirs`	`List<String>` (lalai `[]`)	Direktori hos tempat pelari menyimpan keadaannya sendiri, boleh ditulis dalam setiap modus (`CLAUDE_CONFIG_DIR` yang diuruskan Control Center ialah yang semasa)
`execGrantRoots`	`List<String>` (lalai `[]`)	Pokok direktori yang diluluskan pengendali yang membuka semula sekatan exec direktori boleh tulis pada macOS. Linux mengabaikannya — bwrap tiada sekatan exec `$HOME` untuk dibuka semula

protectedPaths menyimpan checkout repo berdaftar yang asal, diselesaikan bagi setiap penghantaran daripada repo ruang kerja. Ejen bekerja secara eksklusif dalam worktree copy-on-write bagi setiap perbualan, jadi yang asal tidak boleh sama sekali boleh ditulis dari dalam kotak pasir — pada macOS, kebenaran tulis $HOME menyeluruh Seatbelt akan membiarkannya boleh ditulis melalui bash. Ia menyertai set tolak-tulis rahsia dalam setiap modus, termasuk chat.

Setiap laluan tolak-baca dan tolak-tulis dikeluarkan dalam kedua-dua ejaan literalnya dan ejaan yang diselesaikan symlink. Kernel memadankan peraturan penolakan terhadap laluan yang diselesaikan, jadi peraturan yang ditulis terhadap laluan bersymlink tidak pernah tercetus — dan pada macOS itu kes biasa dan bukan kes eksotik, kerana /tmp diselesaikan kepada /private/tmp dan /var/folders/… kepada /private/var/folders/…. Entri yang mengandungi * atau ? dianggap glob dan dibiarkan; laluan yang tidak diselesaikan dikekalkan seperti yang ditulis.

SandboxBindMount

Medan	Jenis	Keterangan
`hostPath`	`String`	Laluan mutlak pada hos
`guestPath`	`String`	Laluan di dalam kotak pasir (dengan kotak pasir natif ini sama dengan `hostPath`; dikekalkan untuk simetri penyesuai)
`readOnly`	`bool` (lalai `false`)	Mount sebagai baca sahaja apabila benar

SandboxHandle

Dikembalikan oleh SandboxPort.launch:

Medan	Jenis	Keterangan
`sessionId`	`String`	Pengecam sesi
`backend`	`SandboxBackend`	Bahagian belakang yang sedang berjalan
`state`	`SandboxState`	Keadaan kitaran hayat
`error`	`Object?`	Ditetapkan apabila `state` ialah `error`
`details`	`Map<String, Object?>`	Pembukuan peribadi penyesuai (direktori kerja, PID, laluan profil, dsb.)

SandboxState

Keadaan	Keterangan
`created`	Spec dicipta tetapi VM belum bermula
`warm`	Berjalan dan bersedia untuk exec perintah
`active`	Sedang melaksanakan perintah
`suspended`	Dijeda / checkpoint ke cakera untuk menjimatkan RAM
`destroyed`	Dibongkar; pemegang itu tidak lagi sah
`error`	Pelancaran gagal — lihat `SandboxHandle.error`

Peristiwa kotak pasir

Jenis peristiwa	Keterangan
`stdout`	Output standard daripada kotak pasir
`stderr`	Ralat standard daripada kotak pasir
`exit`	Proses kotak pasir keluar (membawa `exitCode`)
`starting`	Kotak pasir sedang bermula
`ready`	Kotak pasir bersedia menerima panggilan exec
`killed`	Proses dibunuh oleh hos (OOM, tamat masa, hentian manual)
`violation`	Satu polisi kotak pasir dilanggar (membawa `SandboxViolation`)

SandboxViolation

Medan	Jenis	Keterangan
`action`	`String`	Kata kerja yang ditolak (cth. `file-read*`, `network-outbound`)
`target`	`String`	Laluan atau hos yang menjadi sasaran operasi yang ditolak
`raw`	`String?`	Baris log mentah, berguna untuk nyahpepijat