Cara Self-Host sandboxd di VPS dengan Docker

Apa itu sandboxd dan manfaat menjalankannya sendiri

Untuk melakukan self-hosting sandboxd, Anda memerlukan satu server Linux dengan Docker dan sebuah nama domain. Anda mengirimkan prompt, lalu coding agent membangun aplikasi nyata di dalam container terisolasi. Aplikasi tersebut kemudian tersedia pada URL pratinjau sendiri. Builder prompt-to-app adalah kategori hosted yang paling banyak dibicarakan pada 2026. sandboxd adalah salah satu builder yang dapat berjalan di VPS Anda, di bawah lisensi MIT, dengan kode yang dihasilkan tersimpan pada disk milik Anda sendiri.

Desainnya sengaja dibuat sederhana. Control plane Go mengendalikan Docker, Traefik v3 merutekan setiap hostname pratinjau, SQLite menyimpan state, dan setiap aplikasi berjalan di dalam satu container. Tidak ada Kubernetes atau server database terpisah. Karena itu, server dengan 2 vCPU tetap dapat menjalankannya.

Empat objek membentuk keseluruhan model. app adalah proyek persisten yang menyimpan nama, metadata git, dan secret. sandbox adalah container Docker tempat app tersebut berjalan. Satu app hanya menunjuk ke satu sandbox pada satu waktu. workspace adalah file milik app yang tersimpan di host dan tetap ada setelah container dihentikan. task adalah satu prompt yang diberikan kepada agent di dalam sandbox. Menghentikan sandbox membebaskan memori dan mempertahankan file. Menghapusnya akan membuang container, dan app tersebut dapat menjalankan sandbox baru.

Perbedaan sandboxd dengan Dify dan OpenHands

Ketiga proyek ini sering tertukar karena semuanya menjalankan LLM (large language model) di server Anda, tetapi hasilnya berbeda. Dify membangun aplikasi LLM: antarmuka chat, pipeline retrieval, dan workflow yang memanggil model setiap kali digunakan. Model merupakan bagian dari produk akhir. OpenHands bekerja pada repository yang sudah Anda miliki: Anda mengarahkannya ke kode, lalu OpenHands membaca file, menjalankan perintah, dan mengusulkan perubahan. sandboxd dimulai tanpa apa pun. sandboxd membuat kerangka project dari preset, membangunnya dalam container baru, lalu memberikan URL untuk dilihat. Hasilnya adalah aplikasi React atau FastAPI biasa yang tidak memerlukan model untuk berjalan.

Jadi, pilih berdasarkan hasil akhir yang Anda inginkan. sandboxd cocok untuk memulai dari sebuah kalimat dan mempertahankan kodenya setelah itu. Dua proyek lainnya cocok jika repository atau produk yang didukung model sudah tersedia.

Perbedaan lainnya adalah usia project. Faktor ini perlu dipertimbangkan sebelum Anda membangun sesuatu yang penting di atasnya.

[
  {
    "tool": "sandboxd",
    "github_stars": "875",
    "forks": "50"
  },
  {
    "tool": "OpenHands",
    "github_stars": "83,091",
    "forks": "10,711"
  },
  {
    "tool": "Dify",
    "github_stars": "151,320",
    "forks": "23,886"
  }
]

sandboxd memiliki 875 bintang, sedangkan OpenHands memiliki 83,091 dan Dify memiliki 151,320. Repository tersebut dibuat pada 3 June 2026, sehingga usianya dua bulan pada August 2026. Sebagai perbandingan, OpenHands berasal dari March 2024 dan Dify dari April 2023. Release v0.1.0 dirilis pada 6 June 2026, sedangkan v0.3.6 dirilis pada 1 August 2026. Project ini menyebut dirinya sebagai beta dan menyatakan bahwa release 0.x dapat memutus kompatibilitas. Anggap angka-angka tersebut sebagai indikator risiko dependensi, bukan sebagai penilaian kualitas: project yang baru berusia dua bulan baru memiliki waktu dua bulan bagi pengguna lain untuk menemukan bug-nya.

Kebutuhan server dan masalah akibat keterbatasan sumber daya

