The filesystem disappears, and what to do about it

Assume the disk is temporary

A Space runs in a container. Rebuild it, restart it, let it sleep and wake, and anything written to the local filesystem may be gone. People discover this after a week of collected feedback vanishes on a routine restart.

There are four places to put state, and choosing correctly is most of this lesson.

1. Nowhere: the default, and often right

If your Space transforms input into output and keeps nothing, say so in the readme and move on. “Nothing you type is stored” is a feature, it is free, and it removes a whole category of obligation. Most demos should be here.

2. gr.State: per session, in memory

Conversation history, a wizard’s current step, an uploaded file being worked on. Dies when the browser session ends, never shared between users. Covered in the Blocks lesson, and it is the right home for most of what people wrongly put on disk.

3. Persistent storage: a real disk, paid

Spaces can be given a persistent volume mounted at /data, in tiers starting around 20 GB for a few dollars a month. It survives restarts and rebuilds.

Use it for the model cache, which is the highest-value thing you can put there:

---
# in README.md front matter
sdk: gradio
---

import os
os.environ["HF_HOME"] = "/data/.huggingface"   # before importing transformers

Now a cold start after sleep loads weights from the volume instead of downloading them again, which can turn a three-minute wake into fifteen seconds. On a Space that sleeps often, this is the best use of a few dollars a month available anywhere on the platform.

It is still not a database: one volume, one Space, no backups by default, and no concurrency control beyond what you write yourself.

4. A Hub dataset repository: free, durable, versioned

For collecting anything (feedback, submitted examples, evaluation results) a dataset repository is better than a disk. It is free, it is versioned, it is backed up by being a git repository, and it can be private.

from huggingface_hub import CommitScheduler
import json, uuid, pathlib

folder = pathlib.Path("feedback"); folder.mkdir(exist_ok=True)
file = folder / f"{uuid.uuid4()}.jsonl"

scheduler = CommitScheduler(
    repo_id="your-name/space-feedback",
    repo_type="dataset",
    folder_path=folder,
    every=5,                # minutes
    private=True,
)

def record(text, verdict):
    with scheduler.lock:
        with file.open("a") as f:
            f.write(json.dumps({"text": text, "verdict": verdict}) + "\n")

CommitScheduler batches writes and pushes them on a timer, so you are not making a git commit per request. The lock matters: without it, concurrent requests interleave partial lines and you get corrupt JSON.

The part that is not technical

If you store what users type, you have taken on responsibility for it. Before writing that code:

• Say so on the page, in plain words, above the fold. Not in a link.
• Make the repository private unless you have a specific reason and consent for it to be public. A public dataset of things strangers typed into a demo is a privacy incident waiting for a search engine.
• Collect the minimum. The text and a verdict, not IP addresses, not timestamps precise enough to re-identify, not the user agent.
• Say how long you keep it, and then actually delete it.
• Do not collect at all if the Space handles anything sensitive: health, finance, legal, anything about a named person.

Rules on personal data differ by country and are unsettled for AI training in several of them. This lesson is not legal advice and cannot be; the defensible engineering position is to collect as little as possible and to tell people exactly what you collect.

Secrets

Space settings have a Secrets section. Values set there arrive as environment variables and are not in the repository:

token = os.environ["HF_TOKEN"]

Never commit a token, never put one in a Gradio textbox default, and never print one into a log. Duplicating a Space does not copy its secrets: the duplicate prompts for its own, which is correct behaviour and occasionally confusing.

Do this now

Pick one Space you have made and decide, explicitly, which of the four storage answers it uses. Then write one sentence in the readme saying so. Most Spaces should say “nothing is stored”, and most do not say anything at all.