.claude/skills/hf-space-sandbox/SKILL.md

metadata

name: hf-sandbox
description: >-
  Run remote workloads on Hugging Face Spaces via SSH using Dev Mode. Use when
  executing Python scripts, training models, or running compute-intensive tasks
  on remote GPU hardware.

HF Space Dev Mode Sandbox

Run scripts on remote sandbox hardware via SSH.

Create Space

uv run scripts/sandbox.py create user/sandbox

Check Status

Before SSHing, check the status of the sandbox to ensure it is ready. It may take a few minutes to provision.

uv run scripts/sandbox.py status user/sandbox

SSH Access

ssh USERNAME-SPACENAME@ssh.hf.space

For space burtenshaw/sandbox, the host is burtenshaw-sandbox@ssh.hf.space.

Persistent State

Use files in /app for state that survives across commands:

Set a variable:

ssh USERNAME-SPACENAME@ssh.hf.space "echo 42 > /app/foo"

Read it back:

ssh USERNAME-SPACENAME@ssh.hf.space "cat /app/foo"

Run a background job:

ssh USERNAME-SPACENAME@ssh.hf.space "nohup python train.py > /app/train.log 2>&1 &"

Check progress:

ssh USERNAME-SPACENAME@ssh.hf.space "tail /app/train.log"

Environment variables (source a file):

ssh USERNAME-SPACENAME@ssh.hf.space "echo 'export FOO=42' >> /app/.env"
ssh USERNAME-SPACENAME@ssh.hf.space "source /app/.env && echo \$FOO"

Run uv Scripts

# Remote execution
ssh USERNAME-SPACENAME@ssh.hf.space "uv run --with requests python -c 'import requests; print(requests.get(\"https://httpbin.org/get\").status_code)'"

# Copy and run
scp script.py USERNAME-SPACENAME@ssh.hf.space:/app/
ssh USERNAME-SPACENAME@ssh.hf.space "cd /app && uv run script.py"

# Background job
ssh USERNAME-SPACENAME@ssh.hf.space "cd /data && nohup uv run train.py > train.log 2>&1 &"
ssh USERNAME-SPACENAME@ssh.hf.space "tail -f /data/train.log"

uv Script Format (PEP 723)

#!/usr/bin/env -S uv run --script
# /// script
# requires-python = ">=3.11"
# dependencies = ["transformers", "torch"]
# ///

from transformers import pipeline
print(pipeline("sentiment-analysis")("Hello!"))

Space Management

uv run scripts/sandbox.py status user/sandbox
uv run scripts/sandbox.py start user/sandbox
uv run scripts/sandbox.py stop user/sandbox
uv run scripts/sandbox.py wait user/sandbox

Hardware

WARNING: Only cpu basic is available for now. Fetch this for up to date information: https://huggingface.co/docs/hub/en/spaces-overview