Dokumentasi proyek menyebutkan bahwa 2 vCPU dan 4 GB RAM cukup untuk memulai. Ini benar untuk control plane dan satu sandbox kecil, tetapi tidak cukup untuk dua orang yang melakukan build secara bersamaan. Alokasikan memori berdasarkan komponennya. Traefik dan control plane Go berukuran kecil. Setiap sandbox yang berjalan memuat seluruh toolchain Node atau Python, dan penggunaan puncaknya terjadi saat npm install dilanjutkan dengan production build. Siapkan 8 GB untuk server yang akan menjalankan beberapa aplikasi secara terus-menerus. Anggap swap sebagai jaring pengaman, bukan sebagai pengganti kapasitas memori, karena build yang menggunakan swap memerlukan waktu beberapa menit, bukan beberapa detik.

Saat memori habis, terjadi dua jenis kegagalan yang tampak sangat berbeda. Di dalam sandbox, container mencapai batas --memory yang ditetapkan sandboxd. Kernel kemudian menghentikan proses terbesar, sehingga build berhenti tanpa pesan yang berguna dari agent. docker ps -a menampilkan exit code 137 untuk container tersebut, dan docker inspect pada container itu melaporkan "OOMKilled": true. Build Node yang berhenti dengan cara ini sering kali lebih dahulu menampilkan JavaScript heap out of memory.

Kegagalan kedua terjadi pada host. sandboxd menjalankan pressure reaper yang menghentikan sandbox saat memori host menipis. Akibatnya, pada server kecil, sandbox dapat menghilang saat Anda sedang melihat preview-nya. File tetap aman, dan permintaan berikutnya ke URL preview akan menjalankan sandbox kembali. Namun, task yang sedang berjalan saat container dihentikan tidak dilanjutkan.

Disk adalah masalah yang lebih sulit terlihat. Setiap aplikasi menyimpan workspace sendiri pada host, dan proyek JavaScript membawa tree node_modules berukuran ratusan megabyte. Sepuluh aplikasi memerlukan beberapa gigabyte hanya untuk dependency, sebelum image dihitung. Mulailah dengan 40 GB dan pantau penggunaannya:

docker system df
sudo du -sh /var/lib/sandboxed/workspaces

Direktori data default adalah /var/lib/sandboxed, dengan tambahan e. Jika Anda mengetik /var/lib/sandboxd, Anda akan mendapatkan direktori kosong dan menghabiskan lima menit untuk mencari penyebabnya.

Instal sandboxd dengan rilis yang dikunci versinya

Docker Engine dengan plugin Compose, serta git, harus tersedia di server terlebih dahulu. Instal Docker pada VPS membahas bagian tersebut.

docker compose version
git --version

Keduanya harus menampilkan versi. docker: 'compose' is not a docker command berarti Anda memiliki biner docker-compose standalone lama, sedangkan installer mengharapkan plugin v2.

Installer tersebut adalah skrip shell yang diambil melalui jaringan. Karena itu, baca skrip tersebut sebelum menjalankannya dan kunci versinya.

curl -fsSL https://raw.githubusercontent.com/tastyeffectco/sandboxd/v0.3.6/install.sh -o install-sandboxd.sh
less install-sandboxd.sh
SANDBOXD_REF=v0.3.6 bash install-sandboxd.sh

SANDBOXD_REF adalah referensi git yang diperiksa keluar oleh installer ke dalam $HOME/.sandboxd/src, dan nilai defaultnya adalah main. Jika variabel tersebut dibiarkan tidak disetel, hasil instalasi Anda akan mengikuti apa pun yang digabungkan pada pagi itu. Hal ini penting pada proyek yang merilis enam versi hanya selama Juli 2026. Kunci versinya, lalu lakukan upgrade secara sengaja setelah membaca changelog.

Skrip tersebut meng-clone source code, membangun image, menjalankan stack dengan docker compose up -d, lalu menampilkan URL console dan token API pada bagian akhir. Simpan token tersebut di tempat yang aman. Token itu adalah kredensial untuk API yang menjalankan Docker sebagai root.

curl http://127.0.0.1:9090/healthz

Perintah tersebut menampilkan ok ketika control plane sudah aktif. Jika tidak menampilkan apa pun, stack belum berjalan. Jalankan docker compose ps dari ~/.sandboxd/src untuk melihat service yang berhenti, lalu jalankan docker compose logs sandboxd untuk mengetahui penyebabnya.

Mengakses konsol pada server jarak jauh

