Sandbox arka uçları

cc_server ana makineyi açılışta bir kez yoklar ve yoklama kullanılabilir bir arka uç bildirdiğinde ve --sandbox off olmadığında ajan gönderimini yerel arka uca sarar. Her iki gönderim ek noktası da sarılır: Claude Code CLI sandbox portu üzerinden, ACP ile yerleşik harness bash aracı ise sandbox yöneticisi üzerinden.

Yoklamanın bir arka uç bildirmediği yerlerde — her zaman Windows ve bwrap ile socat bulunmayan Linux ya da WSL2 — ajan çalıştırmaları sandbox’a alınmaz. ACP ve harness bash aracı yine de ortam arındırmasıyla başlatılır; Claude Code NoSandboxAdapter üzerinden gider ve ana makinenin ortamını devralır. Geriye kalan sınırlar şunlardır: çalıştırmanın kendi çalışma ağacı (riftin bulunduğu yerde copy-on-write; Windows’ta git worktree), başlatma başına broker’la verilip kapatmada iptal edilen salt okunur bir forge token’ı, ajan çalıştırma ağ geçidinde push kuralından geçmesi gereken push’lar, moda özgü komut politikası, birleşik eylem korumaları (başarısızlıkta kapalı), ACP ile harness bash yollarındaki ortam arındırması ve modun izin verdiği araç yüzeyi.

Harness’ın süreç içi dosya araçları (read, write, edit, apply patch, search, find, search_files) her ana makinede sandbox’ın dışındadır: sunucu sürecinde çalışırlar, dolayısıyla yalnızca bash sarılır.

Arka uçlara genel bakış

Arka uç	Değer	Platform	Kullanılabilirlik
Kapalı VM	`microvm`	macOS, Linux, Windows (microVM hipervizörü)	microVM çalışma zamanındaki yoklamaya bağlıdır; etkileşimli terminaller için geçerlidir — kabuk ana makinede değil, bir rig içinde çalışır
Yerel	`native`	macOS (Seatbelt), Linux ve WSL2 (bubblewrap)	Açılışta yoklanır; Linux, bubblewrap’in uygulayamadığı dosya adı glob’uyla yazma retlerini gerektiren bir çalıştırmayı reddeder
Yalıtım yok	`none`	Tümü	Ayrıştırma varsayılanı, terminalin varsayılanı ve kullanılabilir bir arka uç olmadığında ya da `--sandbox off` ayarlandığında geri düşülen değer

SandboxBackend.fromName, null ya da tanınmayan bir saklı değer için none döndürür. Saklı bir "docker" değeri native ile eşlenir.

microvm, çekirdek sınırı olan tek arka uçtur — iş yükü gerçekten ana makinede çalışmaz. Hiçbir yönde sessiz bir geri düşüş değildir: bir VM başlatamayan bir ana makinede açıkça istendiğinde yüksek sesle başarısız olur (“VM istedim ve dizüstü bilgisayarımı aldım”, kapalı ortamın göze alamayacağı tek bozulmadır) ve yalnızca belirtilmemiş bir varsayılan nativee iner; günlüğe de bunu söyleyen bir satır düşer. Oturumun gerçek arka ucu istemciye bildirilir ve rozetle gösterilir, böylece bir terminal ana makinede çalışırken asla kapalı olduğunu iddia edemez. VM’nin kendi yaşam döngüsü, imajları ve çıkışı rig’ler referansında ele alınır.

Windows’ta yerel sandbox yoktur. NativeSandboxAdapter.probe, macOS ya da Linux/WSL2 olmayan her ana makinede available: false döndürür. Bu nedenle Windows’ta ajan gönderimi none kullanır. microvm arka ucu ayrıdır: microVM çalışma zamanındaki yoklamaya bağlıdır ve ana makinede bash sarmak için değil, etkileşimli terminaller ile rig’ler için geçerlidir.

Yoklama sonuçları

Kapılamayı yapan şey yoklamadır. Bir kez, sunucu açılışında çalışır.

Ana makine	`available`	Not / ipucu
macOS	`true`	`sandbox-exec` (Seatbelt) — ad alanı yalıtımı, çekirdek sınırı yok
`bwrap` ve `socat` bulunan Linux ya da WSL2	`true`	bubblewrap — ad alanı yalıtımı, çekirdek sınırı yok
Linux ya da WSL2 ve iki araçtan biri eksik	`false`	`requiresInstall: true`, eksik paketleri adlandıran bir kurulum ipucuyla
Diğer tüm platformlar	`false`	Yerel sandbox bu platformda sunulmaz

Sunucu sonucu tek bir başlangıç satırına yazar: agent sandbox ON artı not, no OS-native agent sandbox on this host artı ipucu ya da agent sandbox DISABLED by --sandbox off. GET /healthz bir sandbox alanı taşımaz.

