Skip to content

TinyWebUI

TinyWebUI is a small, local-first chat workspace for any OpenAI-compatible model, with MCP tools. Chats, documents and tool output stay in one SQLite file on your machine. There is no hosted backend and no account to create, and npx tinywebui has nothing to build: the page ships prebuilt.

Bring an endpoint (OpenRouter, OpenAI, Groq, Ollama, vLLM, LM Studio, or anything else that speaks the OpenAI API), pick a model and a system prompt, and start working. It can grow from a personal workspace into a team deployment with sign-in, roles, per-user data and an admin panel, without changing anything else.

It comes with two TinySuite MCP servers already connected:

  • TinySearch searches, reads and reranks the web locally, then gives the model only the evidence worth putting in its context. It doesn’t need a search API key.
  • TinyContext is local long-term memory. It saves short memories in SQLite and recalls only what fits the token budget.
  • Durable conversations. Chats are stored in SQLite, with edit, retry, rewind, fork and full-text search. A running turn belongs to the server, not the browser tab, so you can reload or close the laptop and come back to it.
  • Folders with their own instructions. A folder’s instructions go into every turn of its chats, and a chat in a folder searches only that folder’s chats.
  • Steer a turn while it runs. Press Enter while the model is working and your message reaches it at the next safe point. Press Alt+Enter to hold the message as a follow-up instead.
  • Web search and memory included. TinySearch and TinyContext are connected from the first start. With sign-in on, each person gets their own memories and search history.
  • MCP over stdio, Streamable HTTP or SSE. Calls that can change something wait for your approval. Read-only calls in the same round run in parallel.
  • Attachments. Text and source files, PDFs, DOCX and images. HEIC and AVIF photos are converted automatically. The Files page lists everything you have attached, and files open in a viewer inside the app.
  • Your data, portable. Download your chats, folders and automations as one backup file, and import it here or on another TinyWebUI without overwriting anything.
  • Hybrid local search. BM25 combined with a small on-device embedding model searches documents and past chats. Nothing leaves the machine.
  • Long chats that stay affordable. Prompt prefixes are deterministic, so caches get reused. Large tool results are compacted once, and the full output stays one expand_context call away.
  • You can see what you spend. Every round shows its token use, cache reads and cache writes.
  • Automations. Cron-scheduled prompts that run in a chat of your choice. The model can create them too.
  • Private by default. The first account becomes the administrator. Everyone after that joins with a single-use invitation, or, if the admin turns it on, asks from the sign-in page and waits for approval. Teams can put SSO in front instead.
  • Roles you define. Beyond admin and user, create roles that grant exactly the features, models and personalisation you choose, and set what their chats run with (prompt, default model, sampling, limits, tool approval), for all models or one at a time. From Settings → People & roles or the config file.
  • Thinking levels per model. Let people pick how hard a model thinks, from off to high, and TinyWebUI sends it in whatever form the endpoint expects.
  • Managed from files. Every setting can come from version-controlled config, which hot-reloads, refuses typos and has a fingerprint you can check against a running instance. Keys stay out of it.
  • Integrations. MCP servers that offer a management page, like TinySearch and TinyContext, get one on the MCP page: each person sees and manages their own memories and search history.
  • Themes. Fall Fairy and Cyber Grid are included. A theme is one CSS file: import your own under Settings → Appearance, for yourself or, as an admin, for everyone.

Requires Node.js 22.13 or later. The bundled TinySearch and TinyContext servers also need uv, which fetches them (and Python 3.12 if necessary) the first time they start.

Terminal window
npx tinywebui

Open http://127.0.0.1:7777 and create the first account with an email address and a password of at least 10 characters. That account becomes the administrator and can invite others from Settings → People & roles, where requests for access from the sign-in page also wait for approval. Settings then opens on Models: add a connector (any OpenAI-compatible URL, with an API key if it needs one), then the models people can pick from it. Use --port and --host to change where it listens.

npx tinywebui keeps its config, keys, database and embedding models, and the data of the bundled TinySearch and TinyContext servers under mcp/, in one folder per user: ~/Library/Application Support/TinyWebUI on macOS, %LOCALAPPDATA%\TinyWebUI on Windows and ~/.local/share/tinywebui (or $XDG_DATA_HOME/tinywebui) on Linux. Run it in a folder that has its own tinywebui.config.json, or pass --config, to use that instead.

npx tinywebui@latest always runs the newest release. If you installed it with npm install -g tinywebui, update with npm install -g tinywebui@latest.

Or run from a clone of the repository (Node.js 22.18 or later, since the server runs its TypeScript directly):

Terminal window
npm install
npm start
Terminal window
docker run -d --name tinywebui -p 127.0.0.1:7777:7777 -v tinywebui-data:/data marcellm01/tinywebui

Open http://127.0.0.1:7777 and create the administrator in the browser. Docker covers the two images, connecting a model, Compose, updates and backups.

npm run dev runs the API on port 7777 and restarts it when server/, bin/ or shared/ change. Run npm run dev:web beside it for the page on http://127.0.0.1:5173, with hot reload, passing /api through to the server. npm start builds the page into dist/ first.

The images are on Docker Hub as marcellm01/tinywebui, for amd64 and arm64. An image is published only after the npm release of the same version passes its tests, so the two always match.

Tag What it is
latest Debian slim with hybrid search, with the embedding model baked in. It includes uv and the system libraries Chromium needs, so TinySearch and TinyContext run inside the container as they do with npx.
light A smaller Alpine image with keyword search only. It has no uv, so TinySearch, TinyContext and any other MCP servers connect over HTTP.

latest and light move with each release. Every release also keeps its own tags, v plus the npm version and the same with -light, so you can pin a deployment and upgrade it when you choose.

Terminal window
docker run -d --name tinywebui -p 127.0.0.1:7777:7777 -v tinywebui-data:/data marcellm01/tinywebui

Open http://127.0.0.1:7777 and create the first account, which becomes the administrator. Then add a model under Settings → Models (see Connect a model below).

  • -p 127.0.0.1:7777:7777 makes the page reachable from this machine only. To open it to your network, use -p 7777:7777 and put HTTPS in front of it. Access covers accounts, invitations and sign-in gateways.
  • -v tinywebui-data:/data keeps everything in a named volume: the database (accounts, password hashes, chats and files), the config, the keys and the bundled servers’ data. Without it, removing the container deletes all of that.
  • Accounts are always on in a container. local mode only listens on loopback, which nothing outside the container can reach, so TinyWebUI refuses to start with it there.

The image has a health check on /readyz, so docker ps shows healthy once the server is ready.

