Companion Space: a local-first anime study companion you can self-host
本地优先的二次元陪伴学习应用 · Local-first anime companion and study app.
At a glance
- What is it?
- A Docker-deployed study app with VRM characters, cited document Q&A and realtime voice, running on your machine with Mock or self-chosen AI providers. Apache-2.0 code, carefully licensed characters.
- Who is it for?
- Companion Space fits self-hosters and students who want an anime companion study app under their own roof, are comfortable with Docker Compose and a local CA, and will stick to the Mock or self-chosen providers and the personal-use terms of the character models. Skip it if you need enterprise commercial rights to the characters, a store-ready mobile app, or zero-maintenance hosting.
- Can I use it commercially?
- Yes. Apache-2.0 is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 20 days ago.
- What is it written in?
- Mainly Python, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 17, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
A study companion that never leaves your machine
Companion Space is a local-first study application with an anime twist: you create separate spaces for courses, projects or interests, import your own materials, and study alongside a virtual character through text or realtime voice, with post-session review, memory and revision content organized afterward. Local-first is the operative promise. The app runs on your own computer, materials and credentials stay local, and requests reach external services only when you connect a provider such as an OpenAI-compatible endpoint or Ollama.
The stack is real infrastructure rather than a wrapped toy: Next.js for the web UI with browser-side VRM 3D characters, a FastAPI service, an optional neural TTS sidecar, and Caddy as the single HTTPS entry, all composed through Docker Compose. The code is Apache-2.0, and the README is bilingual from the first line, with the audience visibly Chinese-speaking students and self-hosters who want the character-companion experience without an account on someone else's cloud.
Quick start: Docker, Caddy, and a local certificate authority
Requirements are Docker Desktop or an equivalent engine plus Compose v2, and the README's first instruction is a negative one: do not enable the neural-tts profile yet. The quick start:
git clone https://github.com/Johnson-Durui/Companion-Space.git
cd Companion-Space
cp .env.example .env
docker compose up --buildAfter the build, you open https://companion.localhost and trust the Caddy local certificate authority, because the bundled Caddyfile uses tls internal, explicitly not public Let's Encrypt. The intended first path is the Mock provider, walking Vault, spaces, materials and character in order, so the app is explorable with zero AI credentials. A health endpoint at /healthz reports on the api and web containers, which carry their own healthchecks that Caddy waits on before serving.
What the companion actually does
The feature set maps to studying rather than chatting. Spaces isolate materials, characters and conversation history per course or project. Imported documents power retrieval-augmented answers, and the README specifies that answers keep their citations, the detail that separates study tooling from a chatbot. Voice is realtime and conversational, with continuous dialogue, playback and interruptions supported.
The character layer is more elaborate than expected: browser-local VRM 3D characters with lip sync, emotion, gaze and motion feedback, plus a 2D fallback. AI services are replaceable by design, with the Mock provider built in for zero-config exploration and OpenAI-compatible endpoints or Ollama for real models. One privacy affordance is stated as policy: long-term memory about you is written only after explicit confirmation, which is the kind of consent boundary companion apps usually discover they need after the incident.
The character licence table, which you should read
The code is Apache-2.0, and the characters are not, exactly. The README carries a licence table for the four original VRM companions, each an original custom model with embedded VRM permissions: personal commercial use allowed, enterprise commercial use not authorized. Additional restrictions travel inside the models: no excessive violence or sexual content, no political or religious use, no antisocial or hateful use, and no stripping the embedded metadata.
The README also records what is and is not redistributable: the repository publishes verified VRM binaries with hashes, while the precise painted textures and local Blender working files are not public, so a clean clone runs the models but byte-identical rebuilds are not promised. Legacy sample characters remain as licence specimens. For anyone forking this project, the summary is simple: the Apache code is the easy part, and the character assets carry their own contract that the NOTICE and third-party notices files govern.
The Windows path and optional neural voice
Windows gets first-class scripts rather than an afterthought. START-WINDOWS.ps1 targets 16 GB machines, tuning the WSL and Docker memory cap to 14 GB, with a skip flag for other machines, a separate local-start script when Docker is down, and a backup script that writes to a gitignored backups directory. The README's operational warnings read like incident notes: never copy the SQLite database or storage directory while the API is running, and always back up before replacing the API image.
The neural TTS voice is an opt-in Docker Compose profile, deliberate because it costs real resources: an NVIDIA GPU and about 2.5 GB of weights on first build. Until you enable it, the app runs on standard TTS, which keeps the default install light. This is the document that a self-hoster wishes every project shipped: the happy path, the resource-hungry path, and the backup discipline, separated and labeled.
Mobile pairing and the architecture underneath
Mobile is a tested shell, not a store product, and the README says so plainly: Android and iOS clients connect to the same service and need trusted HTTPS plus device pairing. Pairing runs through an eight-digit code generated in the web Vault, valid for five minutes, with refreshed credentials stored only in the Android Keystore or iOS Keychain and access tokens kept out of URLs, localStorage and logs. The web build uses same-origin relative addresses by default so one reverse proxy serves both desktop and phone hostnames without rebuilding per host, and the README notes that changing those build-time variables requires rebuilding the web image, not just restarting containers.
The component map holds no surprises after that: Next.js web, Capacitor mobile shells, FastAPI service, optional Qwen3-TTS sidecar, Caddy in front. Verification is a set of npm scripts covering typechecks, lint and asset tests, plus ruff and pytest for the API. No releases are published yet, and the last push was on 2026-08-29, so the project is self-hosted software in the literal sense: you run it from source at whatever commit you checkout.
Against hosted character apps and plain study tools
The obvious comparison is hosted character companions: accounts on someone's cloud, conversation history as the product, and personalities rented by subscription. Companion Space inverts every clause: self-hosted, local materials, providers you choose, memory that asks before it remembers. The cost is the self-hosting tax, Docker, a local certificate authority, and a machine that stays on when you want to study.
Against plain study tools, the characters are not cosmetic in intent: the realtime voice, the lip-synced presence and the post-session review loop are built around companionship as a retention mechanism for studying, and the retrieval-cited answers keep the substance honest. The project sits in a narrow but real gap: hosted character apps that own your data on one side, soulless flashcard databases on the other. Whether the gap deserves a Docker daemon is a question each student answers alone.
Editorial conclusion
Companion Space fits self-hosters and students who want an anime companion study app under their own roof, are comfortable with Docker Compose and a local CA, and will stick to the Mock or self-chosen providers and the personal-use terms of the character models. Skip it if you need enterprise commercial rights to the characters, a store-ready mobile app, or zero-maintenance hosting. Verify the core loop in one evening: run the four Docker commands, trust the local certificate, import one real PDF into a space, and check that the character's answers actually cite your document before committing your study workflow to it.
Frequently asked questions
What is the Companion app used for?
Companion Space is a local-first study companion: you organize materials into spaces, ask questions over them with cited retrieval-augmented answers, and study with a VRM character through text or realtime voice, with review and memory content organized after sessions.
Does Companion Space send my data to the cloud?
The app runs on your own computer and keeps materials and credentials local. Requests leave only toward providers you configure yourself, such as an OpenAI-compatible endpoint or Ollama, and long-term memory is written only after your confirmation.
Can Companion Space be used commercially?
The code is Apache-2.0, but the four original VRM characters carry embedded licences allowing personal commercial use only, not enterprise commercial use, with content restrictions and no metadata stripping. Read NOTICE and the third-party asset notices before any commercial plan.
Community notes