Jaroslav Beneš
9ddc0a2103
Nothing in LLeMbas ever happened on its own. Every reply was downstream of
somebody pressing Send, and the one exception -- jobs.wake, waking a chat when a
background job finishes -- was downstream of a command they had run. PLAN.md
never listed scheduling as unbuilt because services/chat.py:618 had recorded it
as a decision: "a scheduler is a whole new concern for a single-worker
application". This is that concern, taken on deliberately, plus the two places
its output goes.
Reports first, because it is useful with no scheduling at all. A report is not a
Chat with one Message in it: it has no turns and no reply, it is read top to
bottom, and it must be writable with no chat behind it -- being the fallback for
a run whose own chat has gone. As a Chat it would need a sidebar row per daily
report, a title that regenerates itself, a composer to suppress and a bubble with
a rewind button around something that is not a turn. The section's character is
enforced by absence: nothing under reports/ includes the composer or renders
chat/_message.html, so there is no sse-connect anywhere and nothing on those
pages *can* start a generation. The test reads that off the OpenAPI schema, not
by walking app.routes -- this FastAPI keeps an included router wrapped rather
than flattening it, so the walk finds nothing and the assertion passes for the
wrong reason.
rule.py is pure, total, and was finished before anything called it. No session,
no wall clock, nothing that raises: validate clamps what it recognises, drops
what it does not, and answers {} for prose -- at which point the caller shows the
manual form. It had to be that way because the compile step's output is model
output that becomes a *timer*, which is the sharpest case of hard rule 6 here.
The invariant, pinned: anything validate accepts has a computable next
occurrence. A schedule that can never fire looks exactly like a working one on
every screen it appears on.
Wall-clock and elapsed time are kept apart because they mean different things.
at.times are wall-clock in the owner's zone, so 15:00 stays 15:00 across a
daylight-saving change -- that is what "every Monday at 3PM" means. every is
elapsed real time, so six hours stays six hours across a 23- or 25-hour day --
that is what a timer means. Conflating them gets one of the two wrong twice a
year. A time inside the spring-forward gap fires at the first minute that exists;
left to zoneinfo's own resolution it lands an hour away wearing a wall-clock time
that did not happen, and a daily 02:30 report vanishing once a year on a machine
nobody watches is the failure this file is arranged around.
The ticker claims and commits *before* it fires. The other order is a hot loop: a
firing that raises is retried every tick for ever against whatever it was that
failed, and the only symptom is load. Its blanket except is copied from the
terminal reaper for a sharper reason -- a ticker that dies on one bad row stops
every schedule on the instance and says nothing at all. No request fails, no
reply errors, no dot appears. The reports simply stop.
Three rules that look like bugs from outside: a firing arriving while the chat is
still answering queues rather than starting a second reply, and past max_queued
is skipped with the reason on the row; Run now does not advance next_fire_at, or
testing a schedule silently consumes the run it was testing; resuming recomputes
from now, or a schedule paused for a month fires the instant it comes back, once
per occurrence it missed. Catching up lives in the sweep and not in a startup
hook, because a suspended host and a long stall reproduce "its time passed while
nothing was running" with no restart to hang one on.
services/wake.py is the lock discipline extracted rather than copied. A finished
job and a due schedule are the same problem, and both depend on there being no
await between the running_for check and the writes; two lock dictionaries for one
invariant is how one of them drifts. jobs.wake is now a caller that supplies
wording, and _completion_text stayed exactly where it was because tool.background
quotes its opening sentence.
A scheduled run has no reader, so ask_user is withdrawn from resolve_tools rather
than merely discouraged in core.unattended -- a rule living only in a system
message is one a page the model just read can argue with, and a parked question
holds the reply for the whole approval_timeout with nobody to answer it. For the
same reason a task chat may not be an agent chat in v1: Manual, Edit and Plan all
stop to ask on RISK_EXECUTE, so the only two outcomes would be unattended
execution and a reply that stalls. That deserves its own pass.
Messages is bounded in the request and unbounded on disk. Only the latest chunk
is sent; everything else stays exactly where it was written. Nothing is folded
into text and nothing is deleted -- the visible conversation is identical either
way, so destroying the older rows would buy only disk, against being irreversible
and losing every attachment and tool call in the range, and it would contradict
the rule compaction already holds. should_compact refuses this kind for the
matching reason: two mechanisms narrowing one transcript is how a summary ends up
summarising a summary. The history route is the mirror of thread_tail and keeps
its four properties; the fifth is its own, that prepending moves the scroll
position, so app.js records scrollHeight before the swap and adds the difference
back after.
An empty Chat.kind meant "both sides of the switch" and had been read as "no
filter" since there were only two of them. The sidebar passes "" precisely when
agent chats are switched off -- so the moment a third kind existed, every task
chat and every Messages conversation appeared in somebody's ordinary chat list,
on exactly the instances whose owners would never think to look. KINDS stays the
two-sided fork, because set_sidebar_kind validates against it and a third entry
there makes the tree filterable to a side with no button to leave it; ALL_KINDS
is what a row may be. Both narrowings are pinned, because they are two
implementations of one rule and only one of them is SQL.
Per-user timezone had to exist for any of this: harness.py:179 was telling every
reader the *server's* idea of the date, which is survivable while the answer is
prose and stops being survivable the moment somebody says "every Monday at 3" and
something has to work out when that is.
Three things were caught by a test being wrong rather than by the code being
wrong. The task-chat "no composer" assertions were passing against a page
rendering its no-models-configured branch. A permission test asserted the same
thing twice because the administrator bypasses every permission. And every
Messages test passed with default_model never called, because none of them
configured a model -- so the pair it returns was being assigned straight to
model_id, and SQLite refuses a tuple in a String column. The fixtures now say why
they exist.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
A self-hosted web UI for your language models, written in Python.
Talks to anything that speaks the OpenAI API. Themed after Middle-earth.
Lembas is the Elvish waybread — one bite sustains a traveller for a day's march. The capitals hide what it runs on: LLeMbas.
Why this exists
Most self-hosted LLM front-ends are large JavaScript applications with a Python
API bolted underneath. LLeMbas is the other way round: server-rendered
Python, with htmx and a little Alpine for interactivity. There is no
package.json, no bundler, no build step, and nothing is fetched from a CDN at
runtime. Clone it, pip install -e ., run it.
Features
Working now
- Chats — streaming replies, Markdown with server-side syntax highlighting, copy and regenerate, automatic chat titles. Chats are created when you send the first message, so an abandoned one never clutters the sidebar
- System prompts — instance-wide, per-model and per-chat, with the most specific winning outright
- Reasoning display — thinking streams into its own collapsible block (closed by default), labelled with how long it took, and is never replayed as context
- Live Markdown — formatting appears as the model writes, not at the end
- Stop and rewind — cut a reply short and keep what arrived, or edit an earlier message and run the conversation on from there
- Replies keep running in the background — navigate away, open another chat, close the tab; a green dot and a notification tell you when it lands
- Attachments — drag, paste or pick images, PDFs and text files. Images are downscaled and sent to vision models; PDF and text content is extracted and put in the prompt
@to name something — a document from your library, or in an agent chat a file in the project directory. The reference stays in the sentence you are writing and the contents come with it/for commands —/compact,/usage,/mode plan,/effort high,/model,/title,/terminal,/theme. The list appears as you type and filters as you go;/helpshows all of them with the keyboard shortcuts beside them. A message that merely starts with a slash is still sent as written, and both@and a recognised command are marked in the box as you type so you can see what will happen before you press Enter- Reasoning effort —
/effort low,mediumorhighon a model marked as reasoning, with a per-model default in the admin area. Sent two ways at once, because there is no single field every endpoint reads - Folders — arbitrarily nested, delete a folder without losing the chats inside it
- Web search — offered to the model as a tool it calls when a question needs it. DuckDuckGo out of the box (no account, no key), or point it at your own SearXNG, or Firecrawl. The sources stay in the transcript
- Your own tools — describe an HTTP call in the admin area (a schema, a URL template, a secret) and a model can make it. Or add an MCP server by URL and its tools appear beside the built-in ones. Both restrictable to groups, and neither can be pointed at your own network unless you say so
- Agent chats — start a chat as an Agent instead, pointed at one of your own SSH connections and a directory on it, and a model can read files, write files and run commands there. Nothing ever runs on the machine LLeMbas itself is on. What it may do without asking is a mode you set and can change mid-conversation: Manual shows you everything first, Edit writes freely but asks before commands, Auto asks about nothing, and Plan reads freely, changes nothing, and finishes by proposing steps you can carry out with one button. Adding a host shows you its fingerprint before anything is sent to it
- A terminal beside the chat — the same connection, a real shell, opened and closed like any panel. It survives closing the panel and reloading the page, so a build keeps running; the model cannot see it, and a button hands it the output you choose
- It can ask you things — a model that needs a decision can stop and put a few questions on one card, with answers to pick from and a box to write your own. In any chat, not only an agent one
- Speech in and out — dictate a message and have replies read aloud, against any OpenAI-compatible audio endpoint (whisper.cpp, Speaches, Kokoro…). Each person picks their own voice
- A library — four places a model can reach for. Knowledge: documents, images and web pages you collect, grouped into named bases so a chat can be pointed at just the right one, searched before the web. Notes: longer things it writes down and finds again later. Memory: short facts about you, in front of it on every turn. Skills: saved procedures it can follow, and write. All of it visible and editable by you, and shareable with a group or a person, read-only
- Installable — add it to a phone home screen or a desktop launcher and it runs in its own window
- OpenAI connections — point at OpenAI, LM Studio, vLLM, llama.cpp, llama-swap, Ollama or OpenRouter; models are discovered and cached
- Model settings — searchable, filterable list with a page per model: ordering, pinned models, an instance default and a per-user default, custom names, descriptions and images. Scales to hundreds of models
- Users, groups & permissions — per-group grants that union rather than override, and model access restricted to chosen groups
- Accounts — first account becomes the administrator, argon2 password hashing, revocable server-side sessions, self-service password change, admin-managed accounts
- Admin settings — open or close registration from the UI, stored in the database and effective immediately
- Two themes — Moria (dark) and Shire (light), switchable per user
Planned
Image generation · OCR for scanned PDFs · semantic search in the library.
See PLAN.md for what is built, what is not, and why.
Quick start
git clone https://git.houmeres.sk/Houmeres/LLeMbas.git
cd LLeMbas
python -m venv .venv && . .venv/bin/activate
pip install -e ".[dev,search,ssh]" # search: DuckDuckGo. ssh: agent chats.
# Drop either if you do not want it
cp .env.example .env
lembas secret-key # paste the result into LEMBAS_SECRET_KEY
lembas serve # http://127.0.0.1:8080
Open the address and create the first account — it becomes the administrator.
Then go to Admin → Connections and add an endpoint. For a local runner that
is usually http://localhost:1234/v1 with no API key. Press Test & refresh
and its models appear in the chat model picker.
The vendored browser libraries (htmx, Alpine) are committed, so no network access is needed to run. To re-fetch or bump them:
python scripts/fetch_vendor.py --update.
Web search
Admin → Web search. DuckDuckGo needs nothing beyond the search extra
above. SearXNG needs its JSON format enabled — add - json under
search.formats in its settings.yml, or every search fails. Firecrawl needs
an API key.
Search is offered to the model as a tool, so it decides when a question needs looking up. It is only offered to models marked tools under Admin → Models: an endpoint without tool support rejects the whole request rather than ignoring the extra field, so the flag is a real switch and not a hint.
Audio
Admin → Audio. Two endpoints, because they are usually two servers:
| Speaks | Example | |
|---|---|---|
| Dictation | POST /v1/audio/transcriptions |
whisper.cpp's whisper-server, Speaches, faster-whisper-server |
| Read aloud | POST /v1/audio/speech |
Kokoro-FastAPI, OpenAI |
If the speech endpoint also answers GET /v1/audio/voices the voice list is
read from it, and each person can pick their own under Settings → Audio.
Recorded audio is passed straight through and never written to disk.
The microphone needs HTTPS or localhost. Browsers do not grant it over plain HTTP, so a LAN install without TLS will not offer dictation.
Agent chats
Admin → Agents to turn the feature on, then Connections in the sidebar to add a machine. Three things have to line up before an agent chat can start: the feature enabled, the Run commands permission, and a model flagged Agent execution. All three are off by default, on purpose.
Nothing an agent does runs on the machine LLeMbas is on. Commands go to a host you name over SSH, which means the containment is that host — a container built for the job is a very different thing from a key to a server you care about, and LLeMbas cannot tell them apart. A throwaway container is the intended shape:
docker run -d --name agent-box -p 127.0.0.1:2222:22 <an sshd image>
Adding a connection does not connect to it. Check shows you the host's fingerprint with nothing sent — not your username, not your key — and only accepting pins it. If that host later answers with a different key, it is refused rather than quietly trusted.
Then start a chat with the Agent toggle, pick the connection, browse to a directory, and choose a mode — all of it under the message box, before you send anything. The connection and the directory are fixed once the chat exists; the mode changes at any time and stays where you chose it:
| Reads | Writes files | Runs commands | |
|---|---|---|---|
| Manual | asks | asks | asks |
| Edit | free | free | asks |
| Auto | free | free | free |
| Plan | free | asks | asks |
The mode is enforced in the reply loop, not written into the prompt: everything a model reads — a web page, a README, the last command's output — is untrusted, and a rule that lives only in a system message is one a poisoned file can argue with. In Auto, nothing stands between that and a command running.
Plan finishes by proposing steps, with a button that carries them out — which switches to Edit, never Auto, because the plan was written under a mode where every command still asked.
What the model knows about the directory
An agent chat starts by listing the project directory, so a reply does not spend
its first rounds finding out what is there. It is one read-only command —
git ls-files in a repository, so .gitignore is honoured for free, otherwise
find with the usual noise pruned — and it is cached and shared by every chat
pointed at the same place.
What reaches the model is budgeted rather than dumped: a directory that will not
fit is shown as node_modules/ (4,102 files) and the model is told to open it
itself if it needs to. Admin → Agents sets the budget, and 0 keeps the
listing for the @ picker while putting none of it in the prompt.
Listing a directory and browsing one are things you asked for, not things a model chose, so neither goes through the modes above. Worth knowing if you read Manual as "nothing happens without me": it means nothing the model does.
The terminal
An agent chat has a Terminal button in its header, which opens a real shell on that chat's connection, in its directory, beside the conversation. It needs the Open a terminal permission, which is off by default.
The modes above do not apply to it. They exist because a model reads pages, files and command output it did not write; you hold the credential and could open the same shell with an ssh client, so nothing you type is queued for your own approval. The model cannot see the panel either — three buttons in its header decide what it sees: Copy takes the last command and its output to the clipboard, Send puts the same into the message box, and Auto collects every command you run into your next message. Nothing is ever sent on its own; the box is where you read it first.
Knowing what "the last command" means takes a little help from the shell. LLeMbas gives bash and zsh the same invisible markers VS Code and WezTerm use, written into a temporary file the shell deletes itself, so it can tell one command's output from the next and record the exit status and the directory. Your own dotfiles are loaded first and nothing of yours is skipped. Any other shell starts exactly as it would have; the two buttons then copy the last of the screen as it appeared, say so, and Auto is switched off rather than guessing.
Drag the panel's left edge to make it wider — a terminal narrower than eighty columns re-wraps everything a program prints — and the width follows you to another browser.
The shell is not tied to the panel. Close it and a build carries on; come back, or reload, and you reattach with the scrollback. Two tabs share one shell, and the smaller window decides the size. It ends when nobody has watched it and nothing has been typed for a while, when the chat is deleted, when the connection is disabled or deleted, or when LLeMbas restarts — a deploy cuts off whatever was running, and the panel says so rather than quietly opening a fresh shell that has lost your working directory.
Nothing typed here is in the transcript and nothing is logged but the opening and the closing. If you are running this over plain http, note that the session cookie is not marked
secureso a LAN install works at all — with a terminal switched on, that is worth a certificate.
The library
Sidebar → Library, and Settings → Memory. Nothing is on by default for a
model: give it the tools it should have under Admin → Models, where
tools decides whether a tool list may be sent at all and the built-in tools are
chosen one by one.
Knowledge is organised into bases — one per subject, project or client. A chat with no base attached searches everything you have; tick some in the chat's settings panel and it searches only those. Sharing happens at the base: share it and everything in it comes too, read-only.
Search is SQLite's FTS5 — keyword matching with BM25 ranking, no embedding service to run and nothing that stops working offline. It will not match a paraphrase, so a line of description on a document is worth writing.
Saving a link makes your server fetch a URL. Addresses on your own machine and network are refused unless an administrator opts in under Admin → Web search, because the address can come from a model and the server can reach things your browser cannot.
Installing as an app
Open it in a browser and use Install (Chromium) or Share → Add to Home Screen (iOS). This also needs HTTPS or localhost — service workers are unavailable over plain HTTP, and without one there is nothing to install.
There is no offline mode beyond a page saying so. Everything is rendered by your server, so a cached conversation would be a snapshot that silently went stale.
Configuration
All variables are prefixed LEMBAS_ and can live in .env. See
.env.example for the annotated list.
| Variable | Default | Purpose |
|---|---|---|
LEMBAS_SECRET_KEY |
generated | Signs sessions and encrypts stored API keys. Set this. A generated key changes every restart, signing everyone out and making stored API keys unreadable. |
LEMBAS_DATA_DIR |
./data |
SQLite database and uploads. |
LEMBAS_HOST / LEMBAS_PORT |
127.0.0.1 / 8080 |
Bind address. |
LEMBAS_ALLOW_SIGNUP |
true |
Whether new users may register themselves — the initial value only. Once set under Admin → General the stored setting wins. The first account is always an admin regardless. |
LEMBAS_DEFAULT_THEME |
moria |
moria (dark) or shire (light). |
LEMBAS_SESSION_TTL |
2592000 |
Session lifetime in seconds. |
LEMBAS_REQUEST_TIMEOUT |
300 |
Seconds to wait on an upstream model. |
Commands
lembas serve # run the server
lembas info # where data lives, what is configured
lembas secret-key # generate a value for LEMBAS_SECRET_KEY
lembas create-admin # create or promote an administrator
How it fits together
Browser ──form POST──▶ FastAPI ──▶ SQLite
▲ │
│ └──httpx──▶ any OpenAI-compatible endpoint
└──── server-sent events ◀───────────────┘ (streamed reply)
Sending a message stores the turn and returns two HTML fragments: the user's
bubble and an empty assistant bubble carrying an sse-connect. That opens a
server-sent event stream which appends tokens as they arrive, then replaces the
whole bubble with the finished, Markdown-rendered version. Rendering and
highlighting happen in Python, so the streamed and final views cannot disagree.
src/lembas/
api/ routes: auth, chats, folders, admin, pages
db/models/ SQLAlchemy schema
security/ password hashing, sessions
services/ llm client, chat orchestration, markdown, crypto, sse
web/ Jinja templates and static assets
assets/ SVG artwork masters
scripts/ artwork generator, vendored-JS fetcher
deploy/ systemd unit and nginx vhost for a real install
Development
pytest # test suite
ruff check . # lint
python scripts/build_artwork.py # regenerate the SVG artwork
python scripts/fetch_vendor.py # verify vendored JS against the lockfile
There is no Alembic. The schema is SQLite-only and synchronised at startup:
missing tables and missing columns are added automatically, so adding a field to
a model needs nothing but a restart. Renames, drops and retypes are still manual
— see CLAUDE.md.
Artwork
The logo, favicon and banner are original vector work, generated by
scripts/build_artwork.py so the mallorn leaf stays
identical across every size it appears at. The wordmark is
Source Serif 4 (SIL OFL 1.1)
converted to outlines — a README banner cannot load a webfont, and <text>
would render in whatever serif the reader happens to have.
Licence
A note on the theme
This is an independent hobby project, themed as an affectionate nod to J.R.R. Tolkien's world. It is not affiliated with, endorsed by, or connected to the Tolkien Estate, Middle-earth Enterprises, or any related rights holder. All artwork here is original.