Add a connector under Settings → Models. A key you type there is saved in /data/tinywebui.secrets.json, on the volume. To keep keys out of the app, pass them as environment variables instead and refer to them from the connector:

Terminal window
docker run -d --name tinywebui -p 127.0.0.1:7777:7777 -v tinywebui-data:/data \
-e OPENROUTER_API_KEY=sk-or-... marcellm01/tinywebui
{ "id": "openrouter", "baseUrl": "https://openrouter.ai/api/v1", "apiKey": "${OPENROUTER_API_KEY}" }

A model server on the same machine (Ollama, LM Studio, llama.cpp, vLLM) isn’t at localhost: inside the container, localhost is the container itself. Use host.docker.internal instead, for example http://host.docker.internal:11434/v1 for Ollama. Docker Desktop on macOS and Windows provides that name. On Linux, add --add-host=host.docker.internal:host-gateway to the docker run command, and make the model server listen on more than loopback (for Ollama, OLLAMA_HOST=0.0.0.0).

The same setup as a compose.yaml. Put keys in a .env file beside it, which Compose reads by itself:

services:
tinywebui:
image: marcellm01/tinywebui:latest
ports:
- "127.0.0.1:7777:7777"
volumes:
- tinywebui-data:/data
environment:
OPENROUTER_API_KEY: ${OPENROUTER_API_KEY}
# extra_hosts: ["host.docker.internal:host-gateway"] # Linux, for a model server on the host
restart: unless-stopped
volumes:
tinywebui-data:
Terminal window
docker compose up -d

For a deployment kept as code (a config file in version control, a read-only container, a sign-in gateway in front), follow Deployment as code and the deployment guide on GitHub.

In latest, TinySearch and TinyContext start inside the container, the same way as with npx (see Pre-loaded: TinySearch and TinyContext). The first time they run, they download the servers, a Python for them, TinyContext’s embedding model and, on TinySearch’s first page read, Chromium. That is over 1 GB in total. It all goes into /data, so it happens once per volume, not once per container.

In light, run them in their own containers and connect over HTTP. TinyWebUI reads mcp.json from beside its config, which is /data/mcp.json in the container, or from the path in TINYWEBUI_MCP. Shared servers for many users has the mcp.json and the settings both servers need, so that each person keeps their own memories and search history. Until there is an mcp.json, the light image shows both servers as needs uv.

The CLI is in the image, so you can run it in the running container:

Terminal window
docker exec tinywebui node bin/tinywebui.ts doctor
docker exec tinywebui node bin/tinywebui.ts validate
docker exec tinywebui node bin/tinywebui.ts users password [email protected]

With Compose, use docker compose exec tinywebui in place of docker exec tinywebui. CLI lists every command.

To update, pull the new image and start a new container on the same volume:

Terminal window
docker pull marcellm01/tinywebui
docker rm -f tinywebui
docker run -d --name tinywebui -p 127.0.0.1:7777:7777 -v tinywebui-data:/data marcellm01/tinywebui

With Compose, docker compose pull && docker compose up -d does the same. A new version may upgrade the database when it starts, and an older version refuses to open it afterwards. Back up the volume first if you might want to go back:

Terminal window
docker stop tinywebui
docker run --rm -v tinywebui-data:/data -v "$PWD":/backup alpine tar czf /backup/tinywebui-data.tgz -C /data .
docker start tinywebui

Stopping the container first means the copy of the SQLite database is complete. To restore, extract the archive into an empty volume the same way. Each person can also download their own chats, folders and automations from Settings → Data (see Export and import).

Each image is signed with cosign, keyless, by the release workflow, and carries an SBOM and build provenance. To check one before you run it:

Terminal window
cosign verify marcellm01/tinywebui:latest \
--certificate-oidc-issuer https://token.actions.githubusercontent.com \
--certificate-identity-regexp '^https://github.com/TinySuiteHQ/TinyWebUI/\.github/workflows/publish\.yml@'

From a clone, docker compose build && docker compose up -d builds and runs the latest image. docker build -f Dockerfile.lexical -t tinywebui:light . builds the light one. Building the default image downloads the embedding model, so it needs internet access.

tinywebui.config.json describes the deployment: endpoints, connectors, models and policy. Start from example.tinywebui.config.json, or let the Settings panel write it. Every model belongs to a connector, an OpenAI-compatible endpoint:

{
"connectors": [
{
"id": "openrouter",
"label": "OpenRouter",
"baseUrl": "https://openrouter.ai/api/v1",
"apiKey": "${OPENROUTER_API_KEY}",
"models": [
{ "id": "flash", "label": "DeepSeek Flash", "model": "deepseek/deepseek-v4.1-flash" }
]
},
{
"id": "local",
"label": "Local models",
"baseUrl": "http://localhost:11434/v1",
"models": [{ "id": "llama", "label": "Llama 3.2", "model": "llama3.2" }]
}
],
"model": "flash",
"maxToolRounds": 12
}

A local runtime (Ollama, vLLM, LM Studio, llama.cpp) needs no apiKey. Older flat files with a top-level baseUrl, apiKey and models still work.

Settings → Models lists the connectors with their models. Each model has its own page for its prompt, sampling, tool budget, caching and request body, and blank fields inherit the defaults below, which are under Model defaults and Chat behaviour. Every change is written back to the config file. API keys are write-only: the browser learns that one is set and its last four characters, never the value, and leaving the field blank keeps the stored key.

