README.md

---
title: 9router
emoji: 💻
colorFrom: red
colorTo: green
sdk: docker
pinned: false
---

# 9router on Hugging Face Spaces

Clones [decolua/9router](https://github.com/decolua/9router) at build, runs it
on port 7860, and persists the SQLite store (`/app/data/db/data.sqlite`) to a
private HF Dataset repo so rebuilds/restarts don't wipe routing history.

## Files

- `Dockerfile` — Node 20 base, build toolchain, plus `python3` + `huggingface_hub` + `sqlite3` CLI for bucket sync
- `start.sh` — entrypoint wrapper: pulls latest snapshot from the Dataset repo, spawns background sync loop, then `exec npm run start`
- `backup.sh` — invoked every `$SYNC_INTERVAL` seconds: `sqlite3 .backup` → clear volatile request/usage history by default → upload compact SQLite to Dataset repo (safe even while the app holds a write lock)

## One-time setup on HF

1. Create a **private Dataset** repo, e.g. `hank-jay/9router-storage`
2. In this Space → Settings → Variables and secrets, add:
   - `HF_TOKEN` (secret) — write-scoped token with access to the Dataset
   - `HF_DATA_REPO` (variable, optional) — defaults to `hank-jay/9router-storage`
   - `SYNC_INTERVAL` (variable, optional) — backup cadence in seconds, defaults to `600`
   - `BACKUP_MODE` (variable, optional) — `settings` by default; use `full` only if you intentionally want request/usage history persisted
3. Factory rebuild the Space

## Caveats

- **Data loss window** = `SYNC_INTERVAL` (default 10 min). Tighten if writes are critical.
- Container shutdown grace on HF is short (~10s); rely on the periodic loop, not a `SIGTERM` flush.
- If `HF_TOKEN` is missing, the Space still boots but warns and runs ephemerally — handy for one-off tests, dangerous for prod.