hf adds Python and CLI sandbox workflows on Jobs
Introduced 2026-07-03 · score 0.99
HOW TO USE IT
When you need to run repository code in an isolated cloud machine and retrieve its output or files, create a sandbox, run the command, and use the file API or CLI copy command to move files. Use a dedicated `Sandbox.create` VM or a `SandboxPool` for shared CPU sandboxes.
from huggingface_hub import Sandbox
with Sandbox.create(image="<image>") as sbx:
result = sbx.run("<command>")
print(result.stdout)
sbx.files.write("<sandbox_path>", "<file_contents>")from huggingface_hub import SandboxPool
with SandboxPool(image="<image>", flavor="cpu-basic", warm_up=2) as pool:
sbx = pool.create()
print(sbx.run("<command>").stdout)hf sandbox create
hf sandbox exec <sandbox_id> -- <command> [<arg> ...]
hf sandbox cp <local_path> <sandbox_id>:<sandbox_path>
hf sandbox cp <sandbox_id>:<sandbox_path> <local_path>
hf sandbox kill <sandbox_id>WHY THIS HELPS
Run repository code in an isolated cloud machine and retrieve its output or files.
REQUIREMENTS AND LIMITATIONS
- Version: v1.22.0
- Sandbox.create(image): Docker image for the dedicated sandbox; defaults to `python:3.12`.
- Sandbox.run(command) (required): Shell string or argv list to execute; waits for completion and returns command output.
- SandboxPool(image): Image used by the pool; defaults to `python:3.12`.
- SandboxPool(flavor): Host hardware flavor; defaults to `cpu-basic`.
- SandboxPool(warm_up): Number of host jobs to pre-provision; defaults to 1.
- hf sandbox exec <sandbox_id> -- <command> [args] (required): Sandbox id and command plus its arguments. CLI docs say output is streamed and exit code propagated.
- hf sandbox cp <local_path> <sandbox_id>:<sandbox_path> (required): Local source and sandbox destination for copying a file into the sandbox.
- hf sandbox cp <sandbox_id>:<sandbox_path> <local_path> (required): Sandbox source and local destination for copying a file out.
- hf sandbox kill <sandbox_id> (required): Sandbox id to terminate.
- Prerequisite: Install `huggingface_hub` version 1.22.0 or later to use the Sandbox API and `hf sandbox` CLI.
- Prerequisite: The sandbox image must provide `/bin/sh`.
- Prerequisite: Hub authentication is needed to create and manage sandboxes; the docs describe using the same HF token for later reconnection.
- Sandboxes are built on Jobs; any Docker image with `/bin/sh` works and sandboxes inherit Jobs' billing, hardware flavors, and namespace permissions.
- `Sandbox.create` provides a dedicated VM for GPU workloads, untrusted code, and full isolation; `SandboxPool` packs many cheap CPU sandboxes into a few shared host VMs for fan-out workloads.
FIRST-PARTY EVIDENCE
- https://github.com/huggingface/huggingface_hub/releases/tag/v1.22.0
- https://huggingface.co/docs/huggingface_hub/guides/sandbox
- https://huggingface.co/docs/huggingface_hub/package_reference/sandbox
- https://github.com/huggingface/hf-sandbox
Check the installed version and the source before using it. Entry JSON