# Sandbox

> [!NOTE]
> Sandboxes adalah fitur **eksperimental**. API, nilai default, dan perilaku dapat berubah tanpa pemberitahuan. Sandbox bersama ditujukan untuk beban kerja dalam batas kepercayaan yang sama; isolasi mereka tidak menjamin perlindungan dari setiap serangan lintas-sandbox. Gunakan sandbox khusus untuk beban kerja yang tidak saling percaya, dan hindari membuat kredensial berumur panjang atau berlingkup luas tersedia untuk beban kerja sandbox.

Sandbox adalah mesin cloud terisolasi yang dapat Anda jalankan dalam hitungan detik, menjalankan perintah dengan output yang disiarkan secara langsung, serta memindahkan file masuk dan keluar — semuanya dari Python atau CLI. Sandbox dibangun di atas [Jobs](./jobs): di balik layar, sebuah sandbox hanyalah Job yang menjalankan server kecil yang mengekspose eksekusi perintah dan transfer file melalui HTTP.

Mereka cocok digunakan kapan pun Anda perlu menjalankan kode di tempat lain selain mesin Anda sendiri:

- **Menjalankan kode yang tidak tepercaya atau dihasilkan AI** — biarkan agen mengeksekusi kode arbitrer tanpa memberikannya akses ke sistem file Anda. Gunakan *dedicated* sandbox untuk ini: itu adalah VM tersendiri.
- **Build dan eksperimen yang dapat direproduksi** — dijalankan pada image yang bersih dan terdefinisi dengan baik, di CPU atau GPU.
- **Mengembangkan pekerjaan** — luncurkan ratusan lingkungan paralel (rollout RL, evaluasi, eksekusi alat batch) dengan biaya rendah.

Setiap image Docker dengan `/bin/sh` dapat digunakan — tidak perlu Python, pip, atau agen yang terpasang sebelumnya (binari server statis kecil disuntikkan saat startup).

> [!TIP]
> Penasaran bagaimana ini bekerja di balik layar — server dalam job, autentikasi stateless, atau bagaimana satu Job dapat menampung banyak sandbox terisolasi? Lihat [panduan konseptual Sandboxes](../concepts/sandbox).

## Dua jenis sandbox

