Halaman ini diterjemahkan dari dokumentasi bahasa Inggris. Perintah, pengenal, dan contoh tidak diubah. Runtime 7.24.4 · SDK 2.6.7. Sumber bahasa Inggris

Mode Sandbox

Status: Aktif Cakupan: keadaan saat ini Terakhir ditinjau: 2026-08-23 Pemilik: ax-code runtime

AX Code menyertakan sandbox eksekusi bawaan yang dapat membatasi apa yang dilakukan agen AI di sistem Anda. Secara bawaan, AX Code mulai dalam full-access dengan sandbox mati, jadi penulisan sistem berkas dan akses jaringan tidak dibatasi. Aktifkan workspace-write atau read-only sebelum bekerja dengan repositori yang tidak dipercaya atau menjalankan tugas tanpa pengawasan.

Peringatan keamanan: full-access bukan batas keamanan. Agen dapat mengubah berkas di luar workspace, menulis .git/ dan .ax-code/, menjalankan perintah shell tanpa batas, dan mengakses jaringan.

Mulai cepat

Alihkan sandbox dari TUI:

• Ketik /sandbox di prompt, atau
• Tekan Ctrl+P dan cari “sandbox”

Bilah status menampilkan keadaan saat ini:

• sandbox nyala (hijau) — agen terbatas pada workspace
• sandbox mati (merah) — tanpa pembatasan

Pengaturan bertahan antar sesi di ax-code.json.

Apa yang berubah

Konfigurasi

Sumber kebenaran

Halaman ini merangkum perilaku yang dilihat pengguna. Ketika perilaku berubah, verifikasi dokumen terhadap:

• packages/ax-code/src/isolation/index.ts untuk resolusi mode, jalur terlindungi, pemeriksaan jaringan, pemeriksaan tulis, pemeriksaan bash, dan IsolationDeniedError.
• packages/ax-code/src/config/schema.ts untuk bentuk konfigurasi, bawaan, dan deskripsi.
• packages/ax-code/src/server/routes/isolation.ts untuk perilaku alihan runtime dan persistensi.
• packages/ax-code/test/isolation/isolation.test.ts dan packages/ax-code/test/tool/bash.test.ts untuk perilaku penegakan yang diharapkan.

Jaga klaim yang diduplikasi di README akar agar ringkas dan tautkan kembali ke sini untuk rincian.

Alihkan dari TUI

Gunakan /sandbox atau palet perintah (Ctrl+P → “Nyalakan atau matikan sandbox”). Perubahan berlaku segera dan disimpan ke ax-code.json proyek Anda.

Bendera CLI

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

Variabel lingkungan

AX_CODE_ISOLATION_MODE=workspace-write ax-code

Berkas konfigurasi

Di ax-code.json:

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

Prioritas

Bendera CLI > variabel lingkungan > berkas konfigurasi > bawaan (full-access)

Ketika penimpaan CLI atau lingkungan aktif, TUI melaporkan mode efektif itu. Alihan /sandbox dapat menyimpan preferensi proyek, tetapi penimpaan berprioritas lebih tinggi tetap aktif sampai dihapus (biasanya saat mulai ulang).

Mode isolasi

Jalur terlindungi

Pada mode workspace-write, jalur ini selalu terlindungi dari penulisan:

• .git/ — mencegah kerusakan keadaan git yang tidak disengaja
• .ax-code/ — mencegah perubahan konfigurasi atau plugin

Tambahkan jalur terlindungi khusus di konfigurasi:

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

Akses jaringan

Jaringan dinonaktifkan secara bawaan pada mode workspace-write dan read-only. Alat yang terpengaruh:

• webfetch — diblokir
• websearch — diblokir
• codesearch — diblokir
• bash — klien khusus jaringan (curl, wget, nc/ncat/netcat, telnet, ftp, tftp, scp, sftp, dig, nslookup, host) diblokir

Batasan: Pemblokiran jaringan pada bash berada di lapisan aplikasi dan mencakup klien jaringan khusus di atas. Ia tidak mencegat alat dwiguna yang juga bekerja luring (git, npm/pnpm/yarn, pip, go, interpreter bahasa seperti python/node), karena pemanggilan luring mereka tidak dapat dibedakan secara statis dan memblokirnya akan merusak alur kerja yang umum. Isolasi jaringan yang sungguh lengkap memerlukan kontrol tingkat OS, yang tidak disediakan sandbox ini. Ketika klien yang ditolak terkena, agen meminta eskalasi satu kali.

Untuk mengizinkan jaringan sambil mempertahankan pembatasan penulisan:

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

Backend isolasi (aplikasi versus OS)

macOS: profil Seatbelt melalui sandbox-exec (penulisan terbatas pada workspace/worktree, jaringan ditolak ketika network: false).
Linux: bubblewrap (bwrap) jika terpasang (--unshare-net ketika jaringan dinonaktifkan, workspace diikat RW).
Windows: hanya lapisan aplikasi saat ini.

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

Lihat SECURITY.md untuk model ancaman.

Izin dan hooks yang dikendalikan repositori

Berkas proyek tidak dipercaya secara bawaan. Aturan izin di ax-code.json, .ax-code/policy.json, serta definisi agen atau mode proyek dapat memperketat akses dengan deny, tetapi pemberian allow/ask yang dikendalikan repositori diabaikan. Perintah proyek tidak dapat mengaktifkan ekspansi shell. .ax-code/hooks.json, .ax-code/plugin/, dan plugin yang dikonfigurasi proyek tidak dieksekusi.

Konfigurasi proyek yang tidak dipercaya juga tidak dapat memilih shell khusus, LSP atau pemformat yang dapat dieksekusi, paket penyedia atau titik akhir API, variabel lingkungan kredensial penyedia, sumber skill eksternal, atau jalur instruksi di luar worktree. Jalur instruksi relatif yang aman dan penimpaan bawaan yang tidak dapat dieksekusi tetap tersedia. Server MCP memakai alur persetujuan ber-sidik jari yang terpisah, dijelaskan di Integrasi MCP.

Setelah meninjau konfigurasi yang dikendalikan repositori, pengguna dapat ikut serta di luar repositori untuk proses saat ini:

AX_CODE_TRUST_PROJECT_CONFIG=1 ax-code

Sakelar yang hanya berupa lingkungan mencegah sebuah checkout menyatakan dirinya sendiri tepercaya.

Cara penegakan bekerja

Penegakan sandbox selalu berada di lapisan aplikasi, diperiksa pada setiap pemanggilan alat. Ketika backend adalah os atau auto dan platform mendukungnya, bash tambahan dibungkus dalam sandbox kernel.

Ketika sebuah alat melanggar isolasi, ia melempar IsolationDeniedError dengan pesan yang jelas tentang apa yang diblokir dan mengapa.