--sandbox / CC_SERVER_SANDBOX, on (varsayılan) ya da off kabul eder. Bu bir devre dışı bırakma seçeneğidir, etkinleştirme değil: on “ana makine bir arka uç sunduğunda sar” demektir, asla “bir tane şart koş” değil.

Yerel arka uç

macOS: Seatbelt

Apple’ın Seatbelt sandbox mekanizmasını kullanır (macOS App Sandbox’ın da kullandığı sistemin aynısı).

Üretilen profil varsayılan olarak izin vericidir ((allow default)) ve retleri oyar; çünkü tamamen varsayılan olarak reddeden bir profil etkileşimli bir kabuğu kullanılamaz hâle getirir — numaralandırılacak çok fazla dyld, XPC ve Mach çağrısı vardır. Bunun pratik sonucu, bir ajanın ana makinenin çoğunu yine de okuyabilmesidir; kayıtlı çalışma kopyalarınız görünmezlikle değil, açık yazma ve yeniden adlandırma retleriyle korunur.

Dosya sistemi okumaları: gizli yollar için reddedilir (~/.ssh, ~/.aws, ~/.gnupg, ~/.config/gh, ~/Library/Keychains ve okuma-reddi kümesinin geri kalanı)
Dosya sistemi yazmaları: redde sıfırlanır, ardından açık alt yol izinleri eklenir; zorunlu red yolları (kabuk rc dosyaları, .git/hooks, Claude yapılandırması, korunan çalışma kopyaları) yazılabilir bir kökün içinde bile engellenir. file-write-unlink reddedilen her yol ve onun üstleri için reddedilir, böylece bir yeniden adlandırma yazma reddini atlayamaz
Süreç: process-exec, her zaman tehlikeli ikilileri reddeder; ayrıca yazılabilir bir dizinden herhangi bir şeyin yürütülmesini engeller
Ağ: süreç içi proxy portları artı DNS ile kısıtlanır — loopback’e toptan izin verilmez ve Unix soketlerine izin verilmez. Proxy’ler oturum başına alan adı izin listesini uygular (bkz. Ağ çıkışı)
Yapılandırma: profiller her başlatmada SandboxSpec üzerinden üretilir

Gereksinimler:

sandbox-exec (/usr/bin/sandbox-exec), her macOS kurulumunun parçası — ek araç gerekmez

Linux: bubblewrap

Mount ve PID ad alanları oluşturmak için bubblewrap (bwrap) kullanır.

Dosya sistemi: yalnızca bağlanan yolların görünür olduğu bir mount ad alanı oluşturur
Ağ: paylaşılmayan bir ağ ad alanında çalışır; trafik ana makine proxy’lerine socat Unix soket köprüleri üzerinden ulaşır
Süreç: PID ad alanı yalıtımı

Gereksinimler:

bubblewrap ve socat kurulu olmalı (Debian/Ubuntu’da sudo apt-get install bubblewrap socat)
Çekirdek ad alanı desteği (modern Linux’ta standart)

Bubblewrap var olan bir yolu gölgeleyebilir ama yazılabilir bir bind içinde yeni bir .env, *.key veya *.pem dosyasını yasaklayamaz. Standart gönderim politikası bu dosya adı glob’uyla yazma retlerini gerektirir, dolayısıyla yerel ajan gönderimi şu anda yoklama bubblewrap’i bulsa bile Linux/WSL2’de başarısızlıkta kapalı davranır. Sessizce daha zayıf bir politikayla çalışmaz. Linux’ta yerel gönderimi geri getirmek için oluşturma zamanında dosya adı kuralları olan bir arka uç gerekir. Sandbox’ı devre dışı bırakmak, eşdeğer bir geçici çözüm değil, açık bir kısıtlamasız devre dışı bırakmadır.

Yalıtımsız arka uç

Sandbox yok. Süreç doğrudan ana makinede, ana makinenin dosya sistemi, ağ ve süreç erişimiyle çalışır. ACP ve harness bash aracı yine de ortam arındırmasını ve komut politikasını alır; NoSandboxAdapter üzerinden Claude Code ana makinenin ortamını devralır. Kullanılabilir bir arka ucu olmayan ya da --sandbox off ayarlanmış bir ana makinede ajan gönderiminin geri düştüğü yer burasıdır ve bir istemci none adını verdiğinde terminalin varsayılanı budur.

Sunucuda barındırılan terminal

