HF Sandboxes

Run the supported Ubuntu subset as one fresh Hugging Face Job per run unit. Nothing runs locally — not even the orchestrator — so this is the provider to reach for when you don't have (or don't want to use) local Docker, a cloud account, or GPU hardware of your own.

What runs where

The hfsandbox provider starts one HF Job per run unit from agentslastexam/ale-ubuntu22-docker, then talks to it over the job's exposed port. The orchestrator process itself needs only an HF token and outbound HTTPS — it can run on a laptop, a CI runner, or another HF Job.

Host requirements

• An HF token with the jobs scope (hf auth login, or HF_TOKEN in the environment).
• Approved access to the gated task-data dataset on Hugging Face.
• A private HF bucket to hold the extracted task-data archive.

hf auth whoami
uv sync --all-packages

Fetch task data once

The image ships without task inputs or references. Request access to the ALE task-data archive, then:

hf download agents-last-exam/agents-last-exam-data-archive \
  ale-tasks-data.tar.gz --repo-type dataset
tar xzf ale-tasks-data.tar.gz -C task-data
hf buckets create <namespace>/<bucket> --private
hf buckets sync task-data hf://buckets/<namespace>/<bucket>

That uploads the extracted <domain>/<task>/<variant>/{input,software,reference} tree to a bucket you own, ready to mount read-only into every sandbox job.

Use the shipped environment

Point volumes at that bucket in configs/environments/hfsandbox.yaml:

volumes:
  - hf://buckets/<namespace>/<bucket>:/mnt/ale-task-data:ro
task_data_source: mounted:/mnt/ale-task-data

then run the premade example, which wires configs/agents/openhands_cli_hf.yaml (GLM-5.3 via the HF router) to this environment over selected_tasks/docker_support.txt:

uv run python -m ale_run run example_hfsandbox_exp.yaml

For data-less tasks only (demo, tool_smoke) you can drop volumes and use task_data_source: baked_in_sandbox instead.

Resource sizing

Set flavor to any value hf jobs hardware lists (default cpu-upgrade, 8 vCPU / 32 GB). A cold pull of the ~40 GB image can take 10-15 minutes — start_timeout accounts for that. idle_timeout self-terminates a sandbox that goes quiet, and job_timeout is the hard per-job cap.

Output options

The default output_path: local copies produced files through the exposed port. See Choose where task output goes for other destinations.

Current limits

• Linux tasks only, same subset as the local Docker provider.
• The sandbox shares the job container's kernel and is not VM-isolated.
• transport: sandbox (the HF Sandbox API port-proxy) is available but not the default — prefer transport: job.