---
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

```bash
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.

```bash
uv run scripts/sandbox.py status user/sandbox
```

## SSH Access

```bash
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:**
```bash
ssh USERNAME-SPACENAME@ssh.hf.space "echo 42 > /app/foo"
```

**Read it back:**
```bash
ssh USERNAME-SPACENAME@ssh.hf.space "cat /app/foo"
```

**Run a background job:**
```bash
ssh USERNAME-SPACENAME@ssh.hf.space "nohup python train.py > /app/train.log 2>&1 &"
```

**Check progress:**
```bash
ssh USERNAME-SPACENAME@ssh.hf.space "tail /app/train.log"
```

**Environment variables (source a file):**
```bash
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

```bash
# 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)

```python
#!/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

```bash
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