Terminal, gönderim yoklamasıyla değil, kendi koşullarıyla sandbox’a alınır. TerminalSessionService’in defaultBackend değeri nonedır ve cc_server bunu geçersiz kılmaz; dolayısıyla bir terminal oturumu, istemci açıkça native istemedikçe ana makine kabuğunu çalıştırır — masaüstünün terminal paneli istemez.

native istendiğinde kabuk, SandboxManager üzerinden sabit bir terminal profiliyle sarılır: $HOME ve oturumun çalışma dizini yazılabilirdir, ağ açıktır ve ~/.ssh, ~/.aws, ~/.gnupg, ~/.config/gh ile ~/Library/Keychains okumaya kapalıdır. Salt okunur forge token’ı ve push ağ geçidi geçerli değildir — bunlar gönderim meseleleridir. Sarmalama desteklenmiyorsa oturum, ana makine kabuğu PTY’sinde yerel bir rozet göstermek yerine başarısız olur.

Ağ çıkışı

Bir sandbox başlatıldığında, dışa giden ağ erişimi çekirdek güvenlik duvarı kurallarıyla değil, süreç içi proxy’lerle uygulanır. Kullanılabilir arka ucu olmayan bir ana makinede bunların hiçbiri geçerli değildir ve başlatılan bir süreç ağa tam olarak sunucu kullanıcısının erişeceği gibi erişir.

Sandbox çalışma zamanı, cc_server sürecinin içinde 127.0.0.1 üzerinde bir HTTP/HTTPS proxy ve bir SOCKS5 proxy çalıştırır, kısıtlı oturum başına bir çift (http_proxy.dart, socks_proxy.dart). Eşzamanlı çalıştırmalar bir çifti paylaşmaz.
Sandbox’a alınmış süreçler proxy ortam değişkenlerini alır (HTTP_PROXY/HTTPS_PROXY → HTTP proxy’si, ALL_PROXY → SOCKS proxy’si; GIT_SSH_COMMAND, SSH üzerinden git’i SOCKS proxy’sinden geçirir). Linux’ta ağ ad alanı paylaşılmaz, dolayısıyla çıkışın tek yolu proxy’lerdir; macOS’ta sandbox ana makinenin loopback’ini paylaşır ve onlarla doğrudan konuşur.
Her bağlantının hedef ana makinesi oturumun alan adı izin listesiyle eşleştirilir; başka her şey reddedilir. Her birinde tam olarak bir * bulunan iki joker biçim vardır: baştaki *.example.com her alt alan adıyla (a.b.example.com dahil) eşleşir ama kök alanın kendisiyle eşleşmez; ortada etiket bulunan bedrock.*.amazonaws.com tam olarak bir etiketle eşleşir (bedrock.us-east-1.amazonaws.com, bedrock.evil.attacker.amazonaws.com değil).
İzin listesi oturum başına, özenle seçilmiş temelden (kBaselineAllowedDomains: LLM sağlayıcıları, Git barındırma, paket kayıt defterleri), GitHub alan adlarından (kGithubDomains) ve SandboxSpec.egressAllowlist değerinden çözülür. Gönderim yolu asla ek egressAllowlist girdileri geçirmez; dolayısıyla pratikte her çalıştırma temeli artı GitHub’ı alır.
Sabit bir ret listesi (kBaselineDeniedDomains: bulut meta veri uç noktaları, telemetri hedefleri) tüm izinlerin önüne geçer.
networkEnabled: false, oturum başına proxy’leri yine de başlatır, ama izin listesi boştur, dolayısıyla her dışa giden bağlantı reddedilir. Gönderim bu değeri çalıştırma başlarken Ağa eriş kuralından ayarlar: reddet ağı kapatır, izin ver ve önce sor açık bırakır.

SandboxSpec

SandboxPort.launch işlevine geçirilen belirtim:

