---
title: FrogQuest
emoji: 🐸
colorFrom: green
colorTo: yellow
sdk: gradio
sdk_version: 6.17.3
python_version: '3.12'
app_file: app.py
hf_oauth: true
pinned: true
license: apache-2.0
short_description: A text-image based RPG built to help fight procrastination
tags:
  - track:backyard
  - track:wood
  - sponsor:openai
  - sponsor:nvidia
  - sponsor:modal
  - sponsor:black-forest-labs
  - achievement:offgrid
  - achievement:offbrand
  - achievement:llama
  - achievement:fieldnotes
---

Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference

## FrogQuest

**[▶️ Try the Space](https://huggingface.co/spaces/build-small-hackathon/FrogQuest)**  
**[🎬 Watch the demo](https://youtu.be/n-2a7a56wWU)**
**[Read the Blog ](https://huggingface.co/blog/build-small-hackathon/frogquest)**

[Social media Post Linkedin](https://www.linkedin.com/posts/soumya532_try-frogquest-today-ugcPost-7471943345662021632-rmnx/?utm_source=share&utm_medium=member_desktop&rcm=ACoAAETNtiwB6QJ_lnhIW_3QCLWUz5B_HzSts-E)

Turn your real life goals into an 8-bit pixel-art text-adventure quest log where **you** are the
hero. Named for the "Eat That Frog" method: your hardest/most important task is the **frog** — the
boss quest you face first.

- **Nemotron Nano 4B** (text only, via llama.cpp on ZeroGPU) writes the quest JSON — Eat That Frog
  prioritization, linked sub-task chains, and optional self-care bonus quests.
- A fixed pixel-art frontend (`gr.Server` custom UI) renders that JSON as the quest log.
- **FLUX.2 [klein] 4B** (diffusers) generates each quest's image using your uploaded photo as a
  reference, then edits that same image into success / "retreat to fight another day" states.

Your photo and quest state live in your browser (localStorage) **and** in a private per-user JSON
record on the Space's storage. **Sign in with your Hugging Face account** (top right) and the
record is keyed to your account — same state on any device, nothing to remember. Logged out, it's
keyed by a random **Hero Code** shown in the left panel instead — paste it on a new device (or
after a cleared browser) to get everything back. The photo is sent to the GPU only transiently
during generation.

NOTE: after enabling/changing `hf_oauth`, fully restart (factory rebuild) the Space so the OAuth
login route gets registered — clicking Sign in before that yields a "Could not parse server
response" error.

### Durable storage (Storage Bucket)

For the server-side record to survive Space restarts, mount a HF **Storage Bucket**:
1. Create a bucket at https://huggingface.co/new-bucket (private is fine).
2. Space **Settings → Storage Buckets → Mount a bucket** → pick it, mount path **`/data`**,
   read-write.
The app writes `users/<hero-code>.json` files there (`store.py`; `FROGQUEST_DATA_DIR` overrides the
location, and without any mount it falls back to the container's ephemeral disk — fine for testing,
wiped on rebuild).

### GPU backend (ZeroGPU or Modal)

The GPU work (quest JSON + images) runs through a pluggable backend chosen by the
`FROGQUEST_BACKEND` env var. The frontend, signatures, and behavior are identical either way.

**`zerogpu` (default).** Everything runs in-Space on ZeroGPU.
- Set the Space hardware to **ZeroGPU**.
- First quest generation cold-downloads the models, then runs fast.
- Subject to ZeroGPU daily quotas (anon 2 min, free 5 min, PRO 40 min per day).

**`modal` (opt-in).** The Space runs on CPU-basic and offloads GPU work to [Modal](https://modal.com)
(dedicated GPU, pay-per-second, no quota). Switching is **two steps** — the env var alone does NOT
change hardware:
1. Set the Space hardware to **CPU basic**.
2. Add a Space **variable** `FROGQUEST_BACKEND=modal`.

One-time Modal setup:
1. `pip install modal` and `modal token new` (authenticate).
2. `modal deploy modal_app.py` (deploys the `frogquest` app: an `LLM` class + a `Flux` class).
3. Add `MODAL_TOKEN_ID` and `MODAL_TOKEN_SECRET` as Space **secrets** so the Space can call Modal.
4. Optional: set `FROGQUEST_MODAL_FLUX_GPU` before `modal deploy` to pick the image GPU
   (default `A10G`; `L4` cheaper; `L40S`/`A100-40GB` if it OOMs).

Optional: rename `requirements-modal.txt` → `requirements.txt` on the Space to skip installing the
heavy GPU libs (torch/diffusers/llama-cpp) and speed up CPU-basic builds.


![image](https://cdn-uploads.huggingface.co/production/uploads/67e018cc3d11aa67c1f911ee/JT7jD-sWNuK5bIp13g67O.png)