Variable Effect
TINYWEBUI_CONFIG Path to the config file (.json, or .js/.mjs, see Deployment as code)
TINYWEBUI_MCP Path to mcp.json (default: next to the config file)
TINYWEBUI_DB Path to the SQLite database (default: tinywebui.db next to the config file)
TINYWEBUI_SECRETS Path to the secrets file (default: tinywebui.secrets.json next to the config file)
TINYWEBUI_API_KEY, OPENROUTER_API_KEY API key for models that name no connector; overrides the file
TINYWEBUI_BASE_URL, TINYWEBUI_MODEL Endpoint and model; override the file
TINYWEBUI_RETRIEVAL_MODE auto, lexical, dense or hybrid (see Search)
TINYWEBUI_MODELS_DIR Where embedding models are stored (default: models/ next to the config file)
TINYWEBUI_SESSION_SECRET Signs session cookies. Without it, one is generated and kept in the secrets file
TINYWEBUI_LOG_LEVEL debug, info (default), warn, error or silent. Audit events are always written
Setting Default What it does
maxToolRounds 12 Tool-use budget for one user message. A model response that calls one or more tools uses one round.
askUserTimeoutSeconds 120 How long an ask_user question waits before the run continues on the model’s own assumptions. 0 waits until the question is answered or the run is stopped. Automation runs never wait.
toolApproval "writes" Which tool calls need your approval: "writes", "all" or "off". See Tool approval.
cache true Prompt-cache shaping where the provider supports it.
cacheMode "auto" auto, implicit (stable prefix only), explicit (Anthropic cache_control), rolling (OpenRouter) or off.
cacheTtl "5m" Anthropic cache lifetime. "1h" costs more to write and suits chats with long pauses between turns.
reasoningReplay "auto" Which reasoning earlier assistant turns send back: reasoning_details (OpenRouter, Anthropic-style), reasoning_content on tool-call turns (direct DeepSeek), or omit. Set it for a gateway that auto doesn’t recognise.
compactThreshold 60000 History tokens (system prompt and tool definitions excluded) at which older tool results are compacted. 0 disables it.
keepTurns 2 How many recent user turns keep their tool results in full.
compactMinSaved 20000 The minimum number of characters a compaction must remove to be worth the cache miss it causes.
maxInlineChars 30000 Tool results larger than this are stubbed for later turns as soon as they arrive.
maxTurnChars 120000 Tool results larger than this are stubbed even within the turn that fetched them.
maxHistoryTokens 100000 Hard window. Beyond it, the oldest turns stop being sent to the model, but they stay in the transcript. 0 disables it.
llmCompaction true Before the window drops turns, the chat’s model summarises them. This costs one extra request each time the window moves. If the summary fails, the turns are simply dropped.
compactionMaxTokens 8192 Output limit for that summary. Reasoning models think within this limit, and a cut-off summary is rejected, so leave headroom.
expandCharBudget 8000 The most one expand_context call can return.
timezone "" IANA zone used for today’s date and for automations. Empty uses the server’s zone.
theme "" The theme everyone sees unless their role may pick their own: "" for the plain look, a built-in theme’s id, or a theme an admin imported for everyone.
extraBody {} Merged into every completion request. Gateway-specific options go here.
dbPath "" Database location. Empty means tinywebui.db next to the config file.

The model is told its full tool budget and today’s date. The last tool result of each round ends with a note of the rounds left, and that note becomes a warning for the final two rounds. When the budget is spent, TinyWebUI makes one last request with tools disabled, so the model answers from the evidence it already has.

The full schema, including the access and retrieval settings, is in docs/config.schema.json. You can also print it with tinywebui schema.

The models listed under the connectors are the catalogue: only they can be picked, and each can be named and tuned. With no models listed anywhere, any model id works.

{
"model": "quick",
"connectors": [
{
"id": "openrouter",
"baseUrl": "https://openrouter.ai/api/v1",
"apiKey": "${OPENROUTER_API_KEY}",
"models": [
{ "id": "quick", "label": "Quick", "description": "Everyday questions",
"model": "deepseek/deepseek-v4.1-flash", "temperature": 0.3 },
{ "id": "deep", "label": "Thorough", "model": "anthropic/claude-sonnet-5",
"systemPrompt": "You are a careful research assistant...", "maxToolRounds": 20,
"thinking": { "default": "high", "choices": ["low", "medium", "high"] } }
]
}
],
"access": { "roles": { "user": { "models": ["quick"] } } }
}
  • id is the name everything else uses: the model setting, role model lists and each person’s saved choice. model is the provider’s id; if it is left out, the id is sent.
  • People only see label and description. They can’t type in an id, and the provider id never reaches the browser.
  • Per-model overrides. An entry can set systemPrompt, temperature, maxTokens, maxToolRounds, cacheMode, cacheTtl, reasoningReplay and extraBody. These replace the global values for turns with that model, except extraBody, which is merged with the global one.
  • "enabled": false hides an entry but keeps its settings. Anyone who had picked it falls back to the default model. The default must be an enabled entry.
  • Connectors ({ "id", "label", "baseUrl", "apiKey", "models" }) let one catalogue mix endpoints. A flat top-level models list still works: there, an entry’s connector names its endpoint, and without one it uses the top-level baseUrl and apiKey.
  • "images": false stops people sending the model images, and "tools": false offers it no tools at all, for a small model that can’t see or can’t call tools. Both are on unless switched off. The older tags list still loads: a tagged entry without vision keeps images off.
  • thinking sets how hard the model thinks. See Thinking levels.
  • Editable from the UI by an admin (or the one person in local mode), in Settings, with the same checks as the file. Startup, reload and every save refuse a catalogue with an unknown key, a duplicate id, or a reference to an entry that doesn’t exist.

A model entry’s thinking says how hard it thinks before it answers, on one scale whatever the provider calls it:

{ "id": "deep", "model": "qwen3:14b", "thinking": { "default": "medium", "choices": ["off", "low", "medium", "high"] } }
  • Levels are provider, off, low, medium and high. provider sends nothing, so the provider’s own default applies; it is the default when default is left out.
  • choices with more than one level lets people switch from the model menu in the composer. One choice, or none, fixes the level.
  • send picks the request field that carries it. auto (the default) guesses from the endpoint:
send Sent as Used for
openrouter reasoning.effort, merged with any reasoning in extraBody OpenRouter
anthropic thinking with a token budget (2,048, 8,192 or 24,576), raising max_tokens to leave room for the answer api.anthropic.com
effort reasoning_effort (off becomes none) Everything else: OpenAI, Gemini, Ollama, vLLM, xAI
switch chat_template_kwargs.enable_thinking, on or off only Qwen-style chat templates on local servers

If an endpoint rejects the field, TinyWebUI drops it and the model answers at its own default instead of failing. The same settings are on each model’s page in Settings.

MCP servers are defined in mcp.json next to the config file, in the same shape that MCP desktop clients use.

Until an mcp.json exists, TinyWebUI starts these two TinySuite servers itself, launched by uv, with their management pages on. Their data, models and config live in TinyWebUI’s own folder, under mcp/. How they run depends on authMode:

  • With sign-in (multiuser, the default, or trusted-header), TinyWebUI starts both over HTTP on a free loopback port, in their own multi-user modes. TinyContext’s hosted tenancy keeps one memory store per person, and TinySearch’s trusted identity keeps one search history per person. Each person’s calls go out on a connection of their own, and every request carries a proxy token that TinyWebUI makes fresh on each start, so nothing else on the machine can pose as one of your users. TinyContext’s tenant secret is generated once and kept in tinywebui.secrets.json.
  • Without sign-in (local), there is one person, and both run over stdio.

uv picks up new releases of both servers by itself when they start. The version floors (TinySearch 0.6.8, TinyContext 0.5.4, the first releases with the proxy token) make sure nobody runs an older one. TinySearch still records no activity unless you turn that on too.

