7.4 Sandboxes & Browser

Tujuan bab

Setelah bab ini kamu bisa:

• Memberi agent lingkungan kerja terisolasi dengan Workspace dan LocalSandbox
• Menjelaskan perbedaan sandbox dan filesystem, serta kapan butuh keduanya
• Menyebutkan risiko keamanan LocalSandbox dan cara menguranginya
• Menjelaskan pilihan yang tersedia untuk otomasi peramban
• Memutuskan kapan agent sebenarnya tidak butuh sandbox

Prasyarat

• 7.3 Subagents & Skills

Dua hal berbeda yang sering disamakan

Dokumentasi membedakan dua konsep yang mudah tertukar:

Sandbox adalah lingkungan terisolasi tempat agent bisa menjalankan perintah, mengeksekusi kode, memasang dependensi, dan mengelola proses.

Filesystem adalah tempat agent membaca, menulis, dan mencari berkas — dan yang penting, bisa hidup lebih lama daripada sandbox-nya.

Perbedaan itu berakar pada satu sifat: sandbox sering bersifat sementara. Berkas yang dibuat di dalamnya bisa hilang saat lingkungannya berhenti.

┌─────────────────────────────────┐
│ Sandbox (sering sementara)      │
│  - jalankan perintah            │
│  - eksekusi kode                │
│  - pasang dependensi            │
│  - kelola proses                │
└─────────────────────────────────┘
            │ membaca/menulis
            ▼
┌─────────────────────────────────┐
│ Filesystem (bertahan)           │
│  - simpan keluaran antar run    │
│  - benih untuk sandbox baru     │
│  - dokumen yang bisa dicari     │
└─────────────────────────────────┘

Karena itu filesystem dipakai untuk: menyimpan keluaran antar run, mengisi sandbox baru dengan berkas yang sudah ada, atau memberi agent dokumen yang bisa ia cari sambil bekerja.

Dan filesystem juga bekerja tanpa sandbox — misalnya saat agent hanya butuh basis pengetahuan, atau akses berkas di layanan seperti Google Drive.

Kapan agent tidak butuh sandbox

Dokumentasi menyebutnya langsung, dan ini menghemat banyak kerumitan:

Kalau agent hanya perlu membaca, menulis, atau mencari berkas, konfigurasikan akses filesystem langsung.

Sandbox dibutuhkan saat agent harus:

• Meng-clone repositori dan menjalankan shell, Git, build, atau alur pengujian di lingkungan terpisah
• Memproses PDF, presentasi, atau berkas lain dengan pustaka khusus dan menghasilkan artefak baru
• Menjalankan pekerjaan berumur panjang atau paralel di lingkungan terpisah dengan berkas dan proses yang terisolasi

Kata kuncinya menjalankan. Kalau agent-mu tidak mengeksekusi apa pun, filesystem saja sudah cukup.

Memberi sandbox

// src/mastra/agents/coding-agent.ts
import { Agent } from '@mastra/core/agent'
import { LocalSandbox, Workspace } from '@mastra/core/workspace'

export const codingAgent = new Agent({
  id: 'coding-agent',
  name: 'Coding agent',
  instructions: 'Pakai sandbox untuk menyelesaikan tugas coding.',
  model: 'openai/gpt-5.6-sol',
  workspace: new Workspace({
    sandbox: new LocalSandbox({
      workingDirectory: './workspace',
    }),
  }),
})

await codingAgent.generate('Daftar berkas di direktori sandbox')

Perhatikan susunannya: Workspace adalah pembungkusnya, LocalSandbox adalah isinya. Workspace juga yang menampung filesystem, pencarian, dan workspace skills yang disinggung di 7.3. Sandbox hanya salah satu komponennya.

Perhatikan juga bahwa agent tidak diberi tool apa pun secara eksplisit — kemampuan bekerja dengan berkas dan perintah datang dari workspace.

Peringatan keamanan yang tidak boleh dilewati

Dokumentasi memberi peringatan yang tegas, dan layak dikutip utuh:

LocalSandbox menjalankan perintah di host aplikasi secara default dan tidak terisolasi maupun aman. Aktifkan isolasi native, atau pakai sandbox remote atau container saat menjalankan kode yang tidak tepercaya.

Perhatikan kata "default". LocalSandbox bisa diamankan dengan mengaktifkan isolasi native, tapi kamu harus melakukannya secara sadar.

Apa artinya "tidak terisolasi"

Tanpa isolasi native, perintah yang dijalankan agent berjalan di mesin yang sama dengan aplikasimu, dengan hak akses yang sama. Sebuah agent yang dibujuk menjalankan perintah berbahaya — lewat prompt injection dari dokumen yang ia baca, misalnya — bisa menyentuh apa pun yang bisa disentuh aplikasimu.

Tiga tingkat pengamanan, dari paling lemah ke paling kuat:

1. LocalSandbox apa adanya — hanya untuk kode yang kamu tulis sendiri, di mesin pengembanganmu
2. LocalSandbox dengan isolasi native diaktifkan
3. Sandbox remote atau container — untuk kode yang tidak tepercaya

Kalau agent-mu menjalankan kode yang berasal dari pengguna, dari internet, atau dari repositori yang tidak kamu tinjau, tingkat pertama tidak memadai.

Ini juga relevan dengan proyek Mastra yang kamu buat di Bagian 0 — template standarnya memakai LocalSandbox untuk workspace/, dengan gerbang persetujuan sebelum mengubah berkas atau menjalankan perintah. Gerbang itu ada justru karena isolasinya bukan bawaan.

Kemampuan lain di dalam workspace

Beberapa kemampuan yang tinggal di bawah payung yang sama dan layak kamu ketahui keberadaannya:

Kemampuan	Kegunaan
Filesystem	Baca, tulis, dan mount berkas — dengan atau tanpa sandbox
Search & indexing	Indeks isi berkas atau aplikasi, lalu cari dengan BM25, semantik, atau hibrida
LSP inspection	Memeriksa simbol, definisi, referensi, dan diagnostik lewat Language Server Protocol
Computer	Kontrol tangkapan layar, tetikus, dan papan ketik di sandbox desktop yang mendukung
Skills	Workspace skills yang ditemukan dari sistem berkas

Search patut diperhatikan karena menyediakan tiga mode: BM25 (kata kunci), vektor (semantik), dan hibrida. Bandingkan dengan Bagian 5: di sana kamu membangun pipeline RAG sendiri; di sini pencarian menjadi kemampuan bawaan workspace atas berkas yang ada di dalamnya.

LSP inspection adalah yang membedakan coding agent yang serius dari yang sekadar mengedit teks. Dengan LSP, agent bisa menanyakan "di mana fungsi ini dipakai?" alih-alih menebak lewat pencarian teks.

Otomasi peramban

Sebagian pekerjaan hanya bisa diselesaikan lewat peramban — mengisi formulir, menavigasi aplikasi web, mengambil data dari halaman yang butuh JavaScript.

Mastra menyediakan beberapa jalur untuk ini: penyedia SDK native, tool CLI, koneksi CDP (Chrome DevTools Protocol), atau layanan cloud seperti Browserbase dan Firecrawl.

Pertimbangan memilihnya serupa dengan sandbox:

Jalur	Kapan dipilih
Lokal (SDK, CLI, CDP)	Pengembangan, kendali penuh, tanpa biaya layanan
Cloud (Browserbase, Firecrawl)	Produksi, penskalaan, tanpa mengelola peramban sendiri

Dan peringatan keamanan yang serupa berlaku: peramban yang membuka halaman sembarangan adalah permukaan serangan. Halaman web bisa memuat teks yang dirancang untuk membajak agent yang membacanya.

Menyatukan gambarannya

Kesalahan umum

Gejala: Berkas yang dihasilkan agent hilang saat run berikutnya dimulai. Penyebab: Berkas ditulis ke dalam sandbox, yang sifatnya sementara. Dokumentasi menyebutnya langsung: berkas yang dibuat di dalam sandbox bisa hilang saat lingkungannya berhenti. Perbaikan: Tulis keluaran yang harus bertahan ke filesystem, bukan ke sandbox. Filesystem justru ada untuk kasus ini — menyimpan keluaran antar run dan mengisi sandbox baru.

