agents/hf-spaces.md

Hugging Face access

HF_TOKEN is present in this container's environment and the official hf CLI is installed, so you can create and manage Hugging Face repos directly.

Never print, echo, cat or otherwise reveal the value of HF_TOKEN. Pass it by variable reference only. Session transcripts can be shared, and this token carries write access to the whole account.

Who am I

hf auth whoami

The CLI reads HF_TOKEN from the environment; there is no login step.

Create a Space

hf repo create my-space --repo-type space --space_sdk docker

Then populate it. A Docker Space needs, at minimum, a README.md whose YAML front matter declares the SDK and the port your app listens on, plus a Dockerfile:

---
title: My Space
emoji: 🚀
colorFrom: gray
colorTo: indigo
sdk: docker
app_port: 7860
---

app_port must match what the container actually listens on. Hugging Face exposes exactly one port and routes it through HTTPS on 443 — a Space cannot serve a second port, and clients must not append a port to the *.hf.space URL.

Upload files with the CLI:

hf upload <user>/<space> ./local-dir . --repo-type space

…or use git, keeping the token out of the stored remote:

git clone "https://huggingface.co/spaces/<user>/<space>" && cd <space>
# commit files, then:
git push "https://$(hf auth whoami | head -1):${HF_TOKEN}@huggingface.co/spaces/<user>/<space>" HEAD:main

Set Space secrets

Secrets are the only correct place for credentials — never commit them.

curl -sf -X POST "https://huggingface.co/api/spaces/<user>/<space>/secrets" \
  -H "Authorization: Bearer $HF_TOKEN" -H "Content-Type: application/json" \
  -d '{"key":"SOME_KEY","value":"...","description":"what it is for"}'

Check whether a Space is up

curl -s "https://huggingface.co/api/spaces/<user>/<space>" | jq '.runtime.stage'

RUNNING is healthy. BUILD_ERROR / RUNTIME_ERROR / CONFIG_ERROR mean it failed — read the build logs on the Space page. Free cpu-basic Spaces are ephemeral and are stopped after roughly 48h idle, so anything that must survive belongs in git or on a persistent-storage mount at /data.

Ask before destroying things

Creating repos is fine. Deleting or renaming an existing repo, changing its visibility, or overwriting someone else's files is not reversible — confirm with the user first.