itchbox (MVP)

A tiny self-hosted itch.io-style gallery for static HTML5 games.

What it does

• Upload a ZIP containing index.html (+ assets)
• Extracts it safely to /data/games/<slug>/...
• Lists games in a gallery, has a details page, and a play page (iframe)

Run with Docker

docker build -t itchbox .
docker run --rm -p 8080:8080 -v itchbox_data:/data itchbox

Then open: http://localhost:8080

Run with docker-compose

docker compose up --build

Dev run (local)

python -m venv .venv
. .venv/bin/activate
pip install -e .
uvicorn app.main:app --reload --host 0.0.0.0 --port 8080

Notes / security

• MVP has no auth. Put it behind a reverse proxy / VPN if needed.
• ZIP extraction rejects path traversal attempts.
• Default max upload size: 200MB (set ITCHBOX_MAX_UPLOAD_BYTES).
• All state-changing POST forms (upload/update/delete) are CSRF-protected with a signed double-submit cookie. Set ITCHBOX_CSRF_SECRET to a stable value in production so CSRF tokens survive restarts; if unset, an ephemeral secret is generated and a warning is logged. Behind HTTPS, set ITCHBOX_CSRF_SECURE_COOKIE=true.