Bu sayfa İngilizce belgenin çevirisidir. Komutlar, tanımlayıcılar ve örnekler aynıdır. Çalışma zamanı 7.24.4 · SDK 2.6.7. İngilizce kaynak

Sandbox modu

Durum: Etkin Kapsam: güncel durum Son inceleme: 2026-08-23 Sahip: ax-code runtime

AX Code, yapay zekâ ajanının sisteminizde ne yapabileceğini kısıtlayabilen yerleşik bir yürütme sandbox’ı içerir. Varsayılan olarak AX Code sandbox kapalı tam erişim ile başlar; dosya sistemi yazmaları ve ağ erişimi sınırsızdır. Güvenilmeyen depolarla çalışmadan veya gözetimsiz görevler çalıştırmadan önce workspace-write veya read-only açın.

Güvenlik uyarısı: full-access bir güvenlik sınırı değildir. Ajan çalışma alanı dışında dosya değiştirebilir, .git/ ve .ax-code/ yazabilir, sınırsız kabuk komutları çalıştırabilir ve ağa erişebilir.

Hızlı başlangıç

TUI içinden sandbox’ı değiştirin:

• İsteme /sandbox yazın veya
• Ctrl+P tuşuna basın ve «sandbox» arayın

Durum çubuğu güncel durumu gösterir:

• sandbox açık (yeşil) — ajan çalışma alanına kapatılır
• sandbox kapalı (kırmızı) — kısıtlama yok

Ayar ax-code.json içinde oturumlar boyunca kalır.

Neler değişir

Yapılandırma

Doğruluk kaynağı

Bu sayfa kullanıcıya dönük davranışı özetler. Davranış değiştiğinde belgeleri şunlara karşı doğrulayın:

• packages/ax-code/src/isolation/index.ts: kip çözümlemesi, korunan yollar, ağ denetimleri, yazma denetimleri, bash denetimleri ve IsolationDeniedError.
• Yapılandırma biçimi, varsayılanlar ve açıklamalar için packages/ax-code/src/config/schema.ts.
• Çalışma zamanı değiştirme davranışı ve kalıcılık için packages/ax-code/src/server/routes/isolation.ts.
• Beklenen uygulama davranışı için packages/ax-code/test/isolation/isolation.test.ts ve packages/ax-code/test/tool/bash.test.ts.

Yinelenen iddiaları kök README’de kısa tutun ve ayrıntı için buraya bağlayın.

TUI içinden değiştirme

/sandbox veya komut paletini kullanın (Ctrl+P → «Sandbox’ı aç veya kapat»). Değişiklik hemen yürürlüğe girer ve projenizin ax-code.json dosyasına kaydedilir.

CLI bayrağı

ax-code --sandbox workspace-write   # sandbox on
ax-code --sandbox full-access       # sandbox off
ax-code --sandbox read-only         # strictest: blocks all mutations

Ortam değişkeni

AX_CODE_ISOLATION_MODE=workspace-write ax-code

Yapılandırma dosyası

ax-code.json içinde:

{
  "isolation": {
    "mode": "workspace-write",
    "network": false
  }
}

Öncelik

CLI bayrağı > ortam değişkeni > yapılandırma dosyası > varsayılan (full-access)

Bir CLI veya ortam geçersiz kılması etkinken TUI etkin kipi bildirir. Bir /sandbox değiştirmesi proje tercihini kaydedebilir ama daha yüksek öncelikli geçersiz kılma kaldırılana kadar etkin kalır (normalde yeniden başlatmada).

Yalıtım kipleri

Korunan yollar

workspace-write kipinde bu yollar her zaman yazmaya karşı korunur:

• .git/ — yanlışlıkla git durumu bozulmasını önler
• .ax-code/ — yapılandırma ve eklenti kurcalamasını önler

Yapılandırmada özel korunan yollar ekleyin:

{
  "isolation": {
    "mode": "workspace-write",
    "protected": ["secrets", "credentials"]
  }
}

Ağ erişimi

Ağ, workspace-write ve read-only kiplerinde varsayılan olarak kapalıdır. Etkilenen araçlar:

• webfetch — engelli
• websearch — engelli
• codesearch — engelli
• bash — yalnızca ağ istemcileri (curl, wget, nc/ncat/netcat, telnet, ftp, tftp, scp, sftp, dig, nslookup, host) engellenir

Sınırlama: bash içinde ağ engelleme uygulama katmanındadır ve yukarıdaki adanmış ağ istemcilerini kapsar. Çevrimdışı da çalışan çift kullanımlı araçları kesmez (git, npm/pnpm/yarn, pip, go, python/node gibi dil yorumlayıcıları), çünkü çevrimdışı çağrıları durağan olarak ayırt edilemez ve onları engellemek yaygın iş akışlarını bozar. Gerçek, kapsamlı ağ yalıtımı bu sandbox’ın sağlamadığı işletim sistemi düzeyi denetimler gerektirir. Reddedilen bir istemciye çarpıldığında ajan tek seferlik bir yükseltme ister.

Yazma kısıtlarını korurken ağa izin vermek için:

{
  "isolation": {
    "mode": "workspace-write",
    "network": true
  }
}

Yalıtım arka ucu (uygulama ve işletim sistemi)

macOS: sandbox-exec üzerinden Seatbelt profilleri (yazma çalışma alanı ve worktree ile sınırlı, network: false olduğunda ağ reddedilir).
Linux: kuruluysa bubblewrap (bwrap) (ağ kapalıyken --unshare-net, çalışma alanı RW olarak bağlanır).
Windows: bugün yalnızca uygulama katmanı.

{
  "isolation": {
    "mode": "workspace-write",
    "network": false,
    "backend": "auto"
  }
}

Tehdit modeli için SECURITY.md sayfasına bakın.

Depo denetimli izinler ve kancalar

Proje dosyaları varsayılan olarak güvenilmez. ax-code.json, .ax-code/policy.json ve proje ajanı veya kip tanımlarındaki izin kuralları deny ile erişimi sıkılaştırabilir, ancak depo denetimli allow/ask bağışları yok sayılır. Proje komutları kabuk genişletmesini açamaz. .ax-code/hooks.json, .ax-code/plugin/ ve proje yapılandırmalı eklentiler yürütülmez.

Güvenilmeyen proje yapılandırması ayrıca özel bir kabuk, yürütülebilir LSP veya biçimlendirici, sağlayıcı paketi veya API uç noktası, sağlayıcı kimlik bilgisi ortam değişkenleri, dış beceri kaynağı ya da worktree dışındaki bir yönerge yolu seçemez. Güvenli göreli yönerge yolları ve yürütülebilir olmayan yerleşik geçersiz kılmalar kullanılabilir kalır. MCP sunucuları MCP bütünleştirmeleri içinde anlatılan ayrı parmak izli bir onay akışı kullanır.

Depo denetimli yapılandırmayı inceledikten sonra kullanıcılar güncel süreç için depo dışında katılabilir:

AX_CODE_TRUST_PROJECT_CONFIG=1 ax-code

Yalnızca ortam anahtarı, bir kopyanın kendini güvenilir ilan etmesini engeller.

Uygulama nasıl çalışır

Sandbox uygulaması her zaman uygulama katmanındadır ve her araç çağrısında denetlenir. backend değeri os veya auto olduğunda ve platform desteklediğinde bash ayrıca bir çekirdek sandbox’ına sarılır.

Bir araç yalıtımı ihlal ettiğinde neyin neden engellendiğini açıklayan açık bir iletiyle IsolationDeniedError fırlatır.