ClaraVerse: a self-hosted AI workspace with agent teams, layered memory and a Docker stack

The problem ClaraVerse targets: chat, agents and memory in one private stack

Most self-hosted chat interfaces stop at a conversation window with a model picker. ClaraVerse positions itself against that shape. The README frames the project as replacing ChatGPT, Claude, N8N and image generation with your own hosted LLM, keys and compute, and it lists three things it says comparable chat UIs treat as afterthoughts: agents that work as a team, memory that behaves like a memory system rather than a flat note list, and a licence that does not start charging once a project gains attention.

The intended user is someone who already has local inference running. The README states that if Ollama or LM Studio is running on the machine, ClaraVerse detects it and imports all models with zero configuration. That is the target deployment: a workstation or small server with a GPU, a local model runtime, and a preference for keeping conversations on hardware you control. Chats are stored locally on the device by default, with optional encrypted sync if you want the same history on more than one machine.

The scope is broader than chat. Crew, a visual workflow builder, Telegram integration, a terminal coding agent and knowledge bases all ship in the same repository. That breadth is the pitch and also the operational cost, which the rest of this review deals with.

How ClaraVerse is put together: React frontend, Go backend, and five stateful services

The Dockerfile shows a three-stage build. Stage one runs npm ci --legacy-peer-deps on frontend/package.json and produces a Vite build. Stage two compiles the Go backend from backend/cmd/server with CGO_ENABLED=1 and links it statically with -ldflags "-s -w". Stage three is an Alpine 3.20 runtime that carries ca-certificates, tzdata, wget, bash and chromium, which suggests headless browser work somewhere in the tool chain. Databases are deliberately not in the image; they run as separate containers.

The compose file makes the data flow concrete. MongoDB holds conversations, workflows and persistence. MySQL holds providers, models and capabilities, and the compose file mounts ./backend/migrations into /docker-entrypoint-initdb.d so schema migrations run on first boot. Redis handles scheduled agent triggers and cross-instance WebSocket pub/sub, started with appendonly yes and a 100 MB maxmemory cap under the allkeys-lru policy. SearXNG and Qdrant appear in the production compose file, and the README states that Qdrant plus an embeddings sidecar are required for Knowledge bases and the search_knowledge tool.

Provider discovery is a polling loop, not an event stream. The README says discovery runs every two minutes, imports models when a provider appears, disables the provider when it goes offline, and re-imports models when it returns. Memory works differently: facts are extracted in the background, stored encrypted with AES-256-GCM under a per-user key derived through HKDF, and split into a pinned tier that always injects and a recall tier retrieved by embedding similarity. Unused recall entries decay and archive themselves. The model calls search_memory and add_memory as tools mid-conversation, the same way it calls any other tool.

Installing ClaraVerse with docker compose and running a first chat

The README gives two paths. The one-line installer targets Linux and macOS and chains an init step:

curl -fsSL https://raw.githubusercontent.com/claraverse-space/ClaraVerse/main/cli/install.sh | bash && claraverse init

The Docker Compose path is the one that brings up the full stack, including the sidecars that Knowledge bases need:

git clone https://github.com/claraverse-space/ClaraVerse.git
cd ClaraVerse
docker compose -f docker-compose.production.yml up -d

After either path, the README says to open http://localhost:3000, register an account, and note that the first user becomes admin. If Ollama is running on the host and listening on 0.0.0.0, models should appear without further setup.

Ports and provider URLs are configurable through a .env file placed next to docker-compose.production.yml. The README shows these keys:

CLARAVERSE_PORT=8080
OLLAMA_BASE_URL=http://host.docker.internal:11434
LMSTUDIO_BASE_URL=http://host.docker.internal:1234

A single-container alternative exists for people who do not want the sidecars:

docker run -d \
  --name claraverse \
  -p 3000:3000 \
  -v claraverse-data:/app/data \
  -v claraverse-uploads:/app/uploads \
  --add-host=host.docker.internal:host-gateway \
  ghcr.io/claraverse-space/claraverse:latest

The README is explicit about the trade-off: this mode boots fine, but the Knowledge tab and the search_knowledge tool need the sidecars and will surface "embeddings service unreachable" without them. The most common first-run failure is Ollama binding to 127.0.0.1, which containers cannot reach. The README's fix is to set OLLAMA_HOST=0.0.0.0, and it shows the systemd route of editing the ollama unit and adding an Environment line before restarting the service.

Where ClaraVerse gets expensive: sidecars, ports and the single-container gap

