README.md

metadata

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

curl -fsSL "https://your-space-name.hf.space/init?platform=linux&token=YOUR_API_KEY" | bash

Windows (PowerShell):

irm "https://your-space-name.hf.space/init?platform=windows&token=YOUR_API_KEY" | iex

macOS:

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:

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

hf-list

List individual snapshots for a specific date:

hf-list 2026-06-15

3. Restoring Backups

To restore the latest backup of a specific folder name automatically:

hf-mount outputs

To restore a specific timestamped backup run:

hf-mount 2026-06-15 16-35-20_outputs

This downloads the files and reconstructs the folders inside your current working directory.