Server What the model gets
TinySearch Web search, clean Markdown from pages, and a browser for pages that need clicking. It runs locally and needs no search API key.
TinyContext Memory across chats: it saves short memories and recalls the relevant ones within a token budget. Stored locally in SQLite.

The first start takes a little longer while uv fetches the packages. TinyContext also downloads its embedding model once.

Without uv, TinyWebUI still starts and everything else works. The two servers are switched off, and it tells you why. On the command line, startup ends with tinycontext, tinysearch off until uv is installed, and npx tinywebui doctor reports both as failed for the same reason. In the app, both show needs uv in the tools menu and on the MCP page.

Install uv and restart TinyWebUI; no other setup is needed. The restart matters because the uv installer adds itself to your PATH only for programs started after it.

Saving the MCP page’s config writes these servers to mcp.json. After that the file is in charge: edit it to change them, or remove them to leave them out. An empty { "mcpServers": {} } means no servers at all.

The repository’s example.mcp.json has the two TinySuite servers plus a disabled HTTP example. Copy it to start, then add servers like these:

Terminal window
cp example.mcp.json mcp.json
{
"mcpServers": {
"files": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-filesystem", "."]
},
"research": {
"url": "http://127.0.0.1:8000/mcp",
"headers": { "Authorization": "Bearer ..." }
}
}
}
  • Stdio servers take command, args, env and cwd.
  • Remote servers take url, optional headers, and "transport": "sse" for SSE. The default transport is Streamable HTTP.
  • "disabled": true keeps a server defined but disconnected.

The MCP page, in the sidebar, validates and saves mcp.json, then reconnects without a restart. You can switch off single tools without disconnecting their server. The model sees tools under stable server__tool names.

A server that isn’t up yet doesn’t need a restart. TinyWebUI keeps trying a url server it couldn’t reach, after 2 seconds and then twice as long each time, up to once a minute, and adds its tools as soon as it answers. The MCP page shows each such server’s error, how many attempts have failed and when the next one is, with a Retry now button. A stdio or serve server is one TinyWebUI starts itself, so it is retried only from that button.

A tool call that can change something waits for you. It appears in the transcript with its arguments and three choices: allow, always allow this tool and deny.

  • A tool counts as read-only only when its server marks it with the MCP readOnlyHint annotation. Any tool without that mark is treated as one that can write.
  • toolApproval sets the policy: "writes" (default) asks before any call that isn’t read-only, "all" asks before every call and "off" never asks. The MCP page can override it for a single tool (confirmTools / autoApproveTools).
  • TinyWebUI’s built-in tools never ask, except manage_mcp, which asks before every change, even when toolApproval is "off".
  • Scheduled automation runs have no one to ask, so they refuse a call that would need approval and report it.

Calls from one round that are marked both readOnlyHint and idempotentHint run in parallel. Other calls run one at a time. Either way, the transcript and the results come out in the order the model asked for them.

Tool What it does
read_document Searches or reads a document attached to the chat.
search_chats Searches your earlier conversations (never the current one) and returns the questions with the answers they got.
expand_context Searches or pages through the full output behind a compacted tool result.
ask_user Asks you a question mid-turn, optionally with choices, and waits for the answer.
manage_tasks Keeps a checklist for the current chat, shown in the right rail.
manage_automation Creates, edits and runs scheduled automations.
manage_mcp Adds, changes, removes, enables and disables the servers in mcp.json. See Letting the model edit MCP servers.

Ask in a chat (“connect the GitHub MCP server”) and the model can edit mcp.json with manage_mcp. A local server is a program that runs on your machine, so every change waits for your approval, in every approval mode. A scheduled run can’t use it. Only roles with the mcp feature get it, and it refuses to change servers that are set in code or frozen.

mcp.json holds credentials, and the model can write them but never read them back. Its results show the names of headers and environment variables, never their values, and an update to headers or env changes only the entries it names, so a key is never repeated to change something beside it.

To keep a key out of the file and out of the chat entirely, set it in TinyWebUI’s environment and refer to it as ${NAME}:

{
"mcpServers": {
"github": {
"url": "https://api.githubcopilot.com/mcp/",
"headers": { "Authorization": "Bearer ${GITHUB_TOKEN}" }
}
}
}

${NAME} works in url, headers, args and env values, and a variable that isn’t set stops that server from connecting, with its name in the error. A key you paste into the chat is stored in the chat like any other message, and the model’s own call that writes it is kept in the transcript, so prefer ${NAME} for real keys.

Changes are saved straight away and the servers reconnect when the reply finishes, so a new server’s tools are available from your next message.

Integrations

The MCP page lists every connected MCP server, the bundled ones first. A server that offers a management page gets a Manage view there: tables and statistics about what it holds, and buttons that run its own tools. TinyContext shows each person their own memories, with search, editing and deletion; TinySearch shows their own search history when its activity history is on, and with TINYSEARCH_ACTIVITY=content each search also opens to exactly what the model was shown. Admins also see the servers’ instance-wide views, such as TinySearch’s domains and health, when the server is given a management token.

These views only ever show your own data. A server without an identity keeps everyone’s data in one store, so in a multi-user deployment its user views open only for admins, with a note that the data is everyone’s; other people see it listed but unavailable. To look into another person’s data, an admin with the oversight feature opens Settings → People & roles, then connectors next to that person. It runs on that person’s own connection, so it shows exactly what they see. It is read-only, and every view opened is written to the audit log.

Pages are built from plain data that TinyWebUI draws with its own components; a server never sends HTML or script. Any MCP server can offer one by implementing the tinysuite.manage/1 contract. The integrations feature controls who can open these views.

One TinySearch and one TinyContext can serve every user of a multi-user deployment. The pre-loaded servers already do this on one machine. To run them yourself, for example in their own containers, give each server in mcp.json an identity, and TinyWebUI tells it on every call which signed-in user the call is for:

{
"mcpServers": {
"tinycontext": {
"url": "http://tinycontext:8000/mcp",
"headers": { "X-TinyContext-Proxy-Token": "${TINYCONTEXT_TRUSTED_PROXY_TOKEN}" },
"identity": { "header": "X-TinyContext-User-Id" }
},
"tinysearch": {
"url": "http://tinysearch:8000/mcp",
"headers": { "X-TinySearch-Proxy-Token": "${TINYSEARCH_TRUSTED_PROXY_TOKEN}" },
"identity": { "header": "X-TinySearch-User-Id" }
}
}
}
  • The identity comes from the owner of the chat the turn runs in, never from the browser, the model’s arguments or the MCP server. Automations run as the owner of their chat.
  • Each user gets their own MCP connection to the server, so server-side session state, such as TinySearch’s browser, is never shared. A call for a user who doesn’t exist or isn’t approved is refused, never sent as someone else.
  • claim chooses what the header carries: TinyWebUI’s own user id (id, the default), the gateway’s id (externalId) or the email (email).
  • The *-Proxy-Token header proves to the server that a request comes from TinyWebUI. Keep the token in tinywebui.secrets.json or the environment, never in mcp.json itself.
  • identity works only on HTTP servers: url ones, or command ones that TinyWebUI starts over HTTP. A stdio server is one process that every user shares, with whatever data it keeps.

