LLeMbas — developer documentation
A self-hosted web interface for OpenAI-compatible endpoints. Server-rendered FastAPI + Jinja + htmx, SQLite, no JavaScript build step, themed after Middle-earth. Point it at whatever you run — llama.cpp, LM Studio, vLLM, Ollama, OpenRouter, OpenAI — and it works the same.
The repository holds the code, the
README and the CHANGELOG. The documentation lives here, so that a clone
carries software and this carries the reasoning behind it.
Start here
Working notes — the one document to read before changing anything. What the project is, the six hard rules it is built around, the layout, and a long catalogue of things that will bite you: the bugs that shipped looking correct, why each happened, and what stops it happening again. If you read one page, read that one.
Roadmap — what is built, what is deliberately not, and the decisions behind each with the reasoning kept rather than summarised.
By topic
Each of these was split out of the working notes because it is only wanted while you are in that corner of the code.
| Page | What it covers |
|---|---|
| Agent chats | The four modes and where each is enforced, how a round is authorised, how "always allow this" derives a pattern, SSH, background jobs, the file tools and the patch matcher, the project listing, and the terminal panel. |
| Schedules and reports | Claiming a schedule before firing it, the pure recurrence rule, the wake lock, task chats, the Reports feed, and the four scheduling tools a model calls. |
| Permissions and sharing | The union rule shown rather than thrown away, where read and write are split and why not everywhere, quotas as the union rule applied to numbers, and the three deletes that have to forget a share. |
| Search and extraction | Extraction limits as a snapshot, why reciprocal rank fusion and not a weight, how a record scores as its best chunk, and why vectors from two models never meet. |
| Image generation | The ComfyUI workflow with holes in it, what substitution walks, the review-and-retry loop, and how a failure reports itself. |
| Subagents | The hidden chat a helper runs in, why unattended is a column and not a kind, what it may run, and where the three bounds are counted. |
| Branding | The branding snapshot and why it is a Jinja global, how a custom theme inherits through data-base, and why /branding.css is a route. |
| Release checklist | The manual pass before a release — everything needing a real endpoint, a real machine, real hardware or a real pair of eyes. |
| Image generation instructions | The prompt guidance shipped for drawing. |
Two things worth knowing before you start
Nothing executes on the machine LLeMbas runs on. Agent chats run their commands on a host reached over SSH. A local sandbox was designed in detail and dropped; the Roadmap records why. The security of an agent chat is the security of the host behind its profile.
One worker. The generation registry, the terminal sessions and the schedule ticker are all in-process. Two workers means two tickers and every schedule firing twice.
Releases
Signed annotated tags, vX.Y.Z, no suffixes. The tag message is the release
notes — /admin/updates reads it with git for-each-ref rather than a forge
API, so what goes into the tag is what an administrator sees on the update page.
The Releases page carries the same text, and is always made from an existing
tag: a Release created for a tag that does not exist writes a lightweight one
with no message, and the update page then shows a version with blank notes.