The honest limitation is infrastructure surface. A full deployment runs MySQL, MongoDB, Redis, SearXNG, Qdrant and an embeddings service alongside the application container. That is six stateful services to back up, monitor and upgrade, each with its own volume. The compose file even fixes memory limits and health checks per service, which tells you the maintainers expect resource contention on small hosts. The README's stated minimum is 4 GB RAM, with 8 GB recommended, and that figure predates whatever the embeddings sidecar and Qdrant consume on real documents.

Single-container mode is the wrong tool for anyone who wants knowledge bases. It is a reasonable fit for chat against a remote OpenAI-compatible API, and a poor fit for RAG, because the README says the embeddings service is unreachable without the sidecars. Choosing the lightweight path and then expecting search_knowledge to work is a configuration mistake the documentation warns about but cannot prevent.

Provider discovery has a two-minute window by design. If you start Ollama after ClaraVerse, models will not appear instantly, and if a provider flaps, the platform disables and re-imports on the next poll. That is acceptable for a workstation and awkward for a shared instance where users expect models to be present the moment they open the app.

Finally, the licence. The README badge and the Dockerfile label both say AGPL-3.0, while the repository metadata reports NOASSERTION. For anyone embedding ClaraVerse in a network service, that discrepancy is worth resolving against the LICENSE file before architectural decisions are made. This is a description of the licence identifiers present in the repository, not legal advice.

ClaraVerse versus Open WebUI: bundled agents and memory against a narrower chat UI

The README itself links a "vs Open WebUI" section, and it is the comparison the project invites. Open WebUI is the better-known self-hosted chat front end, and its centre of gravity is the conversation interface plus model and document handling. ClaraVerse bundles more: Crew agent teams with a human review step on every card, a visual workflow builder, Telegram integration, a terminal coding agent, and a memory system that the README describes as model-driven, with the assistant calling search_memory and add_memory as tools.

The architectural difference matters more than the feature list. A lean chat UI can run as one container against one database. ClaraVerse's feature set is why MySQL, MongoDB, Redis, Qdrant and an embeddings sidecar are in the production compose file. If you only want a polished chat window pointed at Ollama, the extra services are overhead with no payoff. If you want agents that hand work back for review, or memory that pins hard constraints and decays the rest, that is the reason to accept the stack.

The terminal story is a second axis. ClaraVerse ships clara-agent in the same repository, installed with claraverse agent install, which builds the agent and puts claracli on the PATH. The README notes it uses the same model and account as the web app, so a coding session in the terminal and a chat in the browser share context rather than living in separate tools.

Maintenance, upgrades and what the release history shows

The repository is not archived, and the last push was on 2026-08-03, which is recent enough that the project is not dormant. The release list is short and clustered: v0.3.1, v0.3.0 and v0.2.0 all landed on 2026-05-31, with v0.3.1 described as "One-line install RAG-ready" and v0.3.0 as "Knowledge bases everywhere". That clustering suggests release bursts rather than a steady cadence, so anyone tracking upstream should expect quiet periods between drops and read CHANGELOG.md rather than assuming continuous change.

Upgrade cost is dominated by the databases. The compose file mounts ./backend/migrations into MySQL's init directory, which runs on first initialization of the volume, not on every start. Schema changes therefore need a migration path you understand before you pull a new image, and the README's documented fresh start is destructive:

docker compose -f docker-compose.production.yml down -v && docker compose -f docker-compose.production.yml up -d

The -v flag removes volumes, which the README labels as removing all data. Log inspection and a plain restart are the non-destructive options it lists. On the licence side, the AGPL-3.0 identifier appears in both the README badge and the Dockerfile label, so a team planning to offer ClaraVerse as a hosted service should read the LICENSE file and the CODE_OF_CONDUCT.md and CONTRIBUTING.md files in the repository root before deciding how it fits into their distribution model. Nothing here is legal advice; the point is that the licence question is answerable from files in the repo, and it should be answered before deployment, not after.

Editorial conclusion

Adopt ClaraVerse if you already run Ollama or LM Studio, want agent teams and memory on your own hardware, and can operate MySQL, MongoDB, Redis, Qdrant and SearXNG as separate containers. Skip it if you want a single lightweight container with no database sidecars, or if you need a permissive licence for a closed product, because the README ships AGPL-3.0. Before committing, verify two things on your own machine: that Ollama is reachable at host.docker.internal:11434 with OLLAMA_HOST=0.0.0.0 set, and that the embeddings sidecar answers, since single-container mode surfaces "embeddings service unreachable" and disables the Knowledge tab.

Frequently asked questions

Official sources

1. claraverse-space/ClaraVerse on GitHub
2. Issues
3. Project website
4. README
5. Releases