The server must believe the user header only when TinyWebUI sent it. An address alone isn’t enough: another container on the same network, or any local program when the server listens on loopback, could otherwise name any user. Both servers therefore check TinyWebUI’s address and a shared proxy token on every message. TinyContext’s hosted mode refuses to start without the token, and TinySearch treats a request without it as a caller with no identity, so no history is kept for it. This needs TinyContext 0.5.4 and TinySearch 0.6.8 or later. Keep the MCP servers on a private network that only TinyWebUI can reach. The shared MCP guide on GitHub walks through a deployment and a single-machine trial.

Give a command server a serve setting and TinyWebUI starts it over HTTP on a free loopback port instead of over stdio, so it can take an identity. This is how the pre-loaded servers run with sign-in on, and it works for any server that follows the TinySuite convention (MCP_TRANSPORT, MCP_HOST, MCP_PORT):

"tinycontext": {
"command": "uvx",
"args": ["--python", "3.12", "--from", "tinysuite-context[server]>=0.5.4", "tinycontext"],
"env": { "TINYCONTEXT_TENANCY": "proxy-header", "TINYCONTEXT_TRUSTED_PROXY_CIDRS": "127.0.0.1/32",
"TINYCONTEXT_TENANT_STORE_DIR": "${TINYWEBUI_DATA_DIR}/mcp/tinycontext/tenants" },
"serve": {
"proxyToken": { "env": "TINYCONTEXT_TRUSTED_PROXY_TOKEN", "header": "X-TinyContext-Proxy-Token" },
"managementToken": "TINYCONTEXT_MANAGEMENT_TOKEN",
"secrets": ["TINYCONTEXT_TENANT_SECRET"]
},
"identity": { "header": "X-TinyContext-User-Id" }
}
  • proxyToken: a new random token on every start, given to the server in env and sent by TinyWebUI as header on every request.
  • managementToken: also new on every start, and sent only on the server-wide connection that reads the admin’s instance views, never on a user’s own.
  • secrets: env vars that must stay the same across restarts, generated once and kept in the secrets file.
  • ${TINYWEBUI_DATA_DIR} is TinyWebUI’s own data folder.

TinyWebUI stops the server when it stops or reloads MCP, and starts it again on the next call if it exits.

Conversations are stored in tinywebui.db. You can rename a chat, edit and resend a message, retry an answer, rewind, and search them all. The search covers your messages and the final answers, but not reasoning, tool calls or raw tool output, so the results stay relevant. An outline on the right edge lists the questions in a long chat, and clicking one jumps to it.

The answer is what streams. While a turn works, one status line says what it is doing. When it finishes, its reasoning, tool calls and per-round usage fold into an Activity row you can open. Approvals and ask_user questions stay inline, and Jump to latest appears when you scroll up.

Edit, delete or fork any earlier question. Before anything changes, a dialog says what will go, change or be copied, counted from the transcript. A fork is a new chat that starts from that question, optionally with the chat’s documents and images, and is listed under the chat it came from.

Folders. Create a folder from the sidebar with a name, its own instructions and the chats to bring in. The instructions go into every turn of its chats, and a chat in a folder searches only the other chats in that folder. Deleting a folder asks whether its chats stay (moved out of the folder) or go with it. A chat that an automation has posted to is marked until you open it.

Turns run on the server. Reloading or disconnecting doesn’t cancel a turn: reopen the chat to rejoin its stream, or press stop. While a turn is running, press Enter to steer it, or Alt+Enter to hold a follow-up that you send when you’re ready.

Documents. Attach files with the paperclip, by dragging them onto the composer, or by pasting a long block of text. Text and source files, CSV, JSON, PDFs with extractable text and DOCX files are stored as documents for the chat. The model reads the relevant parts with read_document instead of getting the whole file in its context. Each document can be up to 5 MiB. Files you attached before can be reattached from the library without uploading them again.

Images are sent to the model with the message: up to eight per message, each up to 5 MiB. JPEG, PNG, WebP and GIF are sent as they are, and HEIC and AVIF are converted to JPEG. This needs a model and endpoint that accept OpenAI-style image content.

Files. The Files page, in the sidebar, lists every document and image you have attached, across all chats, newest first. Open one in the viewer, which shows images and files over the app instead of in a new tab, or add it to the chat you are in.

Not supported: OCR (scanned or image-only PDFs are refused with a clear error) and legacy .doc files (save them as .docx or .pdf).

Settings → Data downloads a backup: your chats, folders, automations and preferences in one JSON file. It leaves out uploaded documents and images (a message that had them keeps its words), search indexes, which are rebuilt from the text, and anything of the server’s: settings, keys and other people.

Importing a backup adds its chats to yours and never overwrites anything. The whole file is checked before anything is written, a chat you already have is skipped, so importing the same file twice changes nothing, and automations come in paused.

read_document and search_chats share one retrieval engine. A chat turn is indexed as the question together with the answer it finally got, without the narration or tool calls in between.

Search is hybrid by default. SQLite full-text search (BM25) matches exact words, and a small local embedding model matches meaning, so a question about an “automobile” finds the paragraph about the “sedan”. The two rankings are combined with Reciprocal Rank Fusion, using the same ONNX models and fusion as the TinySuite siblings TinySearch and TinyContext. Everything runs locally.

  • Install. npm install brings the embedding runtime (onnxruntime-node and @huggingface/tokenizers, both optional dependencies). The first npm start downloads the fast model through tinywebui models ensure. The default Docker image includes it.
  • Fallback. If the model or the runtime is missing (an offline first start, a platform where onnxruntime can’t install, or npm install --omit=optional), the default auto mode runs BM25 only and logs why.
  • Keyword search only. To skip hybrid search and the download, run TINYWEBUI_RETRIEVAL_MODE=lexical npm start or set { "retrieval": { "mode": "lexical" } }.
  • Pinning the model. { "retrieval": { "mode": "hybrid", "model": "fast", "modelSha256": "<sha256 from tinywebui models pull>" } } refuses to start with any other model file.
  • No downloads at runtime. Models only arrive through tinywebui models pull / models ensure or the Docker build. ONNX Runtime telemetry is switched off.