Gejala: Agent yang hanya perlu membaca beberapa dokumen dibangun dengan sandbox penuh, dan setupnya terasa berat untuk hasil yang sederhana. Penyebab: Memakai sandbox untuk sesuatu yang cukup diselesaikan filesystem. Sandbox untuk menjalankan; filesystem untuk membaca, menulis, dan mencari. Perbaikan: Konfigurasikan akses filesystem langsung, tanpa sandbox.

Coba sendiri

Tantangan: Bangun analis-agent yang memproses berkas CSV dan menghasilkan laporan, lalu buktikan sendiri perbedaan sandbox dan filesystem.

Ketentuan:

1. Beri agent Workspace dengan LocalSandbox yang workingDirectory-nya menunjuk direktori khusus untuk latihan ini
2. Siapkan tiga berkas CSV kecil di direktori itu
3. Minta agent membaca ketiganya, menghitung sesuatu yang sederhana, dan menulis hasilnya ke sebuah berkas
4. Jalankan sekali, periksa berkas keluarannya
5. Hentikan proses, hapus isi sandbox, jalankan lagi — amati apa yang masih ada dan apa yang hilang
6. Ulangi dengan menulis keluaran ke filesystem alih-alih ke dalam sandbox, dan bandingkan
7. Tanpa mengubah kode, minta agent menjalankan perintah shell yang sebaiknya tidak boleh ia jalankan — misalnya membaca berkas di luar direktori kerja. Catat apa yang terjadi

Checklist penerimaan:

• [ ] Agent berhasil membaca ketiga CSV dan menulis laporan
• [ ] Setelah langkah 5, kamu bisa menunjukkan berkas mana yang hilang
• [ ] Setelah langkah 6, keluaran bertahan melewati siklus yang sama
• [ ] Langkah 7 memperlihatkan secara konkret apa arti "tidak terisolasi" — dan kamu bisa menjelaskan risikonya dengan bahasa sendiri
• [ ] Kamu bisa menyebutkan tingkat pengamanan mana yang pantas untuk agent ini kalau ia dipakai orang lain
• [ ] Kamu bisa menjelaskan kapan agent semacam ini sebenarnya tidak butuh sandbox sama sekali

Petunjuk: Langkah 7 sengaja dibuat tidak nyaman, dan lakukan hanya di mesin pengembanganmu dengan perintah yang tidak merusak — membaca berkas sudah cukup untuk membuktikan maksudnya. Membaca peringatan keamanan di dokumentasi memberi pengetahuan; melihat sendiri bahwa agent bisa menyentuh berkas di luar direktori kerjanya memberi kewaspadaan. Yang kedua bertahan lebih lama.

Ikhtisar

• Sandbox untuk menjalankan — perintah, kode, dependensi, proses. Filesystem untuk berkas yang bertahan, dan bekerja tanpa sandbox.
• Berkas di dalam sandbox bisa hilang saat lingkungannya berhenti. Keluaran yang harus bertahan ditulis ke filesystem.
• Susunannya: Workspace membungkus LocalSandbox — dan juga filesystem, search, LSP, serta workspace skills.
• LocalSandbox tidak terisolasi secara default dan menjalankan perintah di host aplikasi. Aktifkan isolasi native, atau pakai sandbox remote/container untuk kode yang tidak tepercaya.
• Workspace juga menyediakan search (BM25, vektor, hibrida) dan LSP inspection untuk memeriksa kode secara semantik.
• Otomasi peramban tersedia lewat SDK native, CLI, CDP, atau layanan cloud — dengan pertimbangan keamanan yang serupa.
• Kalau agent hanya membaca, menulis, dan mencari berkas, ia tidak butuh sandbox.

Lanjut ke mana

Bagian 7 selesai. Agent-mu kini bisa bekerja lama, mandiri, dan punya tempat kerja sendiri — yang membuat satu pertanyaan jadi mendesak: bagaimana kamu tahu ia melakukan hal yang benar? Bagian 8 — Observability & Evaluation.