Tutorial Sandcat: Docker Devcontainer untuk AI Coding Agent yang Aman
KR
Kevin Ray

Dipublikasikan 16 Juni 2026

Tutorial Sandcat: Docker Devcontainer untuk AI Coding Agent yang Aman

vibe-coding
docker
docker
security
tutorial

Sandcat adalah tool open source dari VirtusLab yang dirancang untuk menjalankan AI coding agent secara aman dalam isolated Docker devcontainer. Dengan semakin banyaknya developer yang menggunakan vibe coding dan agentic workflows di production environment, keamanan menjadi concern utama yang tidak bisa ditunda. Agent AI bisa saja mengeksekusi perintah berbahaya, mengakses secret yang sensitif, atau melakukan network request ke endpoint yang tidak diinginkan. Sandcat hadir sebagai solusi komprehensif untuk menangani masalah keamanan ini tanpa mengorbankan produktivitas.

Dalam tutorial lengkap ini, kita akan membahas cara setup Sandcat di proyek kamu, mengkonfigurasi network filtering dengan mitmproxy, dan mengamankan secret dengan transparent proxy. Semua langkah menggunakan Docker Compose dan devcontainer, sehingga compatible dengan VS Code, GitHub Codespaces, dan environment containerized lainnya. Tidak diperlukan pengetahuan deep security karena Sandcat mengabstraksi kompleksitas di balik CLI yang sederhana.

Mengapa Agent AI Membutuhkan Sandbox

AI coding agent seperti Claude Code, Aider, atau OpenCode memiliki kemampuan mengeksekusi shell command secara otomatis berdasarkan interpretasi instruksi dari model bahasa. Meskipun fitur ini sangat membantu untuk otomatisasi, risikonya tidak bisa dianggap remeh. Agent bisa secara tidak sengaja menghapus database production, mengirimkan secret ke server eksternal, atau menginstall dependency berbahaya dari registry yang tidak terpercaya.

Sandcat mengatasi masalah ini dengan tiga lapisan pertahanan yang bekerja secara bersamaan: sandboxed container yang membatasi akses filesystem host, controlled network access via transparent mitmproxy, dan secret substitution yang menyembunyikan credential asli dari container. Container tidak pernah melihat nilai secret asli karena proxy melakukan injeksi secara transparent di level network.

Persiapan Environment

Sebelum memulai setup Sandcat, pastikan kamu memiliki environment yang memenuhi prasyarat berikut:

  • Docker Engine dan Docker Compose yang sudah terinstal dan berjalan dengan baik

  • VS Code dengan extension Dev Containers yang sudah diaktifkan

  • yq dalam versi Go dari Mike Farah (penting: bukan Python variant kislyuk/yq)

  • Proyek yang ingin di-sandbox, minimal sudah memiliki struktur direktori dan dependency file

Untuk pengguna macOS, Colima direkomendasikan sebagai Docker runtime alternatif Docker Desktop. Pada Linux, pastikan Docker socket dapat diakses oleh user biasa tanpa root, atau tambahkan user ke grup docker. Pengguna Windows dengan WSL2 juga bisa menggunakan setup ini dengan sedikit penyesuaian path.

Langkah 1: Instalasi Sandcat CLI

Sandcat menyediakan CLI yang bisa dijalankan sebagai Docker image atau diinstal secara lokal. Metode Docker image sangat direkomendasikan karena tidak memerlukan dependensi tambahan di host dan selalu menggunakan versi terbaru.

Tambahkan alias berikut ke file .bashrc atau .zshrc agar command sandcat bisa diakses dari mana saja:

alias sandcat='docker run --rm -it -v /var/run/docker.sock:/var/run/docker.sock -v "$PWD:$PWD" -v "$HOME/.config/sandcat:$HOME/.config/sandcat" -w "$PWD" -e TERM -e HOME ghcr.io/virtuslab/sandcat'

Alias ini mem-mount Docker socket, direktori kerja saat ini, dan direktori konfigurasi Sandcat. Setelah alias aktif, verifikasi instalasi dengan menjalankan:

sandcat --help

Jika output menampilkan daftar command yang tersedia seperti init, start, dan stop, berarti CLI siap digunakan. Alternatifnya, clone repository Sandcat dari GitHub dan tambahkan direktori cli/bin ke PATH untuk instalasi lokal.

Langkah 2: Inisialisasi Sandbox untuk Proyek

Navigasi ke root proyek yang ingin diisolasi dan jalankan perintah init:

cd /path/to/project
sandcat init

