Soliplex
An AI-powered Retrieval-Augmented Generation (RAG) system with a modern web interface.
Overview
Soliplex is a self-hosted, full-stack RAG/AI system: a FastAPI backend
(a thin configuration and authentication layer around
pydantic-ai), a hardened
Flutter client, and a terminal UI.
See the Overview for what Soliplex is, when (and when not)
to use it, how it compares to alternatives, and the full feature and
architecture breakdown.
Quickstart
The fastest way to stand up and run your own Soliplex is to let a
skills-compatible AI agent (e.g. Claude Code, Codex, Copilot)
do it for you. Soliplex publishes two Agent Skills
that teach your agent how to deploy and operate it -- no need to clone or hack
on this repository:
-
soliplex-template scaffolds a complete, runnable Docker Compose stack
(nginx, the Soliplex backend, the Flutter frontend, an ingester, Postgres,
and a TUI). It prompts for the parameters you care about -- project name,
host ports, your Ollama URL, models, version pins, auth mode -- and writes
out the full project. Published from
soliplex/soliplex-template.
-
soliplex-docs is the full Soliplex documentation, so your agent can
answer questions about installing, configuring, and operating your
deployment straight from the official docs. Published from this repository.
Install the skills
Each skill is a tarball that unpacks into a soliplex-template/ or
soliplex-docs/ directory. Install them by unpacking both into whichever
directory your agent scans for skills. The directory differs per agent:
Point SKILLS_DIR at the row that matches your agent (the examples below use
the Claude Code per-user location) and unpack both skills into it:
SKILLS_DIR=~/.claude/skills
mkdir -p "$SKILLS_DIR"
# Deployment scaffolder
curl -fsSL \
https://github.com/soliplex/soliplex-template/releases/download/template-skill-latest/soliplex-template-skill.tar.gz \
| tar xz -C "$SKILLS_DIR"
# Documentation
curl -fsSL \
https://github.com/soliplex/soliplex/releases/download/docs-latest/soliplex-docs-skill.tar.gz \
| tar xz -C "$SKILLS_DIR"
For example, to install into a Codex project instead:
SKILLS_DIR=.agents/skills
The table covers the common cases; consult your agent's documentation (linked
above) for the authoritative list of locations it scans. Both skills bundle a
scripts/skill_versions.py helper to list published builds and upgrade in
place; see docs/docs-skill.md for details.
Use the skills
Start your agent in the directory where you want the deployment to live and
ask it to scaffold a stack -- for example, "Use the soliplex-template skill
to set up a new Soliplex deployment." The skill walks you through the
parameters and generates the project; then docker compose up brings it
online (the frontend defaults to http://localhost:9000).
Tell your agent to answer configuration or operations questions about Soliplex
using the soliplex-docs skill -- for example, "Use the soliplex-docs skill
to answer questions about configuring or operating a Soliplex installation."
and then "What is a Soliplex installation?"
The remainder of this README covers running Soliplex from a source checkout
and developing on the backend itself. If you only want to use Soliplex,
the two skills above are all you need.
Running from source
The skills-based Quickstart above is the recommended path for
most users. To run Soliplex from a checkout of this repository instead, see:
- Prerequisites -- system requirements and an
installation checklist.
- Server Setup -- install the backend, run the example
installations, and start the server.
soliplex-cli reference -- every subcommand and option
(config audits, serving, admin users, model pulls, ...).- RAG Database -- create and populate the LanceDB database the
examples expect.
- Client Setup -- run the Flutter web client.
- Docker Deployment -- extend the published container images.
Documentation
The full documentation set lives in docs/ and is published as a
Zensical site:
Tip: the same documentation is also available as the soliplex-docs
Agent Skill, so a skills-compatible agent can answer questions straight from
it -- see the Quickstart above.
Configuration
Soliplex is configured by a tree of YAML files rooted at an
installation.yaml; sample configurations live in the
example/ directory. See the configuration docs:
- Filesystem Layout,
Installation,
Meta
- Rooms,
Agents,
Completions
- RAG,
Quizzes,
AI Skills,
AG-UI Features
- Secrets,
Environment,
OIDC Authentication
- Logfire,
Console logging,
SQLAlchemy DBURIs
Development
Contributor guidance -- setup, build and test commands, code style, the
configuration system, and how to add tools, rooms, and API endpoints -- lives
in DEVELOPMENT.md. AGENTS.md and
CLAUDE.md are condensed, agent-facing versions of the same
guidance.
Related Repositories
License
MIT License - Copyright (c) 2025 Enfold Systems, Inc.
