| --- |
| title: hf-save |
| emoji: 💾 |
| colorFrom: blue |
| colorTo: indigo |
| sdk: docker |
| app_port: 7860 |
| pinned: false |
| --- |
| |
| # hf-save |
|
|
| An ultra-fast, zero-overhead developer tool to save work artifacts from ephemeral GPU instances (RunPod, Vast.ai, Lambda Labs) and restore them later. |
|
|
| Uses a **Hugging Face Docker Space** with a **Dataset Storage Mount** at `/data` as the backend and a **Single-binary Go CLI** on the client side. |
|
|
|
|
| --- |
|
|
| ## Deploying the Backend Space |
|
|
| 1. Create a new Space on [Hugging Face](https://huggingface.co/spaces). |
| 2. Set the SDK to **Docker** (Blank template). |
| 3. **Set up Persistent Storage / Dataset Mount**: |
| * Mount a dataset repository at `/data` inside your Space configuration settings. |
| 4. **Set environment variable**: |
| * In your Space's settings, add a new Secret variable: `HF_SAVE_API_KEY` (e.g. `my-super-secret-key-123`). This will authenticate client-side uploads. |
| 5. Clone your space repository locally, copy the repository files (`main.go`, `cli/`, `Dockerfile`, `go.mod`), commit and push to the Space repo. Hugging Face will automatically compile the server and build the CLI binaries for Linux, macOS, and Windows. |
|
|
| --- |
|
|
| ## Client Installation |
|
|
| To install the client binary on any GPU instance or development machine, run the appropriate command. Replace `your-space-name.hf.space` with your actual Hugging Face Space hostname. |
|
|
| ### Linux: |
| ```bash |
| curl -fsSL "https://your-space-name.hf.space/init?platform=linux&token=YOUR_API_KEY" | bash |
| ``` |
|
|
| ### Windows (PowerShell): |
| ```powershell |
| irm "https://your-space-name.hf.space/init?platform=windows&token=YOUR_API_KEY" | iex |
| ``` |
|
|
| ### macOS: |
| ```bash |
| curl -fsSL "https://your-space-name.hf.space/init?platform=mac&token=YOUR_API_KEY" | bash |
| ``` |
|
|
| *Note: If you omit the `&token=YOUR_API_KEY` parameter from the URL, the installer will interactively prompt you to enter the API Key during setup.* |
|
|
| --- |
|
|
| ## CLI Usage Guide |
|
|
| Once installed, use the CLI commands to backup and restore files. |
|
|
| ### 1. Saving Directories |
| To backup folders at the end of a session: |
| ```bash |
| # Save a single directory |
| hf-save outputs |
| |
| # Save multiple directories |
| hf-save outputs logs checkpoints |
| ``` |
| This scans files, filters out binary/bloat directories (like `.git`, `__pycache__`, `venv`), and streams them directly to `/data/{YYYY-MM-DD}/{HH-MM-SS}_{name}` on your backend. |
|
|
| ### 2. Listing Backups |
| List all backup dates: |
| ```bash |
| hf-list |
| ``` |
|
|
| List individual snapshots for a specific date: |
| ```bash |
| hf-list 2026-06-15 |
| ``` |
|
|
| ### 3. Restoring Backups |
| To restore the **latest** backup of a specific folder name automatically: |
| ```bash |
| hf-mount outputs |
| ``` |
|
|
| To restore a **specific** timestamped backup run: |
| ```bash |
| hf-mount 2026-06-15 16-35-20_outputs |
| ``` |
| This downloads the files and reconstructs the folders inside your current working directory. |
|
|