Small-to-big retrieval. Each document is split twice:

Passage Chunk
What it is What read_document returns to the model What gets embedded
Size passageSize characters (default 1,800, about 400 tokens) The embedding model’s token limit: 256 for fast, 512 for the others
Overlap passageOverlap characters (default 200) chunkOverlap tokens (default 32)
Used for BM25 (every mode) and the text the model reads Dense matching (dense, hybrid)

The question is compared with every small chunk, each passage takes its best chunk’s score, and the model gets whole passages. Small chunks keep the match precise, and large passages give the model enough context to answer. Chunk size follows the model, so every part of a passage is embedded, even one longer than the model can read at once.

Modes.

  • auto (default): hybrid when the model is installed, lexical when it isn’t.
  • lexical: BM25 only.
  • dense: embeddings only.
  • hybrid: both, fused.

An explicit dense or hybrid refuses to start without the model instead of falling back. A checksum that doesn’t match modelSha256 stops startup in every mode. tinywebui models verify and tinywebui doctor show which mode will run and why.

Models.

Preset Model Notes
fast (default) all-MiniLM-L6-v2 English, about 90 MB
balanced bge-small-en-v1.5 English
quality bge-base-en-v1.5 English
multilingual granite-embedding-107m-multilingual (Apache-2.0) About as fast as fast, 430 MB download

For questions and documents in different languages, keyword matches rarely help, so dense mode or a higher denseWeight usually ranks better. A custom bundle works with modelDir.

Embeddings are computed once. Document chunks are embedded when the document is attached, and chat turns when each run ends. Older chats and documents are embedded in the background at startup. Vectors are stored in SQLite, and a query only embeds the question. Switching models re-embeds everything automatically. A turn whose answer changes is re-embedded, and deleting or rewinding removes its vectors.

Tuning:

  • passageSize and passageOverlap set what the model gets back. Bigger passages give more context per hit, but fewer hits fit in one result.
  • chunkOverlap sets how much neighbouring chunks share.
  • denseWeight (default 0.5) and rrfK (default 60) control the fusion.
  • queryPrefix and documentPrefix are for models that expect instructions. For bge, set queryPrefix to "Represent this sentence for searching relevant passages: ".

Changing these is safe: stored documents are re-split when the passage settings change, and re-embedded when the model or chunkOverlap changes.

Adding a corpus. The engine in server/retrieval/retrieval.ts can search any source that describes its units through a small adapter (units, candidates, lexical, hydrate…). Register it with retrieval.register(name, corpus) and it gets lexical, dense and hybrid search, storage and backfill.

An automation posts its instructions into a chat you choose, on a five-field cron schedule in an IANA timezone. You can create automations under Settings → Automations, or ask the model to manage them with manage_automation.

  • Runs use the current model and enabled tools, and appear both in the chat and in the automation’s run history. The chat is marked in the sidebar until you open it.
  • Run now triggers one immediately. It waits for the chat’s current turn to finish.
  • Automations only run while TinyWebUI is running. A run that was missed, or that falls while the chat is busy, is skipped.
  • No external notifications are sent.

Tool results can be much larger than the conversation around them. TinyWebUI keeps every result in full in SQLite, but avoids sending it again and again:

  1. Cache-friendly prefixes. Between compactions, history is append-only and serialised deterministically, so providers can reuse the matching prompt prefix.
  2. One-time compaction. When history crosses compactThreshold, older tool results are replaced, once, with compact stubs. A stub holds an artifact ID, a hint about the structure, and the first and last lines verbatim. Older images are replaced with a short note.
  3. Nothing is lost. The model can get the exact content back through expand_context.
  4. A moving window as a last resort. If history is still over maxHistoryTokens, which usually happens in a very long chat with few tool calls, the oldest turns stop being sent. The cut falls on a user message and leaves a note that earlier conversation was omitted. With llmCompaction, those turns are first summarised (together with any earlier summary) into the system prompt. Rewinding to a point before the cut removes the summary.

Provider specifics. On OpenRouter, TinyWebUI sends a stable per-chat session_id so sticky routing keeps caches warm, and Claude gets the automatic rolling cache directive. Local and other endpoints get no OpenRouter-only fields. Set cacheMode only if your gateway needs a different cache dialect, or set cache: false to turn cache shaping off.

Every round in the transcript shows its token use, including cache reads and writes when the provider reports them. Settings → Usage totals usage over time and by model, and can drill down from all time to a single day. Extra summary requests made by llmCompaction show up there too.

Token attribution. Each assistant request stores a counts-only breakdown of where its tokens went. The input side covers the operator prompt, harness, MCP guidance, tool schemas per server, conversation, reasoning sent back, tool history and results, and images. The output side covers reasoning, tool calls, intermediate text and the final answer.

  • The provider’s totals and reported reasoning counts are authoritative. Everything else is estimated at about four characters per token, with images counted as 1,500 tokens, and is marked ~.
  • The gap to the provider’s total is shown as a signed difference and never rescaled away.
  • Cache reads are part of the input, not an extra component.
  • Requests made before attribution existed are not reconstructed.

Choose how people sign in with authMode:

Mode authMode For Sign-in
Local accounts "multiuser" (default) You, or a group, on your own machine or server Email and password. The first account is the administrator and invites the rest.
Local only "local" You, on this machine None
Sign-in gateway "trusted-header" A team or organisation Google, Apple, Microsoft, any SSO, through a sign-in gateway

This is the default for npx tinywebui, npm start and Docker.

  • The first account is the administrator. Create it in the browser with an email address and a password of at least 10 characters. The email is only checked for format: TinyWebUI sends no mail and needs no mail server.
  • Everyone else needs an invitation. An admin creates a single-use invitation link under Settings → People & roles, optionally for one email address. It expires after 7 days by default (anything from 1 hour to 30 days).
  • Or a request, if you allow it. With access.allowRequests: true (off by default, also a switch under People & roles), the sign-in page offers Request access: people choose their email and password and can leave a note of up to 500 characters. The request waits under People & roles. Until an admin approves it, signing in shows a waiting page, which opens the app once they’re let in. The email isn’t checked, so each address can send five requests an hour and at most 50 wait at once.
  • Sessions use HTTP-only signed cookies and last sessionTtlDays (default 30).
  • Lockout. After five wrong passwords, that address is locked out for 15 minutes.
  • HTTPS. Serve it over HTTPS, for example behind a reverse proxy, whenever it is reachable from outside your machine.