Alan	Tür	Açıklama
`sessionId`	`String`	Kararlı oturum tanımlayıcısı (genellikle alan kimliği)
`workspaceId`	`String`	Sahip olan çalışma alanının kimliği
`agentId`	`String?`	Sandbox’a bağlı olan ajan, varsa
`bindMounts`	`List<SandboxBindMount>`	Ana makine→misafir mount’lar; sandbox yalnızca burada listelenen ana makine yollarını görür
`networkEnabled`	`bool` (varsayılan `true`)	Gönderimde ağ çıkışı kuralından ayarlanır (yalnızca reddet olarak çözümlendiğinde kapalı). Kapalıyken oturum başına proxy’ler yine başlar ama izin listesi boştur, dolayısıyla her dışa giden bağlantı reddedilir
`egressAllowlist`	`List<String>` (varsayılan `[]`)	Ek izinli çıkış alan adları; joker karakterler desteklenir (`*.example.com`, ayrıca ortada tek etiketli biçim). Gönderim bunu asla doldurmaz, dolayısıyla sarılmış bir çalıştırma özenle seçilmiş temeli artı GitHub alan adlarını alır
`guestWorkdir`	`String?`	Sandbox içindeki varsayılan çalışma dizini; tek tek `exec` çağrıları bunu geçersiz kılabilir
`mode`	`Mode` (varsayılan `chat`)	Dosya sistemi yazma kurallarını oyar: `chat` bind mount’ları yazılabilir tutar; `review`, `plan` ve `orchestrate` salt okunurdur
`protectedPaths`	`List<String>` (varsayılan `[]`)	Sandbox içinde hiçbir modda yazılabilir olmaması gereken ana makine yolları
`runnerStateDirs`	`List<String>` (varsayılan `[]`)	Runner’ın kendi durumunu tuttuğu, her modda yazılabilir ana makine dizinleri (Control Center tarafından yönetilen bir `CLAUDE_CONFIG_DIR` şu anki örnektir)
`execGrantRoots`	`List<String>` (varsayılan `[]`)	macOS’ta yazılabilir dizin exec engelini yeniden açan, operatör onaylı dizin ağaçları. Linux bunları yok sayar — bwrap’te yeniden açılacak bir `$HOME` exec engeli yoktur

protectedPaths, gönderim başına çalışma alanının depolarından çözülen, kayıtlı orijinal depo çalışma kopyalarını tutar. Ajanlar yalnızca konuşma başına copy-on-write çalışma ağaçlarında çalışır, dolayısıyla orijinaller sandbox’ın içinden asla yazılabilir olmamalıdır — macOS’ta Seatbelt’in toptan $HOME yazma izni onları aksi hâlde bash üzerinden yazılabilir bırakırdı. Her modda, chat dahil, gizli bilgilerin yazma-reddi kümesine katılırlar.

Her okuma-reddi ve yazma-reddi yolu hem düz yazımıyla hem de sembolik bağdan çözülmüş yazımıyla yayımlanır. Çekirdek bir ret kuralını çözülmüş yola göre eşleştirir, dolayısıyla sembolik bağlı bir yola yazılmış bir kural asla tetiklenmez — ve macOS’ta bu, sıra dışı olan değil olağan durumdur; çünkü /tmp /private/tmpye, /var/folders/… ise /private/var/folders/…ye çözülür. * veya ? içeren girdiler glob olarak ele alınır ve olduğu gibi bırakılır; çözülemeyen bir yol yazıldığı gibi korunur.

SandboxBindMount

Alan	Tür	Açıklama
`hostPath`	`String`	Ana makinedeki mutlak yol
`guestPath`	`String`	Sandbox içindeki yol (yerel sandbox’ta bu `hostPath`e eşittir; adaptör simetrisi için korunur)
`readOnly`	`bool` (varsayılan `false`)	Doğru olduğunda salt okunur bağlanır

SandboxHandle

SandboxPort.launch tarafından döndürülür:

Alan	Tür	Açıklama
`sessionId`	`String`	Oturum tanımlayıcısı
`backend`	`SandboxBackend`	Hangi arka ucun çalıştığı
`state`	`SandboxState`	Yaşam döngüsü durumu
`error`	`Object?`	`state` değeri `error` olduğunda ayarlanır
`details`	`Map<String, Object?>`	Adaptöre özel kayıt tutma (çalışma dizini, PID, profil yolu vb.)

SandboxState

Durum	Açıklama
`created`	Belirtim oluşturuldu ama VM henüz başlatılmadı
`warm`	Çalışıyor ve komut yürütmeye hazır
`active`	Şu anda bir komut yürütüyor
`suspended`	RAM tasarrufu için duraklatıldı / diske kontrol noktası olarak yazıldı
`destroyed`	Yıkıldı; tutamaç artık geçerli değil
`error`	Başlatma başarısız — bkz. `SandboxHandle.error`

Sandbox olayları

Olay türü	Açıklama
`stdout`	Sandbox’tan standart çıktı
`stderr`	Sandbox’tan standart hata
`exit`	Sandbox süreci çıktı (`exitCode` taşır)
`starting`	Sandbox başlatılıyor
`ready`	Sandbox exec çağrılarını kabul etmeye hazır
`killed`	Süreç ana makine tarafından öldürüldü (OOM, zaman aşımı, elle durdurma)
`violation`	Bir sandbox politikası ihlal edildi (bir `SandboxViolation` taşır)

SandboxViolation

Alan	Tür	Açıklama
`action`	`String`	Reddedilen fiil (örn. `file-read*`, `network-outbound`)
`target`	`String`	Reddedilen işlemin hedefi olan yol ya da ana makine
`raw`	`String?`	Ham günlük satırı, hata ayıklama için kullanışlı