Konsol disediakan melalui Traefik pada HTTP_PORT, yang secara default menggunakan port 80, dengan hostname http://console.localhost. Traefik melakukan routing berdasarkan hostname. Karena itu, jika Anda memasukkan alamat IP server ke browser, tidak ada aturan yang cocok dan Traefik mengembalikan 404. Sebelum menetapkan domain yang sebenarnya, teruskan port tersebut dan pertahankan hostname:

ssh -L 8080:127.0.0.1:80 you@your-vps

Kemudian buka http://console.localhost:8080 di laptop Anda. Pada Linux dan macOS, nama apa pun yang diakhiri dengan .localhost akan diarahkan ke 127.0.0.1. Dengan demikian, permintaan melewati tunnel dengan header Host yang benar. Tetapkan kata sandi konsol saat pertama kali mengaksesnya.

Berikan model kepada agent

Dua coding agent tersedia dalam base image: OpenCode dan Claude Code. SANDBOXD_DEFAULT_AGENT menentukan agent yang menjalankan tugas jika tugas tersebut tidak menyebutkan agent tertentu, dan nilai bawaannya adalah opencode. Jika tidak ada key yang terhubung, tugas dijalankan pada model gratis tanpa key dari OpenCode Zen. Dengan demikian, build pertama tidak memerlukan biaya dan Anda dapat menguji seluruh alur sebelum mengeluarkan biaya.

Hubungkan key Anda sendiri jika memerlukan model yang lebih kuat. Key dikirim ke control plane, bukan ke sandbox. Key disimpan dalam keadaan terenkripsi di bawah data directory dan disisipkan saat komunikasi berlangsung oleh credential proxy. Dengan demikian, agent maupun kode yang ditulisnya tidak dapat membaca key tersebut.

export API=http://127.0.0.1:9090
export SANDBOXD_TOKEN=sk_...                       # printed by the installer
export AUTH="Authorization: Bearer $SANDBOXD_TOKEN"

curl -s -XPOST $API/v1/agents/claude-code/api-key -H "$AUTH" \
  -H 'content-type: application/json' \
  -d '{"api_key":"sk-ant-..."}'

Console menyediakan pengaturan yang sama di Settings, AI Agents, termasuk alur OAuth terpandu jika Anda ingin menggunakan langganan Claude sebagai pengganti API key. Model default untuk setiap agent berada di panel yang sama, dan satu tugas dapat menggantinya.

Membangun satu aplikasi kecil dari awal hingga selesai

Buat aplikasi, jalankan sandbox-nya, lalu kirim prompt. ID dikembalikan dalam format JSON, dan quickstart mengambilnya dengan sed sehingga Anda tidak perlu menginstal jq.

APP=$(curl -s -XPOST $API/v1/apps -H "$AUTH" \
  -H 'content-type: application/json' \
  -d '{"name":"todo","runtime_preset":"react-vite"}' \
  | sed -E 's/.*"id":"([^"]+)".*/\1/')

SB=$(curl -s -XPOST $API/v1/apps/$APP/sandbox -H "$AUTH" \
  -H 'content-type: application/json' -d '{"ports":[3000]}' \
  | sed -E 's/.*"id":"([^"]+)".*/\1/')

echo "app=$APP sandbox=$SB"

Kedua variabel harus berisi ID. $SB yang kosong berarti sandbox tidak pernah berhasil dijalankan. Penyebab yang paling umum adalah base image masih dalam proses build atau host kehabisan memori. 401 sebagai pengganti ID berarti bearer token salah.

curl -s -XPOST $API/v1/sandboxes/$SB/tasks -H "$AUTH" \
  -H 'content-type: application/json' \
  -d '{"prompt":"Add a todo list with a text input, an add button, and a delete button on each row. Keep the list in localStorage.","agent":"opencode"}'

Respons tersebut berisi task ID. GET /v1/sandboxes/$SB/tasks/<task id> mengembalikan hasilnya, sedangkan path /events pada task yang sama adalah stream SSE (server sent events) langsung yang menampilkan aktivitas agent. Console menampilkan stream yang sama dalam bentuk chat.