TinyWebUI sends no mail, so there is no emailed reset. People change their own password under Settings → Account, which asks for the current one first and signs out their other sessions. An admin can set a new password for anyone else from Settings → People & roles, which signs that person out everywhere.

If the admin is the one locked out, run this on the server. It prints a new password and signs that account out everywhere (--stdin reads the password instead):

Terminal window
npx tinywebui users password [email protected]
docker exec tinywebui node bin/tinywebui.ts users password [email protected]
docker compose exec tinywebui node bin/tinywebui.ts users password [email protected]

"authMode": "local" turns off sign-in. There is one person, who has full access to every chat, setting and tool, and no account management. This mode only listens on loopback: it refuses to start with any other --host, and it answers only loopback host names, plus any in allowedHosts, which guards against DNS rebinding.

TinyWebUI sits behind a sign-in gateway that handles the login, such as Cloudflare Access, oauth2-proxy, Authelia or Authentik. Any identity provider the gateway supports works. The gateway verifies each person and passes their identity in request headers:

{
"authMode": "trusted-header",
"trustedProxyCidrs": ["172.20.0.0/16"],
"trustedUserIdHeader": "x-tinysuite-user-id",
"trustedEmailHeader": "x-tinysuite-email",
"trustedNameHeader": "x-tinysuite-name",
"trustedRoleHeader": "x-tinysuite-role",
"logoutUrl": "https://<team>.cloudflareaccess.com/cdn-cgi/access/logout",
"access": {
"bootstrapAdmins": ["<your gateway user id>"],
"newUsers": "approved"
}
}
  • Accounts create themselves on a person’s first request. They are keyed on the gateway’s stable user ID, not on email, so a changed address keeps the same account.
  • New people wait for approval. Signing in at the gateway isn’t the same as being let in, so new accounts are pending until an admin approves them. Set access.newUsers: "approved", as above, to let everyone the gateway admits straight in.
  • The first admin comes from the config. Anyone listed in access.bootstrapAdmins is always an approved admin. The gateway can also send a role in the role header (admin, user or a custom role), but a decision recorded in the files outranks it.

These apply to both local accounts and a sign-in gateway.

  • Data is private to each user. This covers chats, documents, folders, search, automations and usage. The server refuses any request for another user’s data by ID, and a test matrix tries every route against another user’s IDs.

  • Roles grant features, models and what people may personalise. For example, users can be limited to chatting while admins set up models and MCP servers. A browser can never promote itself.

  • Custom roles. admin and user always exist. Any other name under access.roles (lowercase letters, digits and dashes, up to 32 characters) is a custom role, which starts with nothing and grants only what it lists:

    "access": {
    "roles": {
    "reviewer": { "features": ["chat", "search", "oversight"], "models": ["smart"], "customize": ["theme"] }
    }
    }

    customize (theme, instructions) defaults to access.customize. Admins can also create, change and delete roles on the Roles tab of Settings → People & roles, which shows what each grants and who holds it. Deleting a custom role moves its people to user. The admin role always has everything and can’t be edited.

  • Role settings. A role can also set what its people’s chats run with: its own prompt (which replaces the system prompt), default model, temperature, max tokens, max tool rounds, question timeout and tool approval. A value left blank keeps the global one, and a role’s value wins over the global one and a model’s own. The prompt, temperature, token and tool-round limits and tool approval can also be set for one model at a time, over the role’s own:

    "access": {
    "roles": {
    "student": {
    "features": ["chat"], "models": ["fast", "smart"],
    "settings": { "systemPrompt": "Explain step by step.", "model": "fast", "toolApproval": "all" },
    "modelSettings": { "smart": { "temperature": 0.2, "maxTokens": 2000 } }
    }
    }
    }

    The role editor’s Per model group sets the same from the page.

  • Admins get People & roles in Settings, where they can:

    • invite people, and approve or turn down access requests with their notes (local accounts);
    • approve pending users;
    • set a new password for a local account;
    • disable an account, which returns 403 immediately and stops that user’s automations;
    • change roles, and create custom ones;
    • read any user’s chats, documents and live turns. This view is read-only, and each view is recorded in the audit log;
    • open a user’s connectors to see their memories and search history as they see them, also read-only and audited (see Integrations).
  • Settings belong to the operator. Without the settings feature, the model, system prompt and approval rules are read-only, and credentials and the gateway address are hidden. Endpoints, keys and the model catalogue can only be changed by an admin. Without mcp, the MCP servers are hidden. Each person picks their own model from their role’s allowed list, and can pick a theme under Settings → Appearance and write their own instructions under Settings → Account (access.customize sets what people may personalise: theme, instructions). People who can’t pick see the theme an admin set for everyone.

  • Audit log. New accounts, invitations, rejected requests, role and status changes, config changes and admin views are written to stdout as [tinywebui:audit] JSON lines. Messages and secrets are never logged.

Every part of a deployment, down to what each role can see, can be set up from files. An agent or a script can build it, commit it to git and hand it over, and the running app stays in step with the files.

start() takes the same settings, so you can run an instance without any files:

import { start } from 'tinywebui';
const server = await start({
port: 7777,
config: { apiKey: process.env.OPENROUTER_API_KEY, model: 'anthropic/claude-sonnet-5' },
mcpServers: { files: { command: 'npx', args: ['-y', '@modelcontextprotocol/server-filesystem', '.'] } },
configFile: false, // or a path; false reads and writes no config file
dbPath: ':memory:',
});
// later: await server.shutdown();

The tinywebui command does the same when it finds tinywebui.config.js (or .mjs) in the working directory, or when TINYWEBUI_CONFIG points at one. The file’s default export is the options object, or a function (async is fine) that returns it. --port and --host still override it.

Layers apply lowest first: built-in defaults, the JSON config file, environment variables, then config from JavaScript. Keys set in JavaScript are locked: the Settings panel shows them read-only and the API refuses to change them. tinywebui.config.json is still read and written for everything else, unless the options set configFile: false. In that case changes last only as long as the process. Passing mcpServers replaces mcp.json and makes the MCP panel read-only.

