Flash

Spaced-repetition flashcards you study with your AI. Flash is a small self-hosted server: a web app for your decks and an MCP server that lets Claude, ChatGPT, Grok or any MCP client create cards from what you're learning, quiz you out loud, grade your answers and file the reviews with the FSRS scheduler. One Rust binary, one SQLite file, no accounts anywhere but yours.

The hosted version, with self-serve signup, Google/Apple sign-in and a community deck library, is at flashmemorize.com. iOS and Android apps are on the way and not out yet. This repository is the core it all runs on.

Today	Study	Connect your AI

_{Demo decks under the test persona; the conduction diagram is by Madhero88 via Wikimedia Commons, CC BY 3.0.}

Why not Anki + AnkiConnect?

AnkiConnect is a bridge into the desktop app: it only answers while Anki is open on that machine, and it speaks Anki's own JSON, not MCP. Flash is a server. It is reachable from your phone, from a Claude connector, from Claude Code in a terminal, all at once, and the scheduling lives in the server so every surface sees the same queue. It imports .apkg decks whole (cloze, hints, images, audio, LaTeX, typed answers, nested decks) and exports them back at any time, so trying it costs nothing.

Five-minute quickstart (Docker)

Code

git clone https://github.com/flash-cards/flash && cd flash
cp .env.example .env            # set FLASH_BASE_URL to the URL you'll reach it at
docker compose up -d
docker compose logs flash | grep enroll

The first boot finds an empty database and logs a one-time link:

Code

no users yet. Enroll the first admin within 24h at:
https://cards.example.com/enroll/<token>

Open it, add a passkey or a password, and you are the admin. Every later account is created from Settings → Invite: there is no public signup on a self-hosted Flash, by design.

Without Docker: cargo build --release -p flash-server, then run target/release/flash-server with the same environment variables. The binary embeds its templates and static assets; it writes under FLASH_DATA_DIR, plus short-lived scratch files for an import or export in the system temp directory (the systemd unit gives it a private one).

Upgrading

Terminal

docker compose pull && docker compose up -d

Everything Flash writes lives in the flash-data volume (/data in the container: the SQLite database, media, voice clips), and the image holds nothing of yours, so a newer image finds your data where the old one left it. On its first boot a newer version brings the database schema forward before it listens, one step at a time, each in its own transaction; /healthz then reports the new version. Migrations only go forward: take a copy before an upgrade if you may want to return, and do not start an older image on a volume a newer one has opened. A consistent copy is the volume with the container stopped:

Terminal

docker compose stop flash
docker run --rm -v flash-data:/data -v "$PWD":/backup debian:bookworm-slim \
    tar czf /backup/flash-data.tgz -C /data .
docker compose start flash

latest follows every release. ghcr.io/flash-cards/flash:0.3 takes patch releases only and :0.3.0 never moves; pin one of those in docker-compose.yml if you would rather choose when to move. What each version changed is in CHANGELOG.md, and a release that changes the MCP tools says so there: refresh the connector's tool definitions in each AI client after that upgrade. Without Docker the same holds for FLASH_DATA_DIR: keep the directory, replace the binary, start it.

Connecting your AI

Flash serves MCP at /mcp (Streamable HTTP) with OAuth 2.1: the client registers itself, sends you to Flash's login page, and gets a token scoped to your account.

Claude.ai / Claude mobile: Settings → Connectors → Add custom connector → paste https://<your host>/mcp. Claude's connectors need a publicly reachable HTTPS origin, so put Flash behind a reverse proxy with a certificate, such as Caddy:
Caddyfile
```
cards.example.com {
    reverse_proxy 127.0.0.1:8437 {
        header_up X-Real-IP {remote_host}
    }
}
```
and set FLASH_CLIENT_IP_HEADER=x-real-ip so the rate limiters see each visitor rather than the proxy (see the note under Configuration). A tunnel (Cloudflare Tunnel, Tailscale Funnel, ngrok) works the same way if you'd rather not open a port.
Claude Code: claude mcp add --transport http flash https://<your host>/mcp. Claude Code and Claude Desktop run on your own machine, so a LAN address works for the MCP connection as long as FLASH_BASE_URL matches what you paste. The web UI itself needs HTTPS or http://localhost: its session cookie is marked Secure, and a browser drops it over plain http to any other host (the server says so at boot).
ChatGPT (Plus and up, Developer mode): Settings → Apps → add the same URL as an MCP server. Grok: Connectors → New → Custom.

Once connected, say "quiz me on my pharmacology deck" and follow along. The web app at / is where you import decks, edit cards and read your stats. What the tools take and return, for anyone building a client, is in the MCP contract.

Configuration