Aplikasi kemudian tersedia di http://s-<sandbox id>-3000.preview.localhost, dengan 3000 sebagai port yang Anda minta. Jika sandbox sedang tidur, request pertama masuk ke catch-all milik Traefik. sandboxd memulai container, menunggu hingga port merespons, lalu menampilkan halaman pemuatan singkat yang melakukan refresh ke aplikasi Anda. Preview yang tidak pernah beranjak dari halaman tersebut berarti proses di dalam container tidak listen pada port yang dideklarasikan dalam sandbox.yaml aplikasi.

Pasang pratinjau pada domain nyata dengan HTTPS

Setiap sandbox mendapatkan hostname sendiri, sehingga satu record DNS wildcard mencakup semuanya. Arahkan *.preview.yourdomain.com ke alamat IP server menggunakan record A. Kemudian tetapkan variabel pratinjau di .env dalam ~/.sandboxd/src:

PREVIEW_DOMAIN=yourdomain.com
PREVIEW_ENTRYPOINT=websecure
PREVIEW_TLS=true
SANDBOXD_API_AUTH_DISABLED=false

Traefik memerlukan konfigurasi yang sesuai: aktifkan entrypoint websecure di traefik/traefik.yml dan tambahkan certificate resolver. Gunakan challenge DNS-01 karena satu sertifikat wildcard dapat mencakup semua hostname pratinjau. Dengan HTTP-01, setiap sandbox baru harus menjalani penerbitan sertifikat sendiri. Sesi build yang sibuk dapat langsung mencapai batas rate Let's Encrypt. Sertifikat wildcard melalui challenge DNS-01 menjelaskan konfigurasi DNS tersebut.

cd ~/.sandboxd/src
docker compose up -d

URL pratinjau menjadi https://s-<id>-3000.preview.yourdomain.com. Buka port 80 dan 443 pada firewall, dan biarkan port 9090 tertutup dari jaringan publik: lihat aturan dasar firewall ufw. Ingat, siapa pun yang dapat menebak hostname pratinjau dapat memuat aplikasi tersebut. Perlakukan pratinjau sebagai layanan publik.

Di mana kode yang dihasilkan disimpan, dan apakah kode tersebut dapat diekspor?

Di host, di bawah direktori data. Setiap workspace berupa direktori biasa di /var/lib/sandboxed/workspaces/<id>/ yang di-bind mount ke dalam container, sedangkan file aplikasi berada di /home/sandbox/workspace/app di dalam sandbox. State control plane disimpan dalam satu file SQLite di state/sandboxd.db, dan kredensial agent yang dienkripsi berada di agent-auth/. Tidak ada data yang tersembunyi di dalam layer container, sehingga pencadangan cukup dilakukan dengan menyalin direktori tersebut beserta file database. pencadangan restic pada VPS menangani keduanya.