Ada dua cara untuk mendapatkan sandbox. Keduanya memberikan objek [Sandbox](/docs/huggingface_hub/main/id/package_reference/sandbox#huggingface_hub.Sandbox) yang sama (dengan `run`, `files`, `connect`, `kill` yang sama); perbedaannya hanya terletak pada cara alokasi mesin di baliknya:

|            | [Sandbox.create()](/docs/huggingface_hub/main/id/package_reference/sandbox#huggingface_hub.Sandbox.create) — **dedicated**              | [SandboxPool](/docs/huggingface_hub/main/id/package_reference/sandbox#huggingface_hub.SandboxPool) — **berbagi / pool**                                                     |
| ---------- | ----------------------------------------------- | --------------------------------------------------------------------------------------- |
| pemetaan    | satu Job = **satu sandbox** (satu VM utuh)          | satu Job = **banyak sandbox** (satu VM, dikemas)                                           |
| isolasi  | VM penuh                                         | uid + [Landlock](https://docs.kernel.org/userspace-api/landlock.html) (kepercayaan pengguna yang sama) |
| cold start | ~6 detik per sandbox                                 | ~6 detik untuk host pertama, kemudian ~1 round-trip untuk masing-masing                                         |
| biaya       | satu VM per sandbox                              | satu VM per **host**, dibagi di antara banyak sandbox                                    |
| GPU        | ✅                                               | ❌ (Hanya CPU)                                                                            |
| paling cocok untuk   | satu sandbox, beban kerja GPU, kode yang tidak tepercaya | banyak sandbox CPU murah (rollout RL, fan-out)                                         |

Aturan praktis: membutuhkan GPU atau untuk menjalankan kode yang saling tidak tepercaya → khusus. Membutuhkan ratusan sandbox CPU yang murah → pool.

## Mulai Cepat

```python
>>> from huggingface_hub import Sandbox

>>> with Sandbox.create() as sbx:                      # ready in ~6s
...     result = sbx.run("python -c 'print(40 + 2)'")  # ~100ms per command
...     print(result.stdout)
42
```

Pilih gambar dan [varian](./jobs#select-the-hardware) perangkat keras apa pun:

```python
>>> sbx = Sandbox.create(image="alpine:3.20")
>>> sbx = Sandbox.create(image="pytorch/pytorch:2.6.0-cuda12.4-cudnn9-devel", flavor="a10g-small")
```

## Menjalankan perintah

[Sandbox.run()](/docs/huggingface_hub/main/id/package_reference/sandbox#huggingface_hub.Sandbox.run) menjalankan perintah dan menunggu hingga selesai. Sertakan string shell atau daftar argv:

```python
>>> sbx.run("pip install -q numpy")                       # string  → runs through /bin/sh -c
>>> sbx.run(["python", "-c", "import numpy; print(numpy.__version__)"])  # list → exec'd directly

# Live output streaming, plus env, cwd, timeout, stdin
>>> sbx.run("make -j4", cwd="/app", env={"CC": "gcc"}, timeout=600, on_stdout=print, on_stderr=print)
```

Secara default, mode disimpulkan dari tipe (string dijalankan melalui `/bin/sh -c`, sedangkan list dieksekusi langsung sebagai argv). Sampaikan `shell=` untuk membuatnya eksplisit — berguna untuk menghindari jebakan klasik di mana list satu elemen seperti `["echo hi"]` dieksekusi sebagai satu program bernama `"echo hi"`:

```python
>>> sbx.run("echo $HOME && ls | wc -l", shell=True)   # force the shell (pipes, globs, $VARS)
>>> sbx.run(["git", "commit", "-m", msg], shell=False)  # force argv (no quoting surprises)
```

`shell=True` membutuhkan string dan `shell=False` membutuhkan list; memberikan tipe yang salah akan memicu `ValueError`.

Perintah yang keluar dengan status non-zero akan memicu `SandboxCommandError` (dengan `stdout`, `stderr`, dan `exit_code` yang terlampir). Berikan `check=False` untuk mendapatkan kembali [SandboxCommandResult](/docs/huggingface_hub/main/id/package_reference/sandbox#huggingface_hub.SandboxCommandResult) alih-alih memicu error:

```python
>>> result = sbx.run("test -f /tmp/missing", check=False)
>>> result.exit_code
1
```

### Proses latar belakang

Lewati `background=True` untuk memulai proses jangka panjang (server, watcher, atau sesi pelatihan) tanpa menunggu. `run` langsung mengembalikan [SandboxProcess](/docs/huggingface_hub/main/id/package_reference/sandbox#huggingface_hub.SandboxProcess) alih-alih [SandboxCommandResult](/docs/huggingface_hub/main/id/package_reference/sandbox#huggingface_hub.SandboxCommandResult):

```python
>>> proc = sbx.run("python -m http.server 8000", background=True)
>>> proc
SandboxProcess(pid=1234, cmd='python -m http.server 8000', tag=None, started_at_ms=1700000000000, running=True, exit_code=None)
```

Daftarkan proses sandbox dan hentikan salah satunya saat selesai. Proses yang telah selesai tetap terdaftar (dengan `running=False` dan `exit_code` mereka) hingga sandbox dihapus, sehingga Anda dapat mengetahui apakah suatu proses masih aktif atau sudah berakhir:

```python
>>> sbx.processes()
[SandboxProcess(pid=1234, cmd='python -m http.server 8000', tag=None, started_at_ms=1700000000000, running=True, exit_code=None)]
>>> proc.kill()
```

Opsi streaming/hanya-menunggu (`timeout`, `stdin`, `on_stdout`, `on_stderr`, `check`) tidak berlaku dalam mode latar belakang — hanya `env`, `cwd`, dan `shell` yang dihormati.

## Berkas

```python
>>> sbx.files.write("/app/script.py", "print('hi')")     # str | bytes | file-like
>>> sbx.files.read_text("/app/script.py")
"print('hi')"
>>> sbx.files.upload("local_data.csv", "/data/data.csv")  # local -> sandbox
>>> sbx.files.download("/data/results.bin", "results.bin")  # sandbox -> local
>>> sbx.files.list("/data")
[FileEntry(name='data.csv', path='/data/data.csv', type='file', size=5324, ...)]
```

Helper lainnya: `stat`, `exists`, `mkdir`, `delete`.

## Mencapai server di dalam sandbox

Mulai server di dalam sandbox (di latar belakang), lalu akses dari luar dengan [Sandbox.proxy_url_for()](/docs/huggingface_hub/main/id/package_reference/sandbox#huggingface_hub.Sandbox.proxy_url_for) — permintaan diteruskan oleh server sandbox dalam job ke server internal Anda, sehingga tidak ada port publik tambahan yang perlu diekspos. Ini berfungsi untuk HTTP biasa, Server-Sent Events, dan WebSocket. Gabungkan URL dengan `Sandbox.proxy_headers` untuk autentikasi (klien WebSocket/HTTP Anda harus mengirimkannya):

```python
>>> import httpx2
>>> with Sandbox.create() as sbx:
...     sbx.files.write("app.py", "...")  # a server exposing e.g. /hello and /ws
...     sbx.run("uvicorn app:app --host 127.0.0.1 --port 8000", background=True)
...     # plain HTTP
...     r = httpx2.get(sbx.proxy_url_for(8000, "/hello"), headers=sbx.proxy_headers)
...     # WebSocket: ask for a wss:// URL
...     ws_url = sbx.proxy_url_for(8000, "/ws", scheme="wss://")
```

Saat menggunakan `proxy_headers`, nonaktifkan redirect pada klien HTTP Anda (`follow_redirects=False` dengan httpx, atau `allow_redirects=False` dengan requests). Aplikasi dapat melakukan redirect ke origin lain, dan header autentikasi kustom ini tidak boleh diteruskan ke sana.

Sandbox yang dipoolkan memerlukan server yang mengembalikan token kemampuan per-sandbox. Token yang hilang merupakan kesalahan; lakukan upgrade dan daur ulang host alih-alih menggunakan token pengelolaannya.

Cara server internal harus mendengarkan bergantung pada jenis sandbox:

- **Dedicated** ([Sandbox.create()](/docs/huggingface_hub/main/id/package_reference/sandbox#huggingface_hub.Sandbox.create)): mengikat port TCP biasa di `127.0.0.1:<port>`.
- **Pool / bersama** ([SandboxPool](/docs/huggingface_hub/main/id/package_reference/sandbox#huggingface_hub.SandboxPool)): sandbox yang di-pool tidak dapat mengikat port TCP (Landlock), jadi dengarkan pada **unix socket** di `$SBX_PROXY_DIR/<port>.sock` (variabel lingkungan itu disetel di setiap sandbox), misalnya `uvicorn app:app --uds $SBX_PROXY_DIR/8000.sock`. Sisi klien (`proxy_url_for` / `proxy_headers`) identik dalam kedua kasus.

## Siklus Hidup

Sandbox bertahan lebih lama dari proses yang membuatnya — Anda dapat membuatnya sekarang dan menyambungkan ulang nanti, dari mesin mana pun yang memegang token HF yang sama, tanpa perlu menyalin state:

```python
>>> sbx = Sandbox.create()
>>> sbx.id
'687f911eaea852de79c4a50a'

# Later, from anywhere:
>>> sbx = Sandbox.connect("687f911eaea852de79c4a50a")
>>> sbx.kill()           # terminate now
```

- `idle_timeout` (default 10 menit) adalah fitur utama: ia mematikan sandbox ketika tidak ada panggilan API yang dibuat dan tidak ada proses yang berjalan, sehingga sandbox yang ditinggalkan berhenti ditagih. Atur saat pembuatan (`Sandbox.create(idle_timeout="30m")`) atau berikan `None` untuk menonaktifkan.
- Job juga memiliki masa hidup maksimum tetap 24 jam sebagai pengaman keras (tidak dapat dikonfigurasi).
- `forward_hf_token=True` secara eksplisit mengekspos token HF Anda ke kode yang berjalan di dalam sandbox (sebagai `HF_TOKEN`). Bahkan dengan `forward_hf_token=False`, jangan perlakukan sandbox sebagai batas keras untuk kredensial Anda — lihat peringatan di bagian atas halaman ini.

## Banyak sandbox sekaligus: SandboxPool

Ketika Anda membutuhkan banyak sandbox (rollout RL paralel, evaluasi fan-out, eksekusi tool batch), satu Job per sandbox adalah pemborosan: masing-masing membayar biaya cold start VM penuh dan memegang satu mesin utuh untuk beban kerja yang hanya membutuhkan beberapa MB RAM. [SandboxPool](/docs/huggingface_hub/main/id/package_reference/sandbox#huggingface_hub.SandboxPool) mengemas banyak sandbox ringan ke dalam beberapa Job host bersama — satu VM yang ditagih melayani puluhan sandbox, sehingga biaya per sandbox turun sebesar faktor tersebut dan cold start per sandbox hanya sekitar satu round-trip jaringan.

```python
>>> from huggingface_hub import SandboxPool

>>> with SandboxPool(image="python:3.12", flavor="cpu-basic", warm_up=2) as pool:
...     boxes = [pool.create() for _ in range(100)]   # packed across the 2 warm host VMs
...     print(boxes[0].run("echo hi").stdout)          # each box is a normal Sandbox
hi
```

Setiap `create()` mengembalikan satu [Sandbox](/docs/huggingface_hub/main/id/package_reference/sandbox#huggingface_hub.Sandbox) penuh; panggil berulang kali untuk melakukan fan-out. Pool akan memulai host Jobs sesuai kebutuhan, mengemas `sandboxes_per_host` sandbox per host, dan mengakhiri semuanya pada `close()` (atau ketika host menjadi idle, sebagai pengaman penagihan). Pola fan-out yang umum:

```python
>>> from concurrent.futures import ThreadPoolExecutor
>>> with SandboxPool(image="python:3.12", warm_up=4) as pool:
...     boxes = [pool.create() for _ in tasks]
...     with ThreadPoolExecutor(32) as ex:
...         outputs = list(ex.map(lambda b, t: b.run(t.cmd).stdout, boxes, tasks))
```

Env dan `idle_timeout` bersifat per-sandbox (mereka milik `create()`, bukan pool), sehingga sandbox dalam satu pool dapat memiliki lingkungan yang berbeda:

```python
>>> sbx = pool.create(env={"SEED": "42"}, idle_timeout="5m", forward_hf_token=True)
```

Sandbox yang dipool adalah [Sandbox](/docs/huggingface_hub/main/id/package_reference/sandbox#huggingface_hub.Sandbox) penuh, tetapi beberapa input ditetapkan oleh host alih-alih per-sandbox — sehingga [SandboxPool.create()](/docs/huggingface_hub/main/id/package_reference/sandbox#huggingface_hub.SandboxPool.create) menerima set argumen yang lebih kecil daripada [Sandbox.create()](/docs/huggingface_hub/main/id/package_reference/sandbox#huggingface_hub.Sandbox.create):

| Input              | `Sandbox.create` (dedikatif) | `SandboxPool.create` (pooled)            |
| ------------------ | ---------------------------- | ---------------------------------------- |
| `image`, `flavor`  | per-sandbox                  | dipastikan oleh pool (diatur sekali di host) |
| `volumes`          | per-sandbox                  | **tidak tersedia** (dimuat saat host boot) |
| `env`              | per-sandbox                  | per-sandbox                              |
| `idle_timeout`     | per-sandbox                  | per-sandbox                              |
| `forward_hf_token` | per-sandbox                  | per-sandbox                              |

Sandbox yang dipool berbagi host job berumur panjang, sehingga tidak ada kanal Job-secrets terenkripsi seperti yang diterima sandbox khusus. Namun, `env` dari sandbox yang dipool dikirim ke server host saat pembuatan sandbox (bukan saat job dimulai), sehingga tidak pernah disimpan di metadata job mana pun — kirim rahasia yang dimaksud sebagai `env` biasa.

### Pertumbuhan sesuai permintaan dan pemanasan awal

`pool.create()` membuat satu sandbox pada satu waktu, dengan memanfaatkan ulang host yang masih memiliki kapasitas kosong sebelum memulai host baru — sehingga Anda dapat membuat sandbox saat pekerjaan datang dan mereka akan mengemas diri ke host yang sudah hangat:

```python
>>> pool = SandboxPool(image="python:3.12", flavor="cpu-basic")
>>> sbx = pool.create()    # boots the first host (~6s)
>>> sbx = pool.create()    # packs onto the same warm host (~one round-trip, no new VM)
```

Untuk menghindari host cold start pada beberapa panggilan pertama, pre-provision host dengan `warm_up=N` (diboot pada `create()` pertama) atau dengan memanggil `pool.warm(N)` di awal.

### Menggunakan ulang pool di antara proses dan mesin

Host yang hangat ditemukan melalui label job, sehingga penggunaan ulang berfungsi antar proses: `SandboxPool` baru dengan `image`/`flavor`/`name` yang sama akan menempel pada host yang dibiarkan berjalan oleh eksekusi sebelumnya, alih-alih memulai hostnya sendiri. Sampaikan `name=` untuk mencegah pool yang berbeda berbagi host.

Untuk menyambung ulang dari mesin lain tanpa status lokal, hubungkan kembali dengan id pool menggunakan [SandboxPool.connect()](/docs/huggingface_hub/main/id/package_reference/sandbox#huggingface_hub.SandboxPool.connect) — metode ini menemukan host yang sedang berjalan, membangun ulang konfigurasi pool (image, flavor, packing density) dari job host tersebut, dan siap untuk `create()` lebih banyak:

```python
>>> pool = SandboxPool.connect("pool-ae9f7efe0bc7")   # from anywhere, no config needed
>>> sbx = pool.create()
```

Pool yang sudah `connect()` tidak memiliki host bersama (klien lain mungkin sedang menggunakannya), sehingga — seperti [Sandbox.connect()](/docs/huggingface_hub/main/id/package_reference/sandbox#huggingface_hub.Sandbox.connect) — keluar dari blok `with` (atau memanggil `close()`) hanya melepaskan klien HTTP lokal dan membiarkan host tetap berjalan. Akhiri host pool secara eksplisit dengan `pool delete` / `hf sandbox pool delete <id>`.

> [!NOTE]
> Sandbox di dalam host dipisahkan oleh uid yang berbeda dan ruleset Landlock per-sandbox. Sandbox bersama ditujukan untuk workload paralel *milik satu pengguna*, dan isolasi dari setiap serangan lintas-sandbox tidak dijamin. Untuk kode yang saling tidak tepercaya, atau untuk GPU, gunakan [Sandbox.create()](/docs/huggingface_hub/main/id/package_reference/sandbox#huggingface_hub.Sandbox.create) (VM terpisah per sandbox). Trade-off-nya diuraikan dalam panduan konseptual: [bagaimana isolasi bekerja](../concepts/sandbox#isolation-in-a-pool-uid--landlock) dan — lebih penting jika Anda memilih antara dua mode — daftar lengkap [batasan yang diketahui](../concepts/sandbox#known-limitations).

## Dari CLI

Perintah `hf sandbox` meniru API Python. Sandbox khusus:

```bash
>>> hf sandbox create
✓ Sandbox ready id=687f911eaea852de79c4a50a image=python:3.12 elapsed=6.0s

# Attach labels to the underlying Job
>>> hf sandbox create --label controller-run=run-42 --label team=data-infra

>>> hf sandbox exec 687f911eaea852de79c4a50a -- python -c "print('hi')"
hi

>>> hf sandbox cp data.csv 687f911eaea852de79c4a50a:/data/data.csv
>>> hf sandbox kill 687f911eaea852de79c4a50a
```

`hf sandbox exec` mengalirkan output secara langsung dan keluar dengan kode keluar dari perintah tersebut, sehingga dapat dikomposisikan dalam skrip:

```bash
hf sandbox exec $ID -- pytest && echo "tests passed"
```

Mulai proses jangka panjang di latar belakang dengan `hf sandbox spawn` (menampilkan pid-nya), lalu daftarkan atau hentikan proses. Daftar menampilkan status setiap proses (`running` atau `exited (<code>)`):

```bash
>>> hf sandbox spawn $ID -- python -m http.server 8000
✓ Process started sandbox=687f... pid=1234

>>> hf sandbox process ls $ID
pid   status   cmd
1234  running  python -m http.server 8000

>>> hf sandbox process kill $ID 1234
```

Untuk banyak sandbox bersama yang murah, hangatkan pool sekali lalu buat ke dalamnya sesuai permintaan:

```bash
# Warm a pool -> prints a pool id (billing starts: a host VM is now running)
>>> hf sandbox pool create python:3.12 --flavor cpu-basic
✓ Pool created id=pool-ae9f7efe0bc7 image=python:3.12 flavor=cpu-basic host=687f... elapsed=5.7s

# Each create packs onto a host with room (found by the pool id, from any machine);
# only when every host is full does it boot a duplicate. Env is per-sandbox (pooled
# sandboxes share a host, so there's no encrypted-secrets channel — use --env).
>>> hf sandbox create --pool pool-ae9f7efe0bc7 --env LOG_LEVEL=debug
>>> hf sandbox create --pool pool-ae9f7efe0bc7

>>> hf sandbox pool ls
>>> hf sandbox pool delete pool-ae9f7efe0bc7    # terminate the pool's hosts (and their sandboxes)
```

`hf sandbox create --pool` menghasilkan sandbox bersama; id-nya berbentuk `<host_job_id>.<local_id>` dan berfungsi di mana pun id khusus berlaku (`exec`, `cp`, `kill`). Pool tidak memiliki state lokal — ia hanyalah VM host yang sedang berjalan, yang ditemukan melalui id pool — sehingga dapat digunakan dari mesin mana pun dan berhenti ada begitu semua hostnya hilang (dihentikan atau habis masa idle).