Everything is an environment variable; the core needs only the first three. Optional groups are all-or-nothing: a partial set is a boot error, an absent set turns the feature off.

Variable	Default	What it does
`FLASH_BASE_URL`	`http://localhost:8437`	The public origin (`https://cards.example.com`). Passkeys, OAuth and every link in a mail are minted against it, so it must be what browsers actually see. A hostname, not an IP address: passkeys are bound to a domain, and `http://localhost:8437` is fine for a trial.
`FLASH_BIND`	`127.0.0.1:8437`	Listen address. The Docker image sets `0.0.0.0:8437`.
`FLASH_CLIENT_IP_HEADER`	unset	Header holding the real client address when a proxy is in front (`x-real-ip`, `cf-connecting-ip`). Unset uses the TCP peer. See the note below the table.
`FLASH_DATA_DIR`	`./data`	The SQLite database, import scratch space and media. Back this directory up.
`FLASH_SUPPORT_EMAIL`	unset	Shown on the pages that print a contact address.
`RESEND_API_KEY` + `FLASH_EMAIL_FROM`	unset	Outbound mail through Resend, the one provider supported today. The core sends exactly one kind of mail, the password-reset link, so without this there is simply no self-service reset. Both or neither.
`FLASH_DEV_MAIL_LOG=1`	unset	Instead of a provider, log the mail (and its link) to stdout.
`FLASH_MEDIA_R2_ENDPOINT`, `FLASH_MEDIA_R2_BUCKET`, `FLASH_MEDIA_R2_ACCESS_KEY_ID`, `FLASH_MEDIA_R2_SECRET_ACCESS_KEY`	unset	Keep media blobs in any S3-compatible bucket (S3, R2, MinIO, B2) instead of under the data directory. Most installs leave this unset. All four or none.
`FLASH_AI_PROVIDER`	unset	The switch for card generation and spoken-answer grading, and which model API they go through. `openai` is any endpoint speaking the OpenAI Chat Completions protocol, hosted or on your own machine: pasted text, text files, photos and recordings. `gemini` is the native adapter for that API, the one that also reads PDFs, documents, video and YouTube links, all of them together in one request, with a video of ten minutes or more read agentically (the model navigates it and loads only what the material needs). Unset, there is no Generate button, nothing else changes, and nothing is ever sent out. See Using your own model.
`FLASH_AI_BASE_URL`	unset	`openai` only, required: the endpoint's base in the shape `https://host/v1` (the server appends `/chat/completions`). A local model server is `http://127.0.0.1:<port>/v1`. Ignored by `gemini`, whose adapter knows its host.
`FLASH_AI_API_KEY`	unset	The key every call is made with, for either provider. Required; with `openai` it may be set empty (`FLASH_AI_API_KEY=`) for a local endpoint that needs none.
`FLASH_AI_MODEL`, `FLASH_AI_GRADER_MODEL`	the provider's own	The model that reads sources and writes cards, and the one that grades spoken answers and answers questions. `openai`: the model is required, passed through as you name it, and the grader defaults to it. `gemini`: `gemini-3.8-flash` and `gemini-3.5-flash-lite` unless set. Every call is recorded with the token counts the provider reported.
`FLASH_AI_OUTPUT`	`schema`	`openai` only: how the reply's shape is asked for. `schema` sends the JSON Schema as `response_format: json_schema` in strict mode. `json` asks for a JSON object and states the schema in the prompt, for endpoints without `json_schema`. `plain` sends no `response_format` and reads the JSON out of the text, for endpoints that ignore the field.
`FLASH_VOICE_INPUT`	`transcript`	What a spoken answer is graded from. `transcript` sends what the phone's or browser's own speech recognition heard, free. `audio` sends the recording itself for the grader to listen to, which is right on specialised terms and other languages and costs a fraction of a cent per card. The server accepts both whatever this says; the setting is what it tells the apps and the web page to send. With `openai`, `audio` carries the app's wav recordings; a browser records webm or mp4, which that protocol's audio part does not take, so browser study keeps to `transcript`.
`FLASH_AI_INPUTS`	unset	Unset, users may generate from everything the configured model reads (which includes video and audio, so mind what your key's plan charges). A comma list narrows that: `text,pdf,image,youtube,video,audio`. The picker offers only what is enabled. A name the model cannot read, or an unknown one, is a boot error.
`FLASH_PDFIUM_PATH`	unset	The Pdfium shared library: a file or the directory holding it. Without it `pdf` is dropped from the inputs (a boot error if `FLASH_AI_INPUTS` names it). The Docker image ships one; elsewhere `tools/fetch-pdfium.sh` (or `.ps1`) downloads the pdfium-binaries build for your platform into `./data/pdfium` and prints the line to set. The release tarball is a static binary and cannot load a shared library, so for PDF input use the Docker image or a build from source.
`FLASH_DOC_CONVERTER`	unset	A command that turns a Word, PowerPoint, spreadsheet or OpenDocument file into a PDF, so those can be dropped in too: a template with `{input}` (the file) and `{outdir}` (where the PDF must land), for example `soffice --headless --convert-to pdf --outdir {outdir} {input}` with LibreOffice installed. Unset, such files are refused with a sentence asking for a PDF. The program named is yours to install, sandbox and keep patched; Flash only bounds how long it may run and how large its PDF may be.
`FLASH_DOC_CONVERTER_TIMEOUT_SECS`	`120`	How long one conversion may run before it is killed.
`FLASH_TTS_URL`	unset	Natural voice for study. The sidecar in `tools/flash-tts` reads each card in one of 41 voices (American and British English, Japanese, Mandarin), a few cards ahead of the queue, and the clips are stored once and shared. Its engine is Kokoro-82M, the one voice engine supported today; the server knows only the sidecar's HTTP contract. `docker compose --profile voice up -d` starts it as `http://flash-tts:8880`; it runs on one CPU core in under 1 GB. Unset, study reads with the device's own voice and nothing else changes.
`FLASH_TTS_VOICE_DEFAULT`	`af_heart`	The voice new accounts start with, any id from `tools/flash-tts/flash_tts/voices.py`. Needs `FLASH_TTS_URL`.
`FLASH_TTS_TIMEOUT_SECS`	`90`	How long one clip's synthesis may take before the request is given up. Raise it if long card backs time out on a slow machine.

Accounts are created by an admin (the enroll link above, then Settings → Invite). Each account signs in with passkeys, a password, or both, and always keeps at least one method. Studying, reviewing and export are never gated by anything.

The sign-in, API and web-mutation rate limiters key on the client address. Behind a reverse proxy every request arrives from the proxy's address, so without more configuration the whole instance shares one bucket and the server says so in its log on every boot. Tell Flash which header carries the real address with FLASH_CLIENT_IP_HEADER: x-real-ip for Caddy (with the header_up line above) and nginx (with proxy_set_header X-Real-IP $remote_addr), cf-connecting-ip for Cloudflare. x-forwarded-for works too: the rightmost address, the one your proxy appended, is the one used. Only name a header when nothing but the proxy can reach the port: a header is forgeable by anyone who can connect directly. Values that are not addresses are ignored in favour of the peer, and IPv6 clients are keyed by their /64.

What plugs in

Flash is one binary and one SQLite file; everything else is something you point it at, and each is optional unless the table says otherwise. What ships today is what is listed, not a promise of more.

Piece	Setting	Supported today
Model API, for card generation and spoken-answer grading	`FLASH_AI_PROVIDER` and the `FLASH_AI_*` group	Any OpenAI-compatible Chat Completions endpoint, or Google Gemini through its native API. See Using your own model.
Natural voice, for study	`FLASH_TTS_URL`	The `tools/flash-tts` sidecar, whose engine is Kokoro-82M. No other engine.
Speech recognition, for voice study	none	Nothing on the server: the browser's or the phone's own recognizer hears the student. With `FLASH_VOICE_INPUT=audio` the recording goes to the model API instead.
Outbound mail, for password resets	`RESEND_API_KEY` + `FLASH_EMAIL_FROM`	Resend only. Without it there is no self-service reset; `FLASH_DEV_MAIL_LOG=1` prints the mail instead.
Media storage	`FLASH_MEDIA_R2_*`	The data directory on disk, or any S3-compatible bucket (S3, R2, MinIO, B2).
PDF rendering, for figures and page counts	`FLASH_PDFIUM_PATH`	The Pdfium shared library from pdfium-binaries; the Docker image ships it.
Office documents, for generation	`FLASH_DOC_CONVERTER`	Any command you name that writes a PDF; LibreOffice's `soffice` is the example. Yours to install and keep patched.
TLS and the public hostname	`FLASH_BASE_URL`, `FLASH_CLIENT_IP_HEADER`	Your own reverse proxy or tunnel in front of port 8437, required for anything beyond a trial on localhost: passkeys are bound to the hostname.
AI clients, inbound over MCP	none	Any MCP client with OAuth 2.1 (Claude, ChatGPT, Grok, Claude Code); they register themselves.

Using your own model

Every model call Flash makes (reading a source, writing cards, editing them in the review thread, grading a spoken answer) goes through one provider interface, and the provider is whatever FLASH_AI_PROVIDER names. Two shapes ship.

Any OpenAI-compatible endpoint (FLASH_AI_PROVIDER=openai). The Chat Completions protocol is what nearly every vendor and every local model server speaks, so three settings cover them all: FLASH_AI_BASE_URL, FLASH_AI_API_KEY and FLASH_AI_MODEL, the model name exactly as the endpoint knows it. This shape carries text, photos and wav or mp3 recordings. Endpoints differ in how they take a reply's shape and in what they read, so two more settings adapt to yours: FLASH_AI_OUTPUT (schema, json or plain) and FLASH_AI_INPUTS to drop what the endpoint cannot read (text alone for a text-only model).

The native Gemini adapter (FLASH_AI_PROVIDER=gemini). That API has file uploads and video navigation the compatible protocol lacks, so this is the shape for PDFs as documents, video files and YouTube links. FLASH_AI_API_KEY is the Gemini key; the models have defaults.

The popular endpoints, with the settings their own documentation describes as of September 2026. Anything else that speaks the protocol works the same way; this is the common set, not the allowed set. Check the provider's page for what a given model reads.

Provider	`FLASH_AI_BASE_URL`	`FLASH_AI_OUTPUT`	`FLASH_AI_INPUTS`	Notes
OpenAI	`https://api.openai.com/v1`	`schema`	text, image	`json_schema` strict and `json_object` both documented.
Google Gemini, compatible endpoint	`https://generativelanguage.googleapis.com/v1beta/openai/`	`schema`	text, image, audio	Images and audio in, `json_schema` out; no PDF-as-file, video or YouTube here, use `FLASH_AI_PROVIDER=gemini` for those. Google marks the endpoint beta.
Anthropic Claude	`https://api.anthropic.com/v1/`	`plain`	text, image	`response_format` is ignored and audio parts are stripped, so the schema goes in the prompt. Anthropic describes the layer as for testing rather than production.
Alibaba Qwen (Model Studio)	the compatible-mode URL of your region, from the console	`json`, or `schema` on the Qwen3.7-Plus/Flash/Max and Qwen3.8-Max/Flash series	text (image on the VL models)	`json_object` needs the word JSON in the prompt, which Flash's prompts carry.
DeepSeek	`https://api.deepseek.com`	`json`	text	`json_object` documented, `json_schema` not; vision not documented.
Mistral	`https://api.mistral.ai/v1`	`schema`	text, image	`json_schema` and `json_object` documented; images on the vision models.
Groq	`https://api.groq.com/openai/v1`	`schema` on the models Groq lists for strict mode, else `json`	text, image on its vision models	Images up to 20 MB, a few per request.
OpenRouter	`https://openrouter.ai/api/v1`	`schema` for models its directory flags for structured outputs, else `json`	per model	One key, many vendors; what a model reads is per model.
xAI Grok	`https://api.x.ai/v1`	`schema` (Grok 4 family)	text
Ollama, on your machine	`http://localhost:11434/v1`	`schema`, or `json` if a model refuses a schema	text, image	The key is required but ignored: set `FLASH_AI_API_KEY=`. Structured outputs work locally, not on Ollama's cloud.
LM Studio, on your machine	`http://localhost:1234/v1`	`schema`	text, image	Set `FLASH_AI_API_KEY=`.
vLLM, self-hosted	`http://<host>:8000/v1` or wherever you serve it	`schema`	per model	`json_schema` documented; the key is whatever you configured, else empty.

Every call is recorded with the token counts the endpoint reports, so what a model an operator brings is used for can be read from the ledger; what it costs is between the operator and the endpoint.

What is here, and what isn't

server.ts

crates/
├── flash-core     the scheduler wrapper, queue policy and domain types (no IO)
├── flash-store    SQLite: migrations, decks, cards, reviews, media, .apkg/CSV import and export
└── flash-server   the binary: web UI (askama + htmx), passkeys and passwords,
                   OAuth 2.1 + MCP, the JSON API the mobile apps use

The server exposes a small extension seam (flash_server::ext, flash_store::ext) that the hosted product plugs its billing, sign-in providers, plans and community into. None of that is in this repository, and the core never depends on it: what you run here is complete.

Contributing and support

Issues and pull requests are welcome; see CONTRIBUTING.md for how the code is laid out, how to run the tests, and the contributor license agreement. This is one person's project and the hosted service is where the time goes, so bug reports get read and fixed as they come, and feature requests are weighed against the roadmap rather than promised. If you would rather not run a server, the hosted version is a sign-up away.

License

AGPL-3.0-only. See LICENSE and THIRD_PARTY.md for the embedded assets. Contributions are accepted under the CLA in CLA.md, which lets the same code power the hosted service.