Kind Where it lives Can the UI change it?
File-only: authMode, sessionSecret, sessionTtlDays, trusted*, logoutUrl, allowedOrigins, allowedHosts, dbPath, retrieval, autoMigrate, frozen, access (admins edit roles and whether access requests are allowed under Settings → People & roles) tinywebui.config.js or tinywebui.config.json Never. The API refuses, even for admins.
Locked: anything set in tinywebui.config.js, including mcpServers tinywebui.config.js No. Shown read-only.
Editable: everything else tinywebui.config.json, mcp.json Yes, and every change is written back to the file.
  • Freeze everything with frozen: true in either file. Settings, tools and MCP servers then can’t be changed from the UI or the API. You change the files and let them reload instead. User data and admins’ decisions about users still work normally.
  • Mistakes fail loudly. An unknown key (usually a typo), a value of the wrong type or a value outside its allowed set stops startup, reload, a UI save and tinywebui validate, and every problem is named. Nothing silently falls back to a default.
  • Admin decisions live in the files. Approving, disabling or changing someone’s role writes access.users in tinywebui.config.json before the database is touched. The files outrank the database: delete the database and restart, and every approval and ban is still in force.
  • Edits apply without a restart. Changes to tinywebui.config.json or mcp.json are picked up automatically, or on kill -HUP. A reload is all or nothing: a file that doesn’t parse or validate is rejected and logged, and the running config stays as it was. Changes to tinywebui.config.js or authMode need a restart.
  • Fingerprints. The effective config has a hash that never includes secrets. It is printed at startup, shown under Settings → People & roles, returned by /readyz and included in config-related audit lines before and after each change. Running tinywebui fingerprint on the committed files gives the same value, so you can check that a running instance matches a given commit.
// tinywebui.config.js: committed to git, holds no secrets
export default {
config: {
authMode: 'trusted-header',
trustedProxyCidrs: ['172.20.0.0/16'],
baseUrl: 'http://gateway:8080/v1', // your model gateway; users never see it
apiKey: process.env.MODEL_GATEWAY_KEY,
model: 'fast',
systemPrompt: 'You are the team assistant…', // locked: set here, so read-only in the UI
logoutUrl: 'https://team.cloudflareaccess.com/cdn-cgi/access/logout',
access: {
bootstrapAdmins: ['google-oauth2|1234567890'],
newUsers: 'pending', // the default: an admin approves each new person
roles: {
user: { features: ['chat', 'attachments', 'images', 'search', 'folders', 'model-picker'], models: ['fast', 'smart'] },
admin: { features: '*' },
// Any other name is a custom role, assignable under Settings → People & roles.
reviewer: { features: ['chat', 'search', 'oversight'], models: ['smart'], customize: ['theme'] }
}
}
},
mcpServers: { // locked: users can use these tools, nobody can edit them
search: { url: 'http://tinysearch:8000/mcp' },
context: { url: 'http://gateway:8080/context/mcp' }
}
};

The deployment guide on GitHub takes this through a scripted container deployment: validate, migrate, doctor, start and verify the fingerprint.

A role’s features list can include any of these. Each one covers both the UI and the API routes behind it: the UI hides what a role doesn’t have, and the server refuses it.

Feature Grants
chat Chatting
attachments Attaching documents
images Attaching images
search Searching chats
folders Organising chats into folders
automations Scheduled automations
statistics The Usage page
model-picker Choosing a model from the role’s list
tools Turning tools on and off
settings Changing settings
mcp Managing MCP servers
integrations The management views on the MCP page: your own data in servers that offer a management page, and for admins the servers’ own views
admin Managing users
oversight Reading other users’ chats and their data in connectors

Defaults. With accounts (multiuser or trusted-header), users get everything except tools, settings, mcp, admin and oversight, and admins get *. In local mode you get everything except user management.

Output on stdout is JSON or a single line, and logs go to stderr, so scripts can parse the output. Run any command with npx tinywebui <command>.

Command What it does
tinywebui [start] [--port] [--host] [--config] Run the server
tinywebui validate [path] Prints ok <fingerprint>, or lists every problem and exits with code 1
tinywebui effective [--role user|admin] What is in effect, how each setting can change, and what a role can see and do (also tinywebui config show)
tinywebui fingerprint Hash of the effective config (never includes secrets)
tinywebui schema JSON Schema for the config (also in docs/config.schema.json)
tinywebui migrate [--check] Run schema migrations as an explicit step. --check exits with code 1 if the database is behind. Set autoMigrate: false to make this mandatory.
tinywebui doctor Checks Node, config, database, model endpoint and each MCP server
tinywebui users list Users, and the decisions pinned in the files
tinywebui users set <id> [--role] [--status] [--clear] Record a decision in the config. A running server reloads it.
tinywebui users password <email> [--stdin] Break glass: a new password for a local account, printed (or read from stdin). Signs that account out everywhere.
tinywebui models pull <preset> [--dir] Download an embedding model (fast, balanced, quality, multilingual)
tinywebui models ensure Download the configured model only if it is missing
tinywebui models verify Load the configured model the same way startup does

For orchestrators, GET /healthz reports that the process is answering, and GET /readyz reports that it can serve requests ({"ready":true,"version":"…","fingerprint":"…"}).

  • Network exposure. local mode only ever listens on loopback. Use local accounts or a sign-in gateway, over HTTPS, before exposing TinyWebUI to a network.
  • MCP servers run with whatever access you give them. Treat each configured server and its credentials as trusted infrastructure, and use tool approval for anything that writes. A stdio server you add is shared by every user; use shared servers with an identity to keep users’ data apart. The pre-loaded TinySearch and TinyContext already do this when sign-in is on.
  • Model output is untrusted. Model-written text reaches the page only as text or through a Markdown renderer that escapes first, and the server sends strict security headers.
  • Deleting a chat also deletes its documents, tool output and search vectors.
  • Not included: OCR and cloud sync.
Terminal window
npm test # type check (server and page), then the whole suite, about 15 seconds on a fast disk
npm run dev # the API on :7777, restarting on changes in server/, bin/ and shared/
npm run dev:web # the page on :5173 with hot reload, proxying /api to :7777

The server is TypeScript that Node runs directly, with no build step, so working from a clone needs Node.js 22.18 or later. The page is Vue 3 and TypeScript in web/, built by Vite into dist/, which the server serves. npm start builds it first; during development npm run dev:web serves it with hot reload instead. The npm package ships JavaScript compiled from the server and the built page, and works from 22.13.

The tests cover message serialisation, caching, compaction, the tool loop and approvals, retries, editing, search, streaming and rejoining, settings, password and gateway sign-in, config write-back and reload, and a tenant-isolation matrix. They also enforce the architecture: import directions, the harness boundary, and the stream event registry. AGENTS.md maps the codebase and says where new code goes.

Evals (npm run eval) run the tasks in evals/tasks/ against the configured model and score its behaviour: whether it uses tools instead of guessing, ignores instructions planted in tool output, and reports failures honestly. They make real API calls to your configured endpoint, so they cost money.

TinyWebUI is licensed under the GNU Affero General Public License v3.0 or later. If you run a modified version for users over a network, you must offer them the corresponding source code for that version.