Sotto：自托管 AI 语言学习平台，接入 Claude 或 Codex 做私密练习

Quick Start

Install and start Docker with Compose v2, then run this in a terminal on Linux or macOS. On Windows, use a WSL2 terminal with Docker Desktop integration enabled:

curl -fsSL https://sotto.fm/install.sh | bash

The installer pulls the pre-built images, asks how to connect your AI (an API key, your local Claude Code or Codex CLI with no key, or your Claude agent on a VPS over SSH), writes config to ~/.sotto, and starts everything. Local CLI login refreshes travel through a networkless credential-sync sidecar that copies only the CLI auth JSON into the app containers.

The installer checks image availability before changing configuration and pins a matching web and worker release. It asks for the first Admin profile and shared password locally before the web app opens. OpenAI can supply generation and speech with one key. Other agents need a separately configured speech provider for listening and speaking.

Desktop controls: Unsigned preview launchers for macOS .dmg, Windows .exe, and Linux .AppImage are available from sotto.fm/download. Install the stack with the terminal command above first. Sotto Host starts and stops that installation. Your OS may require an explicit security override. On Windows, the launcher must be pointed at the installation inside WSL; using the browser from WSL is the simpler path.

1. Open the local URL and enter the shared password set during installation. You can save a passkey when prompted or skip it, then choose the Admin profile.
2. Configure languages and providers.
3. Take the placement test and start your first class.

Manage it from ~/.sotto: docker compose logs -f, docker compose down.

Update with sotto-host update. See the installation and troubleshooting guide if Docker, image downloads, or startup fail.

For the full self-hosted journey, see User Flows: start the stack, create a course, take a class, use the iPad workbook, connect devices, and maintain the deployment.

Why Sotto?

Every serious language app is closed, hosted, and subscription-funded. Your progress, your vocabulary, and the model that teaches you all live on someone else's servers.

The social side is its own barrier. Private tutoring, classroom speaking, and conversation exchange can be valuable, but they also put learners on the spot with a stranger or a room waiting. Sotto gives them a private rehearsal loop first.

There is also learning-tool fatigue. Sotto should not feel like another AI language chatbot with an empty prompt box. It wraps the models you already run in a structured course, practice, memory, and teacher follow-up loop.

Sotto inverts that. You run the application, database, and files, connect your own Claude or Codex, and choose the context it can use. Content sent to configured cloud AI, speech, search, or storage providers is processed under those providers' terms; local providers can keep processing on infrastructure you control.

The differentiators

• Taught in your own context: connect your agent and grant the context you choose: notes, goals, and what you're working on. Lessons, readings, and listening are drawn from that, not generic content.
• Low-pressure rehearsal: repeat speaking, writing, and listening practice privately before you try it with a teacher, tutor, classmate, or stranger.
• Not another AI chatbot: learners get classes, prompts, recordings, rubrics, review queues, and memory practice instead of another blank chat window.
• You own the learning stack: run it with your keys, your database, and your files. No Sotto account holds your progress hostage.
• Pedagogy over gamification: mastery gates use retrieval practice; adaptive listening uses comprehensible input (Krashen's i+1); the memory graph uses SM-2 spaced repetition. Progress is measured by demonstrated mastery, not streaks.
• Bring your own stack: LLM, TTS, STT via explicit provider selection, BYOK, or a keyless local agent. You pay your providers directly; nothing is billed through the build you run.

What You Get

A complete CEFR course across five graded skills, on a stack you control:

The rest of the loop:

• Classes gated by mastery: you cannot advance until you pass; failed sections regenerate in a similar form without copying the old one.
• Ungated practice: drill any single skill on your own time, driven by spaced repetition and separate from the graded classes. Use it as private rehearsal before live interaction, not as a human replacement.
• Personal memory graph: a per course, Obsidian style vocabulary and grammar graph with SM-2 spaced repetition that drives review, seeds the listening episode, and renders as an interactive Cytoscape visualization.
• Sourced classes: build a class from a real article, paper, or YouTube link, or from a topic in your interests. Sotto extracts it, levels it to your CEFR, and teaches from it with verified [N] citations.
• Live conversation: when you are ready, speak and hear real time translation in either direction through the Gemini Live API. New words you hit feed straight into your memory graph. Runs on your own Google key in Settings, and stays hidden until you add one.
• Practice exams: full, multi section mock exams modeled on each language's flagship (Goethe-Zertifikat, DELE, Cambridge English, or a generic CEFR mock), with a mock band and feedback by section. Practice only, never an official score, and never changes your level.
• Notes that shape the course: tell Sotto your goals and background once; it threads through placement, classes, and practice.
• Flexible language pairs: English to German, English to Spanish, and Spanish to English ship as hand authored reference curricula that set the quality bar; other selected native to target pairs are composed by your configured model or agent on demand and cached per pair.
• iPad workbooks: a PDF workbook for any class, with cover, class map, reading and writing space, speaking prep, QR links back to the web class, and a server rendered PDF built for GoodNotes style annotation.

The Learning Loop

flowchart LR
    P([Placement]) --> C
    C["Mastery-gated class<br/><sub>grammar · reading · listening · speaking · writing</sub>"]
    C -->|pass| N([Next class adapts])
    C -->|fail| R[Regenerate a fresh form] --> C
    N --> C
    PR[Ungated practice] --> G
    C --> G[("Memory graph<br/>SM-2 spaced repetition")]
    G -. seeds due vocab .-> C
    G -. due reviews .-> PR

Loading

Everything a learner does, classes and practice alike, feeds one course scoped memory graph. Due and weak items resurface in the next class's adaptive content and in practice.

How Sotto Compares

The closest peer is genuinely good: OpenLingo is also open source (MIT), can run on your own stack, and supports BYO LLM, with SM-2 spaced repetition, Whisper speaking exercises, and a similar stack (Next.js 16 / React 19 / PostgreSQL 16). Credit where due. Where Sotto goes further: a structured CEFR course gated by mastery across five graded skills, including writing with inline corrections and pronunciation scoring by rubric; a keyless local agent path through Claude Code or Codex; a fully offline path with local LLM, STT, and TTS; an interactive memory graph; adaptive listening seeded by your due vocabulary; a first party terminal client; and iPad workbooks.

_{✅ publicly documented full support · 〰️ partial, adjacent, or limited support · ❌ public product model indicates no · n/a means no public docs found. This is not proof the feature is impossible, especially for closed apps with regional experiments. Values reflect public repo/site/App Store/Google Play/help pages checked in June 2026. OpenLingo: pretzelai/openlingo documents MIT OSS, Docker/PostgreSQL setup, provider API keys, SM-2 SRS, tutor conversations, translated reading material, OpenAI TTS, and Whisper STT; no public terminal client, Pencil workbook, local no cloud STT/TTS path, mastery gates, memory graph, or rubric pronunciation score found. Duolingo publicly documents CEFR/ACTFL alignment via Duolingo for Schools, spaced repetition research/use, and Max/Explain My Answer/Roleplay, but not self hosting, BYOK, workbook export, or source grounded class generation. Speak, Praktika, and TalkPal publicly emphasize conversation and feedback; the table only gives full credit where the specific capability is named clearly. Workbooks: Pimsleur offers replacement reading booklet PDFs, so it earns 〰️ there, but not a generated iPad class workbook with web class links. Sotto values reflect the build you run; corrections welcome via PR.}

Concepts

A quick map of the nouns you'll meet in the app and the code:

The audio entity is called Episode rather than Lesson or Class because those two words were already taken: Lesson is the curriculum node and Class is the gated unit. Episode keeps the model unambiguous.

Architecture

apps/web          Next.js 16 App Router: web UI, API routes, Prisma schema, Vitest tests
apps/desktop      Tauri launcher: runs the whole stack on your machine, no terminal
tui               sotto: a headless terminal client (Rust): learn from your terminal, tmux friendly
packages/shared   Shared types, Zod schemas, brand copy
packages/mcp      MCP server: exposes Sotto tools to Claude Code / Codex locally
packages/groundcheck       Submodule: domain-aware reference verification
packages/learning-model    Submodule: Bayesian mastery and practice priority

Prefer the terminal? sotto (tui/) is a keyboard driven TUI client for vocab SRS, listening, speaking, classes, exams, and native audio in a single pane. cargo install sotto-tui (the installed command is sotto), then sotto login with a token from the web app's /settings/devices.

Evidence and learning packages

Two small public submodules encode Sotto's evidence models. Recursive clones and CI checkouts build and test both real implementations.

The split matters: source verification asks whether a reference is credible; learner modeling asks whether a person has mastered a skill. Both are probabilistic, but they use different evidence and should evolve independently.

Runtime stack

• PostgreSQL 16 + Prisma 7: user data, vocabulary graph, progress via a node postgres driver adapter.
• Redis 7 + BullMQ: heavy async work such as generation, scoring, and audio stitching.
• Explicit provider resolution: resolveLearningAi, resolveTtsProvider, and resolveSttProvider pick the configured provider, never by key availability.
• Keyless local agent: select Claude Code or Codex to route generation through your local CLI with no outbound API key.
• MCP server (packages/mcp): your local agent calls ingest_agent_output and other Sotto tools directly.
• Web + PWA: Next.js + React, installable from any browser; a Tauri desktop launcher runs the stack locally with no terminal.

Self-host

One command (recommended)

curl -fsSL https://sotto.fm/install.sh | bash

During install you choose how Sotto reaches your AI:

• An API key (OpenAI or Anthropic): simplest.
• Your local Claude Code or Codex CLI: bring your own agent; a networkless sidecar snapshots only its auth JSON into the container, no API key.
• Your agent on a VPS, over SSH: Sotto runs ssh you@vps claude ... for every LLM call (CLAUDE_CODE_SSH_HOST), so your data can stay on your machine.

Keeping it up to date

The installer puts a sotto-host command on your PATH:

sotto-host update              # move to the newest published build
sotto-host update --check      # say what would change, change nothing
sotto-host update --to v0.3.1  # pin a released version
sotto-host update --to 2ce63555 # or an exact commit
sotto-host status              # pinned tag, running version, health
sotto-host rollback            # back to the tag the last update replaced

An update dumps the database, refreshes the compose file, pulls the images, runs migrations, and waits for the health endpoint before calling it done. If the stack does not come up, the dump and sotto-host rollback are both there. Migrations are forward-only, so a rollback returns the images, not the schema. The Sidedoor cutover copies installed provider, model, storage, learner, and encrypted credential state in one transaction while the active release keeps running. Source tables are removed only after the candidate passes its health check. A conversion error rolls back the transaction and stops the update.

Installed before this command existed? Fetch it once:

mkdir -p ~/.local/bin && curl -fsSL https://sotto.fm/sotto-host -o ~/.local/bin/sotto-host && chmod +x ~/.local/bin/sotto-host

From source (contributors)

Prerequisites: Node.js 24, Docker, FFmpeg.

git clone https://github.com/affromero/Sotto.git
cd Sotto
npm run setup     # deps, .env.local (BYOK_ENCRYPTION_KEY), Postgres + Redis, schema, seed
npm run dev

Then open localhost:3000.

Run it 100% offline

No cloud key for any layer. The LLM, speech recognition, and speech generation all run on your own hardware. One opt in profile brings up Ollama (LLM), faster-whisper (STT), and the bundled Kokoro TTS sidecar:

docker compose --profile local up -d        # ollama + whisper + kokoro
docker exec sotto-ollama ollama pull qwen3   # any multilingual model: qwen3 / gemma3 / llama3.3

Open Sotto's welcome flow or Admin settings and save these connections:

Sotto stores provider selection, endpoints, models, voice IDs, and encrypted credentials through Sidedoor. It does not read provider configuration from the process environment. Multilingual support includes Qwen3 / Gemma 3 for generation, Whisper large-v3-turbo for pronunciation, and Kokoro for narration. A GPU helps the LLM but is not required. Whisper and Kokoro run comfortably on CPU. A custom local TTS sidecar only needs GET /health, GET /voices, and POST /tts. See docs/05-provider-extension-guide.md.

Bring your own agent or provider credentials

Choose Claude Code or Codex in the welcome flow when running from source. Optional SSH agent settings remain deployment environment variables because they describe the runtime connection:

# CLAUDE_CODE_SSH_HOST=you@vps
# CODEX_SSH_HOST=you@vps
# SOTTO_AGENT_SSH_KEY_PATH=/home/sotto/.ssh/id_ed25519
# SOTTO_AGENT_SSH_KNOWN_HOSTS_PATH=/home/sotto/.ssh/known_hosts

You can also select OpenAI for AI, speech generation, and speech recognition, then save one OpenAI credential in the welcome flow. Sidedoor encrypts it and shares it across those capabilities.

.env.oss.example defaults to local PostgreSQL, local Redis, local file storage under .sotto/storage, and payments disabled.

Dedicated storage ownership connections require DATABASE_URL to reach PostgreSQL directly or through session pooling. Transaction pooling cannot preserve their session advisory locks. The standard Compose database connection meets this requirement.

Your devices and household

The product runs on your own stack: you run it, then reach it from anywhere.

• Desktop. Sotto Host (a tiny Tauri launcher in apps/desktop/, from sotto.fm/download) runs the whole stack on your computer with no terminal. Open it, click Start, and it brings up the containers and opens the app.
• Web and PWA. Installable from any browser. Add to home screen on a phone, tablet, or laptop for full screen access against your server.
• Terminal. sotto is a headless Rust + ratatui client. Learn from a tmux pane while you code, with native audio playback and mic recording. See Terminal client below.
• Reach it from anywhere. The installer can open a secure public URL with one command (cloudflared quick tunnel, no account), or point a domain at the server and let Caddy handle TLS.

One password, local profiles. Local setup creates the first Admin profile and shared password before web access. Learners choose a profile after entering that password. Each profile keeps its own courses, progress, vocabulary graph, and keys.

The entry screen shows only Password and Continue. After password entry, Sotto offers to save a passkey with Apple Passwords or another WebAuthn manager. This step is optional. A saved passkey opens the profile picker on later visits. Anyone admitted can select Admin and change settings. Selecting another profile removes Admin access. Admin can revoke passkeys in App access.

If you lose the shared password, run sotto-host access reset on the server. The command asks for a new password without echoing it. Reset signs out existing sessions and revokes passkeys.

Teacher-run mode is the natural classroom shape. The current profile model already points there: a teacher self-hosts Sotto, creates one profile per student, and keeps practice data on school-controlled infrastructure. The next product layer should add teacher-authored homework, class-prep scenarios, per-student follow-up queues, and reviewable AI feedback so Sotto prepares students between lessons without replacing the teacher.

Learning surfaces

Sotto is one learning system with deliberately different surfaces. The web app is the interactive, graded class. The iPad workbook is the premium Pencil surface for slow study, annotation, and handwriting. The TUI is the headless terminal surface for learners who want the full loop from a tmux pane.

The workbook is intentionally not a web page in disguise. It is generated from the same class contract, but the layout optimizes for Pencil space, page rhythm, and offline annotation. The native iPad app targets iPadOS 18+ so Sotto can use the modern PencilKit toolbar APIs; generated workbook PDFs can still be exported to GoodNotes or another annotation app. The web class remains the source of truth for audio, recording, grading, regeneration, and progress.

Terminal client (sotto)

A premium headless client in tui/: the whole platform from a terminal, so you can learn from a tmux split while you code. Pure Rust (ratatui), it talks only to your server's /api/v1 over HTTP and ships no business logic of its own.

cargo install --path tui      # builds the `sotto` binary
sotto login                   # redeem a pairing code from Settings -> Devices
sotto                         # launch the TUI against your server

• Everything the web app does: courses, classes gated by mastery across all five skills, ungated practice, the vocabulary spaced repetition loop, mock exams, and adaptive listening.
• Audio in the terminal: segment playback (rodio) and microphone capture for speaking attempts (cpal -> WAV), uploaded for the same async grading the web app uses.
• Contextual Q&A: pause a listening segment and ask a question; the answer streams back inline.
• Accounts: sotto accounts, sotto switch, sotto logout, and sotto whoami manage multiple servers/profiles (stored in ~/.config/sotto), plus an in TUI switcher.

The typed client is generated from the same Zod schemas the web app uses (packages/shared -> OpenAPI -> progenitor), so the contract never drifts. See tui/AGENTS.md and §9 of the architecture diagrams.

Bring your own Claude / Codex

Sotto is built around BYOK from the start, surfaced three ways:

1. Keyless local agent: select Claude Code or Codex in Sotto, with no API key. Sotto checks CLI version and login separately, discovers Codex models live, and refreshes local Docker credentials through a networkless sidecar.
2. MCP server: add packages/mcp to your Claude Code or Codex config and call ingest_agent_output to push content from any agent workflow straight into Sotto.
3. BYOK in Settings: store encrypted per account API keys (LLM, TTS, STT), encrypted at rest with BYOK_ENCRYPTION_KEY. You pay your providers; Sotto is the infrastructure layer.

Status

The full learning loop ships today and runs on your own stack:

• Clean OSS core: AGPL-3.0; .env.oss.example, npm run setup, local storage default.
• BYOK / own agent: keyless claude-code/codex, encrypted per account keys, MCP ingestion.
• Placement to any language course: CEFR placement assigns a level and creates a directed course for any native to target pair.
• Classes gated by mastery across all five skills, with similar regeneration on failure.
• Ungated practice + learner notes: skill practice driven by spaced repetition; notes shape placement, classes, and practice.
• Vocabulary memory graph: per course SM-2 graph, Cytoscape visualization, drives review + adaptive listening.
• Sourced classes: build a class from a real article, paper, or YouTube link, or from a topic in your interests, leveled to your CEFR with verified [N] citations and a sources panel.
• Practice exams: full multi section mock exams modeled on each language's flagship (Goethe / DELE / Cambridge) at your level, with a mock band and feedback by section. Clearly unaffiliated practice, never an official score.
• Live conversation: live spoken translation (Gemini Live) on your own Google key; new vocabulary feeds the memory graph.
• Runs 100% offline: keyless local LLM, STT, and TTS (Ollama / faster-whisper / Kokoro) via docker compose --profile local.
• Households + your devices: first profile becomes owner, add isolated learner profiles and share the deployment password only with your household; desktop launcher (Sotto Host), installable PWA on any device, one command secure tunnel.
• Terminal client: sotto, a Rust + ratatui headless client with in terminal audio playback and recording; the full learning loop over /api/v1.
• iPad workbooks: PDF workbooks for any class; generated by the web app, ready for GoodNotes style annotation, and linked back into the exact web class sections.

Planned teacher mode: a teacher-run self-hosted deployment where profiles are students, homework is assigned as private rehearsal, and follow-up summaries make it easy to prepare the next class for each student. This should be teacher-controlled by design: teachers set the goals, sources, rubrics, and review path; Sotto handles repetition and evidence capture.

Planned optional managed offering: hosted infrastructure for non technical learners, including workers, storage, scheduled generation, and provider routing as a convenience layer. The learning stack itself stays open and can still run on your stack.

Development

npm run dev           # web + workers
npm run dev:web       # web only
npm run dev:workers   # workers only
npm run build
npm run lint
npm run type-check
npm run test
npm run ci            # lint + type-check + test + build (run before every commit)

See CONTRIBUTING.md to get started.

Contributors

Sotto is built with contributions from its community. Thanks to Anton Sannikov (@asannikov), our first external contributor, for fixing setup and first-lesson provider issues.

See all contributors and the changelog for contributions included in each release.

Related Projects

License

AGPL-3.0 (full text). Free to run, modify, and redistribute under the same terms. If you run a modified version as a network service, you must publish the source.

_{Built for people who'd rather own their learning than rent it.}

Dead-code checks

The Dead code workflow runs on pull requests, main-branch pushes, and weekly. It uses the pinned shared maintenance action to reject new findings, stale reviewed exceptions, and scanner failures. Reports are attached to each workflow run. Dependabot updates the shared action and Knip.

Keep runtime entry points in knip.json. Any retained finding in .maintenance-exceptions.json needs an exact identity and a review reason.

Knip excludes the independently versioned groundcheck and learning-model submodules. Their tests and builds remain part of repository CI. The standalone desktop launcher has its own Knip scan and dependency updates, since it is intentionally outside the root npm workspaces.