sudo ls /var/lib/sandboxed/workspaces
sudo du -sh /var/lib/sandboxed/workspaces/*

Fitur ekspor Git sudah tersedia secara bawaan, bukan tambahan terpisah. API menyediakan status dan diff untuk dibaca, kemudian commit dan push:

curl -s $API/v1/apps/$APP/git/status -H "$AUTH"

curl -s -XPOST $API/v1/apps/$APP/git/commit -H "$AUTH" \
  -H 'content-type: application/json' \
  -d '{"message":"todo list, first pass"}'

curl -s -XPOST $API/v1/apps/$APP/git/push -H "$AUTH" \
  -H 'content-type: application/json' -d '{"branch":"main"}'

Remote privat memerlukan personal access token yang diatur sekali di console melalui Settings, Git credentials. Token tersebut disimpan dalam bentuk terenkripsi dan tetap berada di luar sandbox, sehingga agent tidak dapat membacanya atau menggunakannya untuk melakukan push tanpa sepengetahuan Anda. Lakukan push sejak awal dan secara berkala. Sebelum itu dilakukan, direktori workspace adalah satu-satunya salinan kode, dan DELETE /v1/apps/<id> akan menghapusnya tanpa kesempatan kedua.

Berapa biaya build dalam token model?

sandboxd tidak mengukur pengeluaran Anda, jadi angka yang penting ada di konsol provider Anda. Model OpenCode Zen gratis tidak berbayar, tetapi lebih lambat dan kurang andal dibandingkan model berbayar. Perbedaannya terlihat dari lebih banyaknya putaran koreksi untuk pekerjaan yang lebih kompleks daripada aplikasi sederhana.

Bentuk tagihan mengikuti cara kerja loop agen. Setiap giliran mengirim ulang konteks yang diperlukan. Karena itu, biaya bergantung pada jumlah giliran, bukan jumlah aplikasi. Satu prompt yang langsung berhasil biayanya rendah. Lima belas putaran berisi permintaan seperti "sekarang perbaiki jaraknya" pada proyek dengan lima puluh file tidak demikian, karena isi file dikirim ulang setiap kali. Token input dan output memiliki harga yang berbeda, dan biaya agen coding per sesi memberikan kisaran yang realistis. Tetapkan batas pengeluaran yang ketat pada provider sebelum Anda memberikan kredensial kepada loop yang berjalan tanpa pengawasan.

Membersihkan sandbox yang kedaluwarsa

Idle reaper menghentikan setiap sandbox yang tidak aktif selama lebih dari SANDBOXD_IDLE_THRESHOLD_SECONDS, yang secara default adalah 2100 detik atau 35 menit. Tindakan ini mengembalikan RAM, tetapi file tetap disimpan. Permintaan berikutnya ke URL pratinjau akan membangunkan container. Kurangi nilai ini pada server kecil, karena container yang tidak aktif selama 35 menit berarti memori yang tidak dapat digunakan selama 35 menit.

Menghentikan sandbox tidak sama dengan menghapusnya. Pada tahap inilah disk dapat terisi tanpa disadari. Sandbox yang dihentikan masih memiliki workspace dan container-nya. Menghapus sandbox, tetapi mempertahankan aplikasinya, adalah DELETE pada sandbox. Tindakan ini juga menghapus container dan workspace. Menghapus aplikasi akan menghapus semuanya secara permanen.

curl -s -XPOST $API/v1/sandboxes/$SB/stop -H "$AUTH"     # frees RAM, keeps files
curl -s -XDELETE $API/v1/sandboxes/$SB -H "$AUTH"        # container and workspace gone
curl -s -XDELETE $API/v1/apps/$APP -H "$AUTH"            # app and everything under it

Setelah beberapa minggu melakukan eksperimen, docker system df akan menampilkan ruang image yang dapat direklamasi lebih banyak dari perkiraan. Setiap aplikasi yang mengunduh toolchain-nya sendiri meninggalkan layer. docker image prune membersihkan layer yang tidak lagi memiliki referensi. Periksa GET /v1/apps terlebih dahulu, karena image yang masih direferensikan oleh sandbox yang sedang tidur bukanlah garbage.

Batas container memberikan dan tidak memberikan apa

Setiap sandbox berjalan sebagai pengguna tanpa hak istimewa dengan root filesystem hanya-baca, seluruh kapabilitas Linux dihapus, no-new-privileges ditetapkan, serta memiliki batas memori dan batas proses. Proyek ini secara terbuka menjelaskan batas tersebut: container Linux dengan kernel bersama merupakan batas isolasi yang kuat, tetapi batas keamanan yang lemah. Kerentanan pada kernel dapat menyebabkan host terbobol.

Dua hal memerlukan tindakan. Egress jaringan dari sandbox terbuka pada build self-hosted, sehingga kode yang dibuat dapat mengakses Internet, jaringan lokal Anda, dan endpoint metadata cloud. Subsistem egress nftables tersedia dalam source, tetapi dinonaktifkan saat build Docker Compose portabel dikompilasi. Artinya, pembatasan harus berasal dari firewall host Anda. Selain itu, API control plane pada dasarnya memiliki hak root pada host karena mengendalikan Docker socket. API tersebut secara default melakukan bind ke 127.0.0.1:9090, SANDBOXD_API_AUTH_DISABLED harus tetap false, dan API tersebut tidak boleh dipublikasikan ke Internet.

Jika Anda berencana mengizinkan orang lain mengirim prompt ke server Anda, model ini terlalu lemah jika digunakan sendiri. Proyek tersebut mengarahkan pengguna ke gVisor dengan SANDBOXD_RUNTIME=runsc. gVisor menempatkan kernel ruang pengguna di antara sandbox dan host, dengan konsekuensi pekerjaan yang banyak melakukan syscall menjadi sekitar 1.7 hingga 4 kali lebih lambat. Pilihan yang lebih kuat adalah menggunakan satu mesin untuk setiap tenant. Argumennya sama seperti menjalankan coding agent dalam VM sekali pakai.

Haruskah Anda membangun di atas proyek yang baru berusia dua bulan?

Untuk server build pribadi, ya, dengan tindakan pencegahan yang wajar: kunci SANDBOXD_REF, buat cadangan /var/lib/sandboxed, dan push setiap aplikasi yang penting bagi Anda ke remote git. Untuk apa pun yang digunakan pelanggan, tunggu versi 1.0 atau siapkan anggaran untuk kerusakan, karena pengelola menyatakan dengan jelas bahwa 0.x dapat berubah tanpa kompatibilitas ke belakang. Pengelola juga menawarkan instalasi terkelola seharga 79 dolar per bulan per Agustus 2026. Hal ini perlu diketahui saat Anda menilai apakah proyek tersebut memiliki alasan untuk terus dipertahankan.

Risiko ini dapat ditoleransi karena hasilnya. sandboxd menghasilkan aplikasi biasa dalam repositori git biasa. Jadi, jika pengembangan proyek terhenti, Anda tetap memiliki kode dan hanya kehilangan wrapper. Posisi ini jauh lebih baik daripada builder hosted yang mengendalikan proyek Anda. Untuk gambaran yang lebih luas tentang hal yang layak di-self-host pada tahun ini, lihat apa yang layak di-self-host pada 2026.

FAQ

Apa spesifikasi minimum server untuk sandboxd?

Proyek ini menyatakan bahwa 2 vCPU dan 4 GB RAM cukup untuk memulai. Spesifikasi tersebut mencakup control plane, Traefik, dan satu sandbox kecil. Gunakan 8 GB RAM dan disk 40 GB jika ingin menjalankan beberapa aplikasi sekaligus. Setiap sandbox yang berjalan menyimpan toolchain Node atau Python lengkap, dan setiap workspace menyimpan pohon dependensinya sendiri di disk. Jika resource host tidak mencukupi, pressure reaper milik sandboxd akan menghentikan sandbox untuk membebaskan memori. Build yang melampaui batas memori containernya akan dihentikan oleh kernel: docker ps -a menampilkan exit code 137 untuk proses tersebut.

Apa perbedaan sandboxd dengan Dify atau OpenHands?

Ketiganya menghasilkan artefak yang berbeda. Dify membuat aplikasi yang memanggil model saat runtime, seperti antarmuka chat dan pipeline retrieval. OpenHands mengedit repository yang sudah Anda miliki, menjalankan perintah, dan mengusulkan perubahan pada kode yang ada. sandboxd membuat kerangka proyek baru dari prompt, melakukan build di dalam containernya sendiri, lalu menyajikannya pada URL pratinjau. Hasilnya adalah aplikasi web biasa yang tidak memerlukan model untuk berjalan.

Di mana kode yang ditulis agent sebenarnya disimpan?

Kode tersebut disimpan pada filesystem host, bukan di dalam image container. Setiap aplikasi memiliki direktori di /var/lib/sandboxed/workspaces/<id>/ yang di-bind mount ke sandbox-nya, dan file tersebut terlihat di /home/sandbox/workspace/app dari dalam sandbox. State control plane disimpan dalam satu file SQLite di bawah state/ pada direktori data yang sama. Anda dapat melakukan commit dan push ke remote git dari tab Git di console atau melalui endpoint /v1/apps/<id>/git/commit dan /git/push. Token untuk remote privat disimpan dalam bentuk terenkripsi oleh control plane, bukan diberikan kepada sandbox.

Apakah aman mengekspos sandboxd ke Internet?

Ekspos URL pratinjau dan console, tetapi jangan mengekspos API control plane. API tersebut mengendalikan Docker pada host, sehingga setara dengan akses root. Karena alasan itu, API tersebut secara default melakukan binding pada 127.0.0.1:9090. Sandbox juga memiliki egress jaringan terbuka pada build self-hosted. Artinya, kode yang ditulis agent dapat mengakses jaringan lokal dan endpoint metadata cloud Anda. Tambahkan aturan firewall host jika server tersebut memiliki sistem lain di sekitarnya yang perlu dilindungi. Untuk prompt dari pengguna yang tidak Anda percayai, gunakan satu host untuk setiap tenant, bukan hanya mengandalkan batas container.