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)

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:

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

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:

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:

  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

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.