DeepCellar

A minimalist, self-hosted AI hub for companies, built on your own
Ollama instance — local and cloud models, thinking
support, and real authentication, all wrapped in a dark purple UI.
DeepCellar is becoming a RAG chatbot over company documents, tool-equipped
agents, and everyday AI utilities: one command, one SQLite file, fully
offline.

Features

Chat

• Streams replies from Ollama's native /api/chat endpoint through a
  FastAPI proxy (NDJSON)
• Persistent chat sessions in a sidebar: auto-created on the first
  message, full history on click, delete — the server tees the stream
  and stores each turn in SQLite, and a reload brings you back to your
  last chat
• Conversational memory: the full message history is resent each turn
  (Ollama's chat API is stateless by design)
• Thinking models (detected natively via capabilities) get think: true
  automatically, with their reasoning shown in a collapsible block
• Assistant replies rendered as markdown (bold, lists, code blocks, tables)
  via vendored marked + DOMPurify — works fully offline
• Unified composer: message box, custom model dropdown, and send button in
  one smooth container

Models

• Model picker groups Cloud vs Local models and only lists chat-capable
  ones (native "completion" capability — embedding-only models are
  excluded)
• Models dashboard with per-model details: parameters, quantization,
  family, context length, size, host
• Thinking models are highlighted; non-chatable models get a distinct
  "not chatable" badge
• Detects when Ollama isn't running and tells you how to start it

Accounts & security

• Real local accounts: username + password signup/login, argon2 password
  hashing, SQLite storage
• JWT sessions in an HttpOnly, SameSite=Lax cookie
• Per-install secret key generated on first run — nothing sensitive is
  ever committed to the repo
• Only static/ is served publicly; source code, the database, and the
  secret key are never exposed over HTTP

Requirements

• Python 3.11+
• Ollama installed and running (ollama serve,
  or the desktop app)

Quick start

git clone https://github.com/alouiadel/DeepCellar.git
cd DeepCellar

python3 -m venv .venv
.venv/bin/pip install -r requirements.txt

# make sure Ollama is running, then:
.venv/bin/python run_app.py

Open http://127.0.0.1:8000, create an account, and start chatting.

Configuration

Project structure

DeepCellar/
├── run_app.py          Entry point (uvicorn launcher)
├── app/
│   ├── main.py         FastAPI app: auth API, model list, streaming chat proxy
│   ├── auth.py         argon2 hashing, JWT sessions, per-install secret key
│   ├── db.py           SQLite tables (users, chats, messages)
│   └── ollama_client.py Ollama API client (model listing, chat streaming)
├── tests/              pytest API suite (isolated SQLite per test)
├── .github/workflows/  CI: ruff + prettier + pytest on push and PRs
├── pages/
│   ├── index.html      Login / signup page
│   ├── app.html        Chat window with session sidebar (protected)
│   └── models.html     Models dashboard (protected)
├── requirements.txt
├── requirements-dev.txt Dev-only tools (pytest, httpx2)
├── next.md             Roadmap: milestone map (chat → RAG → company → agents)
├── static/
│   ├── style.css       Theme (purple / dark / gray)
│   ├── script.js       Login + signup logic
│   ├── app.js          Chat logic (streaming, memory, markdown)
│   ├── models.js       Dashboard logic
│   ├── vendor/         Pinned marked + DOMPurify (offline-friendly)
│   └── favicon.*       DeepCellar brand icon
└── docs/               Screenshots

Files created at runtime (gitignored): deepcellar.db, .secret_key.

How it works

• Auth — passwords are hashed with argon2 (pwdlib) and stored in a
  local SQLite database. Logging in issues a signed JWT stored in an
  HttpOnly cookie; protected pages and API routes verify it.
• Model detection — everything comes from Ollama's /api/tags: cloud
  models carry a remote_host, thinking and chat capability come from the
  native capabilities array (with a /api/show fallback for older
  Ollama versions).
• Chat memory — Ollama's /api/chat is stateless, so the browser
  keeps the conversation and resends it with every message. Every chat
  persists from its first message: the streaming proxy tees each turn
  into SQLite. Switching models starts a fresh chat.

Roadmap

See next.md for the milestone map.

• Persistent chat sessions (done — sidebar, stream persistence, tests)
• RAG: document ingestion, embeddings, cited answers (next)
• Company layer: admin roles, shared knowledge bases, branding
• Agents (MCP) and a toolbox of everyday AI utilities

Contributing

See CONTRIBUTING.md for design principles, the roadmap,
and how to submit changes.

Development

.venv/bin/pip install -r requirements-dev.txt
.venv/bin/python -m pytest tests/ -q  # API tests
ruff check --fix . && ruff format .   # Python lint + format
prettier --write .                    # HTML / CSS / JS

CI runs ruff, prettier and pytest on every push and pull request.

License

MIT — see LICENSE.