Claude Code'da Sandbox: Bash Aracını İzole Çalıştırma Rehberi

Claude Code'u onay yorgunluğu olmadan kullanmanın en yaygın yollarından biri Auto Mode'dur — ama sınıflandırıcı yine de her kabuk komutunu tek tek değerlendirir. Sandboxlı Bash aracı bunun yerine tamamen farklı bir yaklaşım sunar: hangi dosyalara ve alan adlarına erişileceğini siz tanımlarsınız, işletim sistemi bu sınırı her Bash komutu ve onun alt süreçleri için zorunlu kılar. Sonuç olarak Claude çoğu kabuk komutunu hiç sormadan çalıştırabilir, çünkü sınır zaten model kararına değil OS'a dayanır. Bu yazıda Claude Code'un resmi dokümantasyonuna dayanarak sandbox'ın nasıl kurulacağını, nasıl yapılandırılacağını, izin sistemiyle ilişkisini, yaygın sorunları ve sınırlamalarını adım adım anlatıyorum.

Sandbox Nedir, Neden Var?

Sandbox, Claude Code'a yerleşik olarak gelen bir özelliktir; ekstra bir servis kaydına ya da API anahtarına ihtiyaç duymaz. Fikir basit: Bash aracının erişebileceği dosyaları ve ağ üzerinde konuşabileceği alan adlarını önceden tanımlarsınız, işletim sistemi bu sınırı çalışan her sürece ve onun ürettiği alt süreçlere karşı zorunlu kılar. Bu, model tarafından üretilen komut metnine bakarak karar veren klasik izin isteminden temelde farklıdır: bir komut isminin masum görünmesi yetmez, gerçekten çalıştığında yaptığı her şey sandbox sınırına tabidir.

Sandbox iki bağımsız katmandan oluşur: dosya sistemi izolasyonu (sandboxlı komutların hangi yollara okuma/yazma yapabileceğini kontrol eder) ve ağ izolasyonu (hangi alan adlarına erişilebileceğini kontrol eder). İki katman birbirinden bağımsız olarak açılıp kapatılabilir; ama resmi dokümantasyon, etkili bir sandbox için ikisinin birlikte açık olmasının önemini özellikle vurguluyor — ağ izolasyonu olmadan ele geçirilmiş bir ajan SSH anahtarları gibi hassas dosyaları dışarı sızdırabilir, dosya sistemi izolasyonu olmadan ise sistem kaynaklarını arka kapıya çevirip ağ erişimi kazanabilir.

Sandbox'ı Etkinleştirme: /sandbox Komutu

Sandbox'a başlamanın en kolay yolu bir Claude Code oturumu içinde /sandbox komutunu çalıştırmaktır:

/sandbox

Bu komut üç sekmeli bir panel açar (Linux'ta isteğe bağlı seccomp filtresi eksikse bir Dependencies sekmesi daha eklenir):

• Mode: sandboxlı komutların nasıl onaylanacağını seçersiniz (auto-allow ya da normal izinler).
• Overrides: sandbox altında başarısız olan komutların sandbox dışında çalışmaya geri düşüp düşemeyeceğini belirler; bu, allowUnsandboxedCommands ayarına karşılık gelir.
• Config: geçerli (resolved) sandbox ayarlarını gösterir.

Panel yalnızca bir Dependencies sekmesi gösteriyorsa gerekli bir paket eksik demektir; aşağıdaki Linux/WSL2 kurulum adımını uygulayıp Claude Code'u yeniden başlatın ve /sandbox'ı tekrar çalıştırın. Bağımlılık kontrolü yalnızca başlangıçta çalışır, bu yüzden paket kurduktan sonra yeniden başlatmak gerekir.

Mode sekmesinde bir seçim yaptığınızda Claude Code bunu projenizin yerel ayarlarına, .claude/settings.local.json dosyasına kaydeder; bu dosya yalnızca geçerli projeye uygulanır ve Claude Code onu global gitignore'a otomatik ekler. Sandbox'ı tüm projelerinizde açmak için kullanıcı ayarlarınızdaki (~/.claude/settings.json) sandbox.enabled anahtarını true yapmanız yeterlidir; bir organizasyondaki herkes için zorunlu kılmak isterseniz managed settings kullanılır (aşağıda ayrı bir bölümde ele alıyorum).

Varsayılan olarak, sandbox bağımlılık eksikliği ya da platform desteksizliği yüzünden başlayamazsa Claude Code bir uyarı gösterip komutları sandboxsuz çalıştırır. Bunu sert bir hataya çevirmek — yani sandbox kullanılamıyorsa hiç çalışmamak — isterseniz sandbox.failIfUnavailable ayarını true yapabilirsiniz; bu, sandbox'ı bir güvenlik kapısı olarak zorunlu kılan yönetilen dağıtımlar için tasarlanmıştır.

Linux ve WSL2 Kurulumu

macOS'ta hiçbir şey kurmanız gerekmez; sandbox yerleşik Seatbelt çatısını kullanır. Linux ve WSL2'de ise sandbox iki pakete dayanır:

• bubblewrap — dosya sistemi izolasyonunu uygulayan, yetkisiz (unprivileged) sandbox aracı.
• socat — ağ trafiğini sandbox proxy'sinden geçiren röle.

Ubuntu/Debian'da:

sudo apt-get install bubblewrap socat

Fedora'da:

sudo dnf install bubblewrap socat

Ripgrep, native Claude Code ikili dosyasıyla birlikte gelir, ayrıca kurulması gerekmez. İsteğe bağlı seccomp filtresi Unix domain socket engellemesi ekler; eksikse şu komutla kurabilirsiniz:

npm install -g @anthropic-ai/sandbox-runtime

Ubuntu 24.04 ve sonrasında, varsayılan AppArmor politikası bubblewrap'in ihtiyaç duyduğu kullanıcı ad alanlarını (user namespace) oluşturmasını engelleyebilir. Ortamınızın bunu kısıtlayıp kısıtlamadığını kontrol etmek için:

sysctl kernel.apparmor_restrict_unprivileged_userns

Komut 0 döndürüyorsa ya da anahtar hiç yoksa bu adımı atlayabilirsiniz. 1 döndürüyorsa, bwrap'e bu yetkiyi veren bir AppArmor profili eklemeniz gerekir:

sudo tee /etc/apparmor.d/bwrap > /dev/null <<'EOF'
abi <abi/4.0>,
include <tunables/global>

profile bwrap /usr/bin/bwrap flags=(unconfined) {
  userns,
  include if exists <local/bwrap>
}
EOF
sudo systemctl reload apparmor

WSL2 kullanıcıları için ayrı bir not: WSL, cmd.exe, powershell.exe gibi bir Windows ikili dosyasının veya /mnt/c/ altındaki bir şeyin başlatılmasını bir Unix soketi üzerinden Windows host'una devreder. Bu tür başlatmaların sandbox içinden çalışıp çalışamayacağı allowUnixSockets ayarına bağlıdır (soketi ilk etapta engellemek için isteğe bağlı seccomp filtresinin kurulu olması gerekir). WSL sürümünüzü wsl -l -v ile kontrol edin; "Sandboxing requires WSL2" mesajı görürseniz dağıtımınızı WSL2'ye yükseltmeniz gerekir.

Sandbox Modları: Auto-allow ve Normal İzinler

İki modda da sandbox aynı dosya sistemi ve ağ kısıtlamalarını uygular; fark yalnızca sandboxlı komutların otomatik mi onaylanacağı yoksa açık izin mi isteyeceğidir.

Auto-allow modunda sandbox içine alınabilen bir komut sorulmadan çalışır. İzin verilmeyen bir host'a erişim gerektiren komutlar gibi sandbox'a alınamayan komutlar ise normal izin akışına düşer. Auto-allow modunda bile şunlar geçerliliğini korur:

• Açık deny kuralları her zaman uygulanır.
• Kritik bir yolu (dosya sistemi kökü, ev dizini gibi) hedefleyen rm veya rmdir komutları normal izin akışına gider.
• İçerik bazlı ask kuralları (ör. Bash(git push *)) sandboxlı komutlar için bile onay istemeye devam eder.
• Salt Bash ya da eşdeğeri Bash(*) gibi geniş bir ask kuralı sandboxlı çalışan komutlar için atlanır (normal izin akışına düşen komutlarda hâlâ geçerlidir); ama plan modunda bu kural atlanmaz, salt okunur komutlar dahil sandboxlı komutlar için de sorar (v2.1.212 öncesinde plan modunda da atlanıyordu).

Auto-allow modu, izin modu ayarınızdan bağımsız çalışır — tek istisna plan modudur. "Kabul et" (accept edits) modunda olmasanız bile, auto-allow açıksa sandboxlı Bash komutları sormadan çalışır; bu, Manual modda dosya düzenleme araçlarının onay isteyeceği durumlarda bile sandbox sınırları içindeki dosyaları değiştiren Bash komutlarının sormadan çalışabileceği anlamına gelir. Plan modunda ise auto-allow onayları genişletmez (v2.1.212 öncesinde genişletiyordu).

Normal izinler modunda ise tüm Bash komutları, sandboxlı olsalar bile normal izin akışından geçer — daha fazla kontrol sağlar ama daha fazla onay gerektirir.

Sandbox Dışına Çıkış Kapısı: dangerouslyDisableSandbox

Bazı komutlar sandbox içinde hiç çalışamaz — sandbox ile uyumsuz araçlar ya da izin vermediğiniz bir host'a ihtiyaç duyan komutlar gibi. Claude Code, engellenen komutun sonucunda sandbox'ın hangi yolu ya da host'u reddettiğini adlandıran bir ihlal raporu döner, böylece Claude neyin engellendiğini görür. Görevi başarısız saymak ya da sizi sandbox'ı kapatmaya zorlamak yerine bir kaçış kapısı sunulur: Claude ihlali analiz eder ve komutu dangerouslyDisableSandbox parametresiyle yeniden deneyebilir.

Yeniden denenen komut sandbox dışında çalışır, dolayısıyla normal izin akışından geçer: Manual modda onay istemi görürsünüz, Auto Mode'da ise sınıflandırıcı asıl komutu değerlendirir. Auto Mode'da bile her sandboxsuz yeniden denemede sorulmasını istiyorsanız Bash(dangerouslyDisableSandbox:true) için bir ask kuralı ekleyebilirsiniz.

Bu kaçış kapısını tamamen kapatmak için sandbox ayarlarınızda "allowUnsandboxedCommands": false yazabilirsiniz — /sandbox'ın Overrides sekmesinde bu Strict sandbox mode olarak gösterilir. Devre dışı bırakıldığında dangerouslyDisableSandbox parametresi tamamen yok sayılır; tüm komutlar ya sandboxlı çalışmak ya da excludedCommands listesinde açıkça yer almak zorundadır.

Geçici Dizinler

Oturum geçici dizini varsayılan olarak sandbox içinde çalışma dizini yanında yazılabilir durumdadır. Dosya sistemi izolasyonunu kapatmadığınız sürece Claude Code, sandboxlı komutlar için $TMPDIR'ı bu dizine ayarlar; böylece geçici dosya yazan araçlar ek bir yapılandırma gerektirmeden çalışır. Sandboxsuz komutlar ise kabuğunuzun $TMPDIR'ını değiştirmeden miras alır — yani dosya sistemi izolasyonu açıkken sandboxlı ve sandboxsuz komutlar $TMPDIR'ı farklı dizinlere çözer. İki taraf arasında geçici dosya taşımak isterseniz bunları çalışma dizini altına yazmanız gerekir.

Sandbox'ı Yapılandırma

Sandbox davranışını settings.json dosyanız üzerinden özelleştirirsiniz. Varsayılan olarak sandboxlı komutlar geçerli çalışma dizinine, oturum geçici dizinine ve --add-dir, /add-dir ya da permissions.additionalDirectories ile eklediğiniz dizinlere yazabilir. kubectl, terraform ya da npm gibi alt süreç komutlarının bu dizinlerin dışına yazması gerekiyorsa, aracı excludedCommands ile sandbox'tan tamamen çıkarmak yerine sandbox.filesystem.allowWrite ile belirli yollara izin vermeniz önerilir:

{
  "sandbox": {
    "enabled": true,
    "filesystem": {
      "allowWrite": ["~/.kube", "/tmp/build"]
    }
  }
}

Bu yollar OS düzeyinde uygulanır, dolayısıyla sandbox içinde çalışan tüm komutlar ve onların alt süreçleri bunlara uymak zorundadır. Aynı dosya sistemi dizisini birden fazla ayar kapsamında (scope) tanımlarsanız Claude Code, bir kapsamın dizisini diğeriyle değiştirmek yerine tüm kapsamlardaki yolları birleştirir. Bu listeleri bir oturum sırasında düzenlerseniz değişiklik çalışan oturuma hemen uygulanır; bir sonraki sandboxlı komut yeni yollarla çalışır.

Yol ön ekleri şu şekilde çözülür:

Ön ek	Anlamı	Örnek
/	Dosya sistemi kökünden mutlak yol	/tmp/build aynen /tmp/build kalır
~/	Ev dizinine göreli	~/.kube, $HOME/.kube olur
./ veya ön eksiz	Proje ayarları için proje köküne, kullanıcı ayarları için ~/.claude'a göreli	.claude/settings.json'daki ./output, proje kökündeki output'a çözülür

Bu söz dizimi, Read/Edit izin kurallarındaki mutlak yol için //path, proje-göreli yol için /path kullanan yapıdan farklıdır — sandbox dosya sistemi yolları standart kuralları izler.

sandbox.filesystem.denyWrite ve sandbox.filesystem.denyRead ile yazma ya da okuma erişimini engelleyebilir, sandbox.filesystem.allowRead ile de engellenen bir bölge içinde belirli yolları yeniden açabilirsiniz. Okuma kuralları çakıştığında daha spesifik olan yol kazanır: örneğin "denyRead": ["~/"] ile "allowRead": ["~/projects"] birlikte tanımlanırsa ~/projects okunabilir kalırken ev dizininin geri kalanı engelli kalır; tersine "allowRead": ["~/"] ile "denyRead": ["~/.env"] tanımlanırsa ~/.env engelli kalır — geniş bir allow gizli bir sırrı sessizce yeniden açamaz.

Aşağıdaki örnek, tüm ev dizininden okumayı engelleyip yalnızca geçerli projeden okumaya izin verir (bunu proje ayarlarına, .claude/settings.json dosyasına koymalısınız — çünkü . yalnızca proje ayarlarında proje köküne çözülür):

{
  "sandbox": {
    "enabled": true,
    "filesystem": {
      "denyRead": ["~/"],
      "allowRead": ["."]
    }
  }
}

Dosya Sistemi İzolasyonunu Kapatmak

Ağ izolasyonunu korurken yalnızca dosya sistemi izolasyonunu atlamak isterseniz sandbox.filesystem.disabled ayarını true yapabilirsiniz:

{
  "sandbox": {
    "enabled": true,
    "filesystem": {
      "disabled": true
    },
    "network": {
      "allowedDomains": ["github.com", "*.npmjs.org"]
    }
  }
}

Bu ayar varsayılan olarak kapalıdır ve v2.1.216 veya üzeri gerektirir. Dosya sistemi katmanı kapalıyken sandboxlı komutlar host dosya sistemine sınırsız okuma/yazma erişimi kazanır, ama ağ trafiği yine izin verdiğiniz alan adlarıyla sınırlı kalır. Resmi dokümantasyon burada net bir uyarıda bulunuyor: dosya sistemi izolasyonu kapalı ve komutlar otomatik onaylanıyorsa, sandboxlı bir komut daha sonra çalıştırılacak dosyalar (kabuk başlangıç dosyaları, $PATH üzerindeki çalıştırılabilirler, ~/.claude/settings.json gibi) yazıp kendi erişimini genişletebilir. Bu yüzden filesystem.disabled'ı yalnızca kendi erişimini yükseltmeyeceğine güvendiğiniz iş yükleri için açmanız önerilir; allowManagedDomainsOnly ile ağ alan adlarını kilitlemek riski azaltır ama tamamen ortadan kaldırmaz.

Bu ayarı yalnızca kullanıcı ayarları, managed settings ve --settings CLI bayrağı belirleyebilir — proje ayarları olan .claude/settings.json ve .claude/settings.local.json bu anahtarı ayarlayamaz, böylece bir depoyu checkout etmek dosya sistemi izolasyonunu kapatamaz.

Kimlik Bilgilerini Koruma

sandbox.credentials ayarı, sandboxlı komutlardan korunacak kimlik bilgisi dosyalarını ve ortam değişkenlerini tanımlar — v2.1.187 veya üzeri gerektirir. "mode": "deny" olan girdilerde dosya yolları sandbox içinde okumaya kapatılır (bu, filesystem.denyRead ile aynı kısıtlamadır), ortam değişkenleri ise her sandboxlı komut çalışmadan önce ortamdan kaldırılır:

{
  "sandbox": {
    "enabled": true,
    "credentials": {
      "files": [
        { "path": "~/.aws/credentials", "mode": "deny" },
        { "path": "~/.ssh", "mode": "deny" }
      ],
      "envVars": [
        { "name": "GITHUB_TOKEN", "mode": "deny" },
        { "name": "NPM_TOKEN", "mode": "deny" }
      ]
    }
  }
}

Bunu belirtmek önemli: varsayılan okuma davranışı hâlâ ~/.aws/credentials ve ~/.ssh/ gibi kimlik bilgisi dosyalarını okumaya izin verir — dosya sistemi izolasyonu bu dosyaları otomatik olarak engellemez, çünkü sandbox'ın varsayılan okuma davranışı "engellenen belirli dizinler dışında tüm bilgisayarı okuma erişimi" şeklindedir. Bu dosyaları sandboxlı komutlardan gerçekten korumak istiyorsanız sandbox.credentials girdileri eklemeniz ya da onları denyRead'e koymanız gerekir.

"mode": "mask" seçeneği deny'den bir adım öteye gider: kimlik bilgisini tamamen engellemek yerine sandboxlı komuta bir yer tutucu (sentinel) gösterir ve sandbox proxy'si izin verdiğiniz host'lara giden isteklerde gerçek değeri devreye sokar — bu sayede gh veya npm gibi araçlar kimlik doğrulamasını kaybetmeden çalışmaya devam eder. Masking, AWS SigV4 imzalarının yeniden imzalanması gibi ileri düzey senaryoları da destekler, ama bu yazının kapsamı dışında; ayrıntılar için resmi sandboxing dokümantasyonuna bakabilirsiniz.

Sandbox Nasıl Çalışır?

Dosya Sistemi İzolasyonu

Davranış	Açıklama
Varsayılan yazma	Çalışma dizini ve alt dizinleri, --add-dir//add-dir/permissions.additionalDirectories ile eklenen dizinler, $TMPDIR'ın gösterdiği oturum geçici dizini
Varsayılan okuma	Belirli engellenen dizinler dışında tüm bilgisayar (kimlik bilgisi dosyaları dahil — korumak için sandbox.credentials gerekir)
Engellenen erişim	Çalışma dizini, eklenen dizinler ve geçici dizin dışına açık izin olmadan yazma — ~/.bashrc gibi kabuk yapılandırma dosyaları ve /bin/ içindeki sistem ikilileri dahil
Git worktree'ler	Çalışma dizini bağlı bir git worktree ise sandbox, ana deponun paylaşılan .git dizinine de yazma izni verir (böylece git commit ref'leri ve index'i güncelleyebilir); ama hooks/ ve config'e yazma yine engellidir

Korumalı Yollar

Sandboxlı komutların yazabildiği dizinler içinde bile, sandbox Claude Code'un yapılandırma ve kod okuduğu dosyalara yazmayı reddeder. Bu dosyaları düzenleyebilen bir komut kendine izin verebilir ya da sandbox dışında çalışan bir hook veya MCP sunucusu ekleyebilir. Korunan yollar dört grupta toplanır:

• Çalışma dizininizde ve üstündeki dizinlerde: .claude ayar dosyaları, .claude/skills, .claude/agents, .claude/commands, .claude/hooks dizinleri, .mcp.json, ve .claude/workflows, .claude/scheduled_tasks.json gibi Claude Code'un kendiliğinden çalıştırdığı dosyalar.
• Yalnızca çalışma dizininde: .bashrc/.zshrc gibi kabuk başlangıç dosyaları, .gitconfig, .vscode ve .idea dizinleri, .git içindeki hooks ve config.
• Çalışma dizininizi çıplak (bare) bir git deposuna çevirecek dosyalar: en üst seviyedeki HEAD, objects, refs, ve zaten mevcutlarsa config, hooks.
• ~/.claude içinde (veya CLAUDE_CONFIG_DIR'ın gösterdiği dizinde): içeriğinin çoğu, artı ~/.claude.json ve .credentials.json kimlik bilgisi deposu.

Bu korumayı hiçbir allowWrite ya da Edit izin kuralı geçersiz kılamaz; kapatmanın tek yolu dosya sistemi izolasyonunu tamamen kapatan filesystem.disabled'dır — ki o zaman da o dosyaları başka bir mekanizmayla korumanız gerekir. Bu yolların makinenizde nasıl çözüldüğünü görmek için /sandbox'ı açıp Config sekmesindeki Denied within allowed bölümüne bakabilirsiniz.

Ağ İzolasyonu

Ağ erişimi, sandbox dışında çalışan bir proxy sunucusu üzerinden kontrol edilir. Claude Code varsayılan olarak hiçbir alan adına önceden izin vermez: bir komut yeni bir alan adına ilk kez ihtiyaç duyduğunda Claude Code onay ister (Auto Mode'da istek sınıflandırıcıya gider). "Evet" derseniz host, oturumun geri kalanı için izinli kalır; "Evet, bir daha sorma" derseniz Claude Code yerel ayarlarınıza bir WebFetch(domain:...) allow kuralı kaydeder ve host gelecek oturumlarda da izinli kalır. İstemi tamamen atlamak için alan adlarını allowedDomains ile önceden tanımlayabilirsiniz.

Üç yapılandırılabilir kilitleme seviyesi vardır:

• strictAllowlist — kullanıcı, managed veya CLI --settings ayarlarında true yapılırsa, sandboxlı komutlar için allowlist dışındaki her host sormadan reddedilir (v2.1.219+; repo ayarlarında etkisizdir).
• allowManagedDomainsOnly — managed settings'te ayarlanırsa, izinli olmayan alan adları sormadan engellenir ve yalnızca managed settings'ten gelen allowedDomains/WebFetch(domain:...) kuralları geçerli olur.
• Kurumsal proxy — ağınız trafiğin bir kurumsal proxy'den geçmesini gerektiriyorsa HTTPS_PROXY, HTTP_PROXY ve NO_PROXY'yi ayarlarınızın env bloğunda tanımlayabilirsiniz; Claude Code önce alan adı allowlist'ini uygular, sonra izinli bağlantıları bu üst akış proxy'sinden tünelletir.

Proxy, izin kararını istenen host adına bakarak verir ve varsayılan olarak TLS trafiğini sonlandırıp incelemez. İleri düzey kullanıcılar özel bir proxy kurup HTTPS trafiğini deşifre edip inceleyebilir, kendi filtreleme kurallarını uygulayabilir ve tüm istekleri loglayabilir; bunun için sandbox ayarlarında httpProxyPort ve socksProxyPort belirtilir.

İşletim Sistemi Düzeyinde Uygulama

Sandbox, platforma göre farklı OS güvenlik ilkellerini kullanır: macOS'ta Seatbelt, Linux'ta bubblewrap, WSL2'de de yine bubblewrap (Linux ile aynı). Bu ilkeller ayrıca bağımsız bir @anthropic-ai/sandbox-runtime paketi olarak da sunulur; bu paket, Claude Code sürecinin tamamını sarmalayan ayrı bir yaklaşım olarak "Sandbox environments" dokümanında ele alınır.

Sandbox, İzin Kuralları ve İzin Modlarıyla Nasıl İlişkilidir?

Sandbox'ı, klasik izin kurallarını ve Auto Mode'u karıştırmak kafa karıştırıcı olabilir — bu üçü tamamlayıcı katmanlardır, aynı şeyi yapmazlar. İzin kuralları hangi araçların çalışabileceğini, çalışmadan önce kontrol eder ve Bash dahil tüm araçlara uygulanır. Sandbox ise yalnızca Bash komutlarını ve alt süreçlerini kapsar, OS düzeyinde neye erişebileceklerini kısıtlar. Fark uygulama biçiminde de kendini gösterir: izin kararları komut çalışmadan önce, komut metnine (ve Auto Mode'da sınıflandırıcının yargısına) bakılarak verilir; sandbox sınırı ise çalışan sürecin üzerinde işletim sistemi tarafından uygulanır — modelin ne çalıştırmayı seçtiğinden bağımsızdır, izin verilen bir komut adının önerdiğinden fazlasını yapsa bile geçerlidir.

	Neyi kontrol eder	İstemin yerini ne alır
/sandbox	Bir Bash komutunun çalıştıktan sonra neye erişebileceği	Auto-allow modunda sandbox sınırının kendisi
Auto Mode	Her araç çağrısının çalışıp çalışmayacağı	Eylemleri inceleyen sınıflandırıcı
--dangerously-skip-permissions	Her araç çağrısının çalışıp çalışmayacağı	Hiçbir şey (korumalı yol kontrolleri de atlanır; hiçbir modun otomatik onaylamadığı eylemler yine geçerlidir)

Sandbox'ın auto-allow modu, Auto Mode'dan bağımsızdır: auto-allow, komutu sandbox sınırının içine hapsettiği için onaylar; Auto Mode ise eylemleri incelemek üzere bir sınıflandırıcı kullanır. İkisi bağımsız çalışır ve birlikte kullanılabilir — pratikte de en yaygın kurulum budur, çünkü sandbox OS düzeyinde bir sınır çizerken Auto Mode geri kalan araçlar (Read, Edit, WebFetch, MCP) için sınıflandırıcı denetimi sağlar.

Organizasyon İçin Sandbox'ı Zorunlu Kılmak

Yöneticiler, sandbox'ı her geliştirici için zorunlu kılabilir, geliştiricilerin politikayı genişletmesini engelleyebilir ve sandbox trafiğini bir kurumsal proxy'den geçirebilir. sandbox anahtarlarını managed settings üzerinden (MDM tarafından yönetilen bir dosya ya da Claude.ai'de server-managed settings) dağıtarak sandbox'ı zorunlu kılabilirsiniz:

{
  "sandbox": {
    "enabled": true,
    "failIfUnavailable": true,
    "allowUnsandboxedCommands": false
  }
}

enabled dışındaki iki anahtar, sandbox bir komutu çalıştıramadığında ne olacağını kontrol eder: failIfUnavailable, bubblewrap gibi eksik bir bağımlılığın Claude Code'un başlamasını uyarı gösterip sandboxsuz çalışmaya düşmek yerine tamamen engellemesini sağlar; allowUnsandboxedCommands: false ise dangerouslyDisableSandbox kaçış kapısını yok sayar, böylece sandbox altında başarısız olan komutlar dışarıda yeniden denenemez. Buna ek olarak, organizasyon onaylı araçlar için excludedCommands, kimlik bilgisi dizinleri için sandbox.credentials girdileri eklemeniz önerilir — çünkü belirttiğim gibi varsayılan okuma politikası bunları zaten izin verir.

Boolean anahtarlarda (enabled, failIfUnavailable gibi) Claude Code managed değeri kullanır ve geliştiricinin yerel ayarını yok sayar. excludedCommands ve allowRead gibi dizi anahtarlarda ise her kapsamdan gelen girdiler birleştirilir, yani bir geliştirici politikayı genişleten girdiler ekleyebilir. Geliştiricilerin okuma erişimini organizasyon onaylı yolların ötesine genişletmesini engellemek için managed settings'te allowManagedReadPathsOnly'i true yapabilirsiniz; ağ alan adlarını aynı şekilde kilitlemek için allowManagedDomainsOnly kullanılır. excludedCommands için ise böyle bir kilit yoktur — bir geliştirici her zaman sandbox dışında ek komut çalıştıran girdiler ekleyebilir, bu yüzden managed listeyi dar tutmak önemlidir. Windows'ta sandbox çalışmadığından, filodaki Windows makineleri bu politikanın dışında tutulmalı ya da bu kullanıcılar Claude Code'u WSL2 veya bir konteyner içinde çalıştırmalıdır.

Gerçek Örnek: Kubernetes ve Terraform Kullanan Bir Projede Sandbox Kurulumu

Diyelim ki bir DevOps projesinde çalışıyorsunuz; Claude Code'un testleri çalıştırmasını, kubectl ile bir geliştirme kümesini sorgulamasını ve terraform plan çıktısını incelemesini istiyorsunuz — ama SSH anahtarlarınıza ya da AWS kimlik bilgilerinize dokunmasını, ya da GitHub ve npm registry dışındaki alan adlarına bağlanmasını istemiyorsunuz. Projenizin .claude/settings.json dosyasına şunu ekleyebilirsiniz:

{
  "sandbox": {
    "enabled": true,
    "filesystem": {
      "allowWrite": ["~/.kube"]
    },
    "credentials": {
      "files": [
        { "path": "~/.aws/credentials", "mode": "deny" },
        { "path": "~/.ssh", "mode": "deny" }
      ]
    },
    "network": {
      "allowedDomains": ["github.com", "*.github.com", "registry.npmjs.org"]
    },
    "excludedCommands": ["docker *", "terraform *"]
  }
}

Burada ~/.kube'a yazma izni açıkça verilirken, AWS ve SSH kimlik bilgileri okumaya kapatılıyor. Ağ tarafında yalnızca GitHub ve npm registry'ye izin veriliyor; bunun dışındaki her host için Claude Code onay isteyecek (ya da Auto Mode'da sınıflandırıcıya gidecek). docker sandbox ile uyumlu olmadığı ve terraform'un macOS'ta TLS doğrulama sorunları yaşayabildiği için ikisi de excludedCommands ile sandbox dışına alınıyor — yani bu iki komut normal izin akışından geçecek, sandbox sınırından değil. Bu yapılandırmayla /sandbox'ı açıp Mode sekmesinden auto-allow'u seçtiğinizde, Claude testleri çalıştırabilir, kubectl get pods gibi komutları sormadan yürütebilir, ama cat ~/.ssh/id_rsa denemesi ya da tanımadığı bir host'a bağlantı denemesi normal izin akışına düşer.

Sandbox'ın gerçekten devrede olduğunu doğrulamak için Claude'a çalışma dizini dışına yazma denemesi yaptırabilir ya da /sandbox'ın Config sekmesinden geçerli kısıtlamaları gözden geçirebilirsiniz.

Sorun Giderme

Bazı komutlar sandbox dışında çalışırken sandbox içinde başarısız olabilir. En sık karşılaşılan durumlar ve çözümleri:

Sorun	Çözüm
Host izinli değil hatası	İstendiğinde izin verin; host oturum için (ya da "bir daha sorma" ile kalıcı olarak) izinli listeye eklenir.
jest takılıyor veya başarısız oluyor	watchman sandbox ile uyumsuzdur; jest --no-watchman çalıştırın.
macOS'ta Go tabanlı CLI'lar (gh, gcloud, terraform) TLS doğrulamasında başarısız oluyor	Bu araçları excludedCommands'a ekleyin; httpProxyPort ile MITM proxy ve özel CA kullanıyorsanız enableWeakerNetworkIsolation'ı true yapın.
macOS'ta open, osascript veya tarayıcı tabanlı auth akışları -600 hatası veriyor	Sandbox varsayılan olarak Apple Events'i engeller; kullanıcı/managed/CLI ayarlarında allowAppleEvents'i true yapın (kod çalıştırma izolasyonunu kaldırır) ya da komutu excludedCommands'a ekleyin.
docker komutları başarısız oluyor	docker sandbox ile uyumsuzdur; excludedCommands'a docker * ekleyin.
Git komutu unable to unlink old hatası veriyor	git merge/git checkout, sandbox'ın yazmaya izin vermediği bir dosyayı değiştirmeye çalıştığında oluşur (Linux/WSL2'de Read-only file system ile biter). Claude'un sandbox dışında yeniden deneme teklifini onaylayın ya da komutu başka bir terminalde kendiniz çalıştırın.
Konteyner içinde bubblewrap başlatılamıyor	Ayrıcalıksız bir konteynerde bubblewrap taze bir /proc bağlayamaz; dış konteyner zaten yeterli izolasyon sağlıyorsa enableWeakerNestedSandbox'ı true yapın (güvenliği önemli ölçüde zayıflatır).
--dangerously-skip-permissions root olarak başarısız oluyor	Linux/macOS'ta root veya sudo ile bu bayrak engellenir; tanınan bir sandbox içinde kontrol otomatik atlanır. Konteynerde otonom çalıştırmak için root olmayan kullanıcıyla çalışan dev container yapılandırmasını kullanın.

Sınırlamalar

Resmi dokümantasyon açıkça belirtiyor: sandbox riski azaltır ama tam bir izolasyon sınırı değildir. Sert bir güvenlik kontrolü olarak güvenmeden önce şu sınırlamaları göz önünde bulundurmak gerekir:

• Ağ filtrelemesi içerik incelemesi yapmaz. Yerleşik proxy varsayılan olarak TLS'i sonlandırıp incelemez; github.com gibi geniş bir alan adına izin vermek domain fronting gibi tekniklerle veri sızıntısı yollarına açık kalabilir. Daha güçlü garanti isteyen kullanıcılar TLS'i sonlandırıp trafiği inceleyen özel bir proxy kurmalıdır.
• Unix soketleri üzerinden ayrıcalık yükseltme. allowUnixSockets yapılandırması istemeden sistem servislerine erişim verebilir — örneğin /var/run/docker.sock'a izin vermek, Docker soketi üzerinden host sistemine erişim vermek anlamına gelir.
• Dosya sistemi izin yükseltmesi. $PATH üzerindeki çalıştırılabilirleri, sistem yapılandırma dizinlerini ya da .bashrc/.zshrc gibi kabuk yapılandırma dosyalarını içeren dizinlere yazma izni vermek, başka kullanıcılar ya da sistem süreçleri bu dosyalara eriştiğinde farklı bir güvenlik bağlamında kod çalıştırılmasına yol açabilir.
• Linux sandbox gücü. Linux uygulaması güçlü dosya sistemi ve ağ izolasyonu sağlar, ama ayrıcalıksız ad alanlarının devre dışı olduğu Docker ortamlarında veya host'larda çalışmasını sağlayan enableWeakerNestedSandbox modu güvenliği önemli ölçüde zayıflatır ve yalnızca ek izolasyon başka bir katmanda zaten sağlanıyorsa kullanılmalıdır.
• macOS'ta Apple Events. allowAppleEvents kod çalıştırma izolasyonunu kaldırır: sandboxlı komutlar kullanıcı istemi olmadan başka uygulamalar başlatabilir ve çalışan uygulamalara AppleScript komutları gönderebilir (macOS'un TCC izin sistemine tabi).

Kapsam açısından sandbox yalnızca Bash alt süreçlerini izole eder: Read/Edit/Write araçları doğrudan izin sistemi üzerinden çalışır; computer use gerçek masaüstünüzde çalışıp uygulama başına izin istemleriyle kontrol edilir; sandboxlı Bash komutları varsayılan olarak ebeveyn sürecin ortam değişkenlerini (oradaki kimlik bilgileri dahil) miras alır — belirli değişkenleri kaldırmak ya da maskelemek için sandbox.credentials gerekir; alt ajanlar (subagents) ana oturumla aynı süreçte çalıştığı için aynı sandbox yapılandırmasını paylaşır.

Sıkça Sorulan Sorular

Claude Code sandbox'ı hangi işletim sistemlerinde çalışır?

Sandbox macOS, Linux ve WSL2'de çalışır. macOS'ta yerleşik Seatbelt çatısını kullandığı için ek kurulum gerekmez; Linux ve WSL2'de bubblewrap ve socat paketlerinin kurulu olması gerekir. Native Windows desteklenmez — Windows'ta Claude Code'u bir WSL2 dağıtımı içinde çalıştırmanız gerekir. WSL1 de desteklenmez çünkü bubblewrap yalnızca WSL2'nin sunduğu çekirdek özelliklerini kullanabilir.

Sandbox'ı etkinleştirmek izin isteklerini tamamen ortadan kaldırır mı?

Hayır. Sandbox'ın auto-allow modunda bile açık deny kuralları her zaman geçerlidir, rm veya rmdir ile kritik bir yola (dosya sistemi kökü, ev dizini gibi) yönelen komutlar normal izin akışına gider, ve içerik bazlı ask kuralları (ör. Bash(git push *)) sandboxlı komutlar için bile onay istemeye devam eder. Sandbox dışına çıkması gereken komutlar da normal izin akışına düşer ve isteminde "Bash command (unsandboxed)" başlığını taşır.

Sandbox içinde bir komut çalışamazsa ne olur?

Claude Code, sandbox'ın engellediği yolu veya host'u adlandıran bir ihlal raporu döner ve Claude bunu görür. Claude, dangerouslyDisableSandbox parametresiyle komutu sandbox dışında yeniden deneyebilir; bu yeniden deneme normal izin akışına girer (Manual modda onay istemi, Auto Mode'da sınıflandırıcı kararı). allowUnsandboxedCommands ayarı false yapılırsa bu kaçış kapısı tamamen devre dışı kalır ve komutlar ya sandboxlı çalışmak ya da excludedCommands listesinde açıkça yer almak zorundadır.

Sandbox, dosya düzenleme araçlarını (Read/Edit/Write) da mı izole eder?

Hayır. Sandbox yalnızca Bash aracını ve onun alt süreçlerini kapsar. Read, Edit ve Write gibi yerleşik dosya araçları doğrudan izin sistemi üzerinden çalışır, sandbox'tan geçmez. Aynı şekilde computer use ile açılan uygulamalar gerçek masaüstünüzde çalışır ve uygulama başına izin istemleriyle kontrol edilir; alt ajanlar (subagents) ise aynı süreç içinde çalıştığı için ana oturumla aynı sandbox yapılandırmasını miras alır.

Sandbox ağ trafiğini şifre çözerek mi denetler?

Hayır, varsayılan olarak değil. Yerleşik proxy, izin kararını yalnızca istenen host adına bakarak verir ve TLS trafiğini sonlandırıp incelemez; bu yüzden github.com gibi geniş bir alan adına izin vermek domain fronting gibi tekniklerle veri sızıntısına açık bir yol bırakabilir. Deneysel network.tlsTerminate ayarı proxy'nin TLS'i kendisi sonlandırmasını sağlar ama bunun amacı yalnızca mask edilmiş kimlik bilgilerini enjekte etmektir, içerik filtrelemesi eklemez. Daha güçlü bir tehdit modeli için TLS'i sonlandırıp trafiği inceleyen özel bir proxy kurulmalıdır.

Docker ile terraform, gcloud, gh gibi araçlar sandbox içinde çalışır mı?

docker komutları sandbox ile uyumlu değildir ve excludedCommands listesine docker * olarak eklenmesi gerekir. macOS'ta gh, gcloud ve terraform gibi Go tabanlı CLI araçları Seatbelt altında TLS doğrulamasında başarısız olabilir; bu araçlar da excludedCommands ile sandbox dışına alınabilir, ya da bir MITM proxy ve özel CA kullanılıyorsa enableWeakerNetworkIsolation ayarı devreye sokulabilir.

Sandbox'ı gündelik akışınıza oturtmak isterseniz, izin modlarının tam listesini ve Auto Mode'un sınıflandırıcı kararlarını anlattığım Claude Code'da Auto Mode: Sınıflandırıcı Tabanlı İzin Sistemi Rehberi yazısına, sandbox dışındaki araçlar için kendi onay mantığınızı PreToolUse ve PermissionRequest olaylarıyla kurmak isterseniz Claude Code'da Hooks: Olay Tabanlı Otomasyon Rehberi yazısına göz atabilirsiniz.

Özet

Sandbox, Claude Code'un Bash aracına OS düzeyinde bir sınır çizerek onay yorgunluğunu azaltmanın ayrı ve tamamlayıcı bir yoludur: dosya sistemi ve ağ erişimini önceden tanımlarsınız, işletim sistemi bu sınırı model kararından bağımsız olarak zorunlu kılar. /sandbox ile başlamak birkaç saniye sürer; asıl iş, projenize özgü allowWrite/denyRead yollarını ve allowedDomains alan adlarını doğru tanımlamakta, kimlik bilgisi dosyalarını sandbox.credentials ile korumakta, ve sandbox ile uyumsuz araçları (docker, bazı Go tabanlı CLI'lar) bilinçli olarak excludedCommands'a almaktadır. Unutmayın: sandbox bir güvenlik garantisi değil, riski azaltan bir katmandır — etkili olması için hem dosya sistemi hem de ağ izolasyonunun birlikte açık kalması, ve hassas kimlik bilgilerinin varsayılan okuma politikasının ötesinde ayrıca korunması gerekir.