CLI akan mengajukan beberapa pertanyaan interaktif: tipe agent yang digunakan, IDE yang dipilih, dan stack development. Kamu juga bisa mempersingkat proses dengan flag non-interaktif:

sandcat init --agent claude --ide vscode --stacks "python,node"

Stack yang tersedia meliputi: node, python, java, rust, go, scala, ruby, dotnet, dan zig. Versi default mengikuti LTS masing-masing. File yang dihasilkan meliputi .devcontainer/Dockerfile.app untuk aplikasi, compose-all.yml untuk orkestrasi, dan devcontainer.json untuk konfigurasi VS Code.

Untuk integrasi dengan 1Password sebagai secret provider, tambahkan flag --secret-provider 1password. Ini memungkinkan proxy mengambil credential dari vault 1Password secara dinamis tanpa menyimpan secret di file konfigurasi proyek.

Langkah 3: Memahami Arsitektur Network Filtering

Sandcat menggunakan transparent mitmproxy yang dirutekan melalui WireGuard tunnel. Semua traffic HTTP, HTTPS, DNS, dan TCP/UDP dari container melewati proxy tanpa perlu konfigurasi proxy per-tool atau environment variable tambahan.

Engine filtering berbasis allowlist dan denylist mengontrol request mana yang boleh lewat. Konfigurasi ini ditempatkan di file .devcontainer/sandcat/scripts/. Kamu bisa menambahkan domain yang diizinkan atau diblokir sesuai kebutuhan proyek dengan syntax sederhana.

Misalnya, untuk membatasi agent hanya bisa mengakses GitHub dan npm registry:

ALLOWLIST="github.com,registry.npmjs.org"

Request ke domain di luar allowlist akan di-drop secara otomatis oleh proxy. Ini mencegah agent mengirimkan data ke endpoint yang tidak dikenal atau berbahaya.

Langkah 4: Konfigurasi Secret Substitution

Secret substitution adalah fitur andalan Sandcat yang menggantikan placeholder di request dengan nilai asli dari secret provider. Container hanya melihat placeholder seperti OPENCODE_API_KEY, bukan nilai sebenarnya yang seharusnya rahasia.

Setup dilakukan di level proxy melalui file compose-proxy.yml. Proxy menangkap header atau body yang mengandung placeholder dan menggantinya dengan secret dari 1Password atau file konfigurasi. Proses ini terjadi di luar container, sehingga agent tidak bisa mengakses secret meskipun mencoba membacanya dari environment variable.

Contoh konfigurasi dengan file env sederhana:

SANDCAT_SECRET_PROVIDER=env
SANDCAT_SECRET_FILE=/run/secrets/.env

Dengan arsitektur ini, bahkan jika agent mencoba mengekspos API key melalui log atau network request, nilai yang terlihat hanyalah placeholder. Ini memberikan lapisan perlindungan tambahan yang tidak tersedia di setup AI agent standar.

Langkah 5: Menjalankan Devcontainer dengan Sandcat

Setelah konfigurasi selesai, buka VS Code di root proyek dan pilih opsi Reopen in Container. VS Code akan membangun image aplikasi dan proxy, lalu menghubungkan keduanya melalui Docker Compose sesuai file yang dihasilkan.

Terminal di VS Code sekarang berjalan dalam sandbox yang terisolasi. Setiap command yang dieksekusi oleh agent akan melalui filtering dan secret substitution. Kamu bisa memverifikasi dengan menjalankan:

curl -v https://example.com

Request ke domain yang tidak ada di allowlist akan menghasilkan error connection refused atau proxy error. Ini membuktikan bahwa network filtering berfungsi dengan baik.

Best Practice untuk Production

Berikut rekomendasi tambahan saat menggunakan Sandcat di environment tim atau production:

  • Gunakan allowlist yang sesempit mungkin, hanya domain yang benar-benar diperlukan proyek

  • Integrasikan dengan secret provider enterprise seperti 1Password atau HashiCorp Vault

  • Review log mitmproxy secara berkala untuk mendeteksi anomali atau percobaan akses tidak sah

  • Enkripsi volume Docker yang menyimpan secret file dengan LUKS atau Docker Volume encryption

  • Update Sandcat secara rutin untuk mendapatkan patch keamanan terbaru

Dengan setup Sandcat, tim kamu bisa menikmati produktivitas vibe coding tanpa mengorbankan keamanan infrastruktur. Dokumentasi lengkap dan issue tracker tersedia di repository GitHub Sandcat.