What is Companion Space?

Companion Space is a local-first anime companion and study application that lets users create independent learning spaces, import their own materials, and interact with virtual characters via text or real-time voice. It features VRM 3D avatars with lip-sync, expressions, and gaze tracking, retrieval-augmented generation with answer citations, and replaceable AI providers including OpenAI-compatible APIs, Ollama, and a built-in Mock for offline testing. An optional neural TTS sidecar (Qwen3-TTS) runs on NVIDIA GPU. The stack runs via Docker Compose with Caddy providing local HTTPS, a Next.js frontend, and a FastAPI backend. All data stays on the user's machine by default; provider credentials are stored in an encrypted server-side vault. Mobile access is available through opt-in Capacitor Android/iOS wrappers that pair with a trusted HTTPS origin.

Should you self-host Companion Space?

Companion Space scores 42/100 on selfhost.directory (how scoring works) and ranks #80 of 120 in AI Assistant. It has 338 GitHub stars.

There was no stable release in the past 12 months, so check the repository's recent activity before you rely on it.

Setup is advanced: plan for several services and some ongoing maintenance. It is Apache-2.0-licensed and written mostly in Python.

Its closest alternative on selfhost.directory is hermes-agent (89/100, 257 989 stars). It scores higher overall, so compare the two before you pick. See Companion Space vs hermes-agent side by side.

Features

Encrypted provider vault
Health Checks
Independent learning spaces
Local-first Privacy
Mobile device pairingTest shells, not store releases; requires trusted HTTPS origin
Optional neural TTSRequires NVIDIA GPU and ~2.5 GB model download
RAG with citations
Replaceable AI providers
Text and real-time voice chat
VRM 3D avatars with expressions

How to configure Companion Space

ALLOWED_ORIGINShttps://companion.localhostComma-separated browser origins. The packaged Android/iOS launcher origins are always included explicitly; wildcard origins are not used.
Comma-separated browser origins. The packaged Android/iOS launcher origins are always included explicitly; wildcard origins are not used.
ALLOW_ML_FALLBACKtrue
API_BASE_URLhttp://api:8000
API_MALLOC_ARENA_MAX2Smaller glibc arena counts reduce fragmentation without changing model quality.
Smaller glibc arena counts reduce fragmentation without changing model quality.
API_MEMORY_LIMIT5g
API_MEMORY_RESERVATION2g
APP_BASE_URLhttps://companion.localhost
APP_DISPLAY_NAMECompanion Space
APP_ENVdevelopment
APP_HOSTcompanion.localhost
AUDIO_PERSIST_ENABLEDfalse
BUILTIN_NEURAL_TTS_ENABLEDfalse
CADDY_MEMORY_LIMITRuntime container caps total 11.9375 GiB by default. Pair these with the repository's 14 GB WSL cap so Docker/WSL stays about 12.5% below a 16 GB host. Keep the TTS value unchanged unless monitoring proves a smaller cap is safe.
Runtime container caps total 11.9375 GiB by default. Pair these with the repository's 14 GB WSL cap so Docker/WSL stays about 12.5% below a 16 GB host. Keep the TTS value unchanged unless monitoring proves a smaller cap is safe.
CADDY_MEMORY_RESERVATION64m
CITATION_REQUIREDtrue
COMPANION_MOBILE_TRUSTED_ORIGINSBuild-time allowlist for apps/mobile. Set this to a real phone-reachable HTTPS origin before running build:mobile; companion.localhost is not a phone target.
Build-time allowlist for apps/mobile. Set this to a real phone-reachable HTTPS origin before running build:mobile; companion.localhost is not a phone target.
COMPOSE_PARALLEL_LIMIT1Build one image at a time so peak build work stays inside the WSL-wide cap.
Build one image at a time so peak build work stays inside the WSL-wide cap.
COMPOSE_PROFILESEnable this GPU-only service with COMPOSE_PROFILES=neural-tts.
Enable this GPU-only service with COMPOSE_PROFILES=neural-tts.
EMBEDDING_MODEL_NAMEBAAI/bge-m3
EMBEDDING_PROVIDERbge_m3
LOCAL_NEURAL_TTS_BASE_URLhttp://neural-tts:8001
MAX_DOCUMENT_SIZE_BYTES52428800
MAX_EXTRACTED_TEXT_CHARS2000000
MAX_PDF_PAGES500
MEMORY_WRITE_ENABLEDtrue
MOBILE_DEFAULT_SNIcompanion.localhostSet this only when APP_HOST also exposes a direct IP HTTPS origin. It lets Caddy serve the matching certificate to clients that omit SNI for IP hosts.
Set this only when APP_HOST also exposes a direct IP HTTPS origin. It lets Caddy serve the matching certificate to clients that omit SNI for IP hosts.
NEXT_PUBLIC_API_BASE_URL/
NEXT_PUBLIC_LIVE2D_RUNTIME_BRIDGE_URLOptional, same-origin modules supplied by a license holder. Leave empty to import Live2D/Spine AIRI assets safely while keeping their rendering blocked.
Optional, same-origin modules supplied by a license holder. Leave empty to import Live2D/Spine AIRI assets safely while keeping their rendering blocked.
NEXT_PUBLIC_REALTIME_WS_URL/api/v1/sessions/:sessionId/realtime
NEXT_PUBLIC_SPINE_RUNTIME_BRIDGE_URL
OBJECT_STORAGE_PATH./storage
RERANKER_MODEL_NAMEBAAI/bge-reranker-v2-m3
RERANKER_PROVIDERbge_reranker_v2_m3
RETRIEVAL_TOP_K4
SQLITE_BUSY_TIMEOUT_MS5000
TTS_DEVICEcuda
TTS_MALLOC_ARENA_MAX2
TTS_MEMORY_LIMIT6g
TTS_MEMORY_RESERVATION3g
TTS_MODEL_CACHE_PATHqwen3_tts_model_cacheOptional bind mount for the ~2.5 GB cache, for example ./qwen3-tts-cache
Optional bind mount for the ~2.5 GB cache, for example ./qwen3-tts-cache
WEB_MEMORY_LIMIT768m
WEB_MEMORY_RESERVATION256m