A small, local-first chat UI for any OpenAI-compatible model, with MCP tools
635
A small, local-first chat workspace for any OpenAI-compatible model, with MCP tools.
Part of TinySuite. Comes with TinySearch and TinyContext already connected.
A real first run with DeepSeek V4.1 Flash through OpenRouter, sped up. Watch the full 100-second walkthrough.
TinyWebUI is the chat interface of TinySuite, a set of small, local-first tools for AI agents. 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. 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 needs no build step: the page ships prebuilt.
It comes pre-loaded with two TinySuite MCP servers, so a new install can already search the web and remember things:
access.allowRequests: true (off by default), ask from the sign-in page and wait for an admin to approve them. Teams can alternatively put SSO in front.Requires Node.js 22.13 or later. The bundled TinySearch and TinyContext servers also need uv, which fetches them the first time they start. With sign-in on, each person gets their own memories and search history, and both keep their data in TinyWebUI's own folder (docs/multi-user-mcp.md).
npx tinywebui
Open http://127.0.0.1:7777 and create the first account with 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 connection (connectors in the config: any OpenAI-compatible URL, with an API key if it needs one), then the models people can pick from it. Every model, with its prompt, sampling and caching, belongs to a connection. The same in tinywebui.config.json (start from example.tinywebui.config.json):
{
"connectors": [
{
"id": "local",
"baseUrl": "http://localhost:11434/v1",
"models": [{ "id": "llama", "label": "Llama 3.2", "model": "llama3.2" }]
}
]
}
A connector that needs a key takes "apiKey": "${NAME}", filled in from the environment, or the key typed into Settings.
With accounts, a role decides what its people may use (features, models, what they may personalise) and, under Settings → People & roles, what their chats run with: its own prompt (which replaces the system prompt), default model, temperature, token and tool-turn limits, question timeout and tool approval. A value left blank keeps the global one. The prompt, temperature, token and tool-turn limits and tool approval can also be set for one model at a time, over the role's own. In the file these are access.roles.<name>.settings and access.roles.<name>.modelSettings.<model id>:
{ "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 } } } } } }
tinywebui.config.json describes the deployment (endpoints, connectors, models, policy) and holds no secrets. A key is either a ${NAME} reference, filled in from the environment, or kept in tinywebui.secrets.json beside it: what the Settings panel saves, and the generated session-signing secret. A key written straight into the config file moves there the next time the server starts. Accounts, password hashes and conversations live in tinywebui.db. TinyWebUI keeps the secrets file and the database readable by their owner only; keep them private and backed up.
npx tinywebui keeps the config, keys, database and embedding models 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. It uses keyword search until you run npx tinywebui models pull fast (about 90 MB) to enable hybrid search.
From a clone, run npm install && npm start.
With Docker, run the image from Docker Hub (amd64 and arm64), then create the administrator with an email address and password in the browser. The email is checked for valid format; TinyWebUI does not send mail or require a mail server for local accounts:
docker run -d --name tinywebui -p 127.0.0.1:7777:7777 -v tinywebui-data:/data marcellm01/tinywebui
This publishes port 7777 on the host's loopback interface only. Keep the data volume: it contains the accounts, conversations and local password hashes.
| Tag | Image |
|---|---|
latest | Hybrid search, with the embedding model baked in. Includes uv, so the bundled TinySearch and TinyContext start as they do with npx. |
light | Keyword search only, smaller. No uv: connect MCP servers over HTTP. |
Each image is signed with cosign and carries an SBOM and build provenance. To build it yourself from a clone, run docker compose build && docker compose up -d.
Since no mail is sent, there is no emailed reset. People change their own password under Settings → Account, and an admin can set a new one for anyone from Settings → People & roles. If the admin is the one locked out, run this on the server, where it prints a new password and signs that account out everywhere (--stdin reads the password instead):
node bin/tinywebui.ts users password [email protected] # from a clone
docker exec tinywebui node bin/tinywebui.ts users password [email protected] # docker run
docker compose exec tinywebui node bin/tinywebui.ts users password [email protected]
npm start and npx tinywebui default to multiuser setup. To run a local workspace without login, explicitly set "authMode": "local" in tinywebui.config.json; this mode binds only to loopback and has full access to settings and data, without account management. The runtime images contain Node.js but no npm/npx (the default one has uv for the bundled servers); connect other MCP servers over HTTP or include their executables in a custom image.
The former password-only single mode now fails startup instead of opening without login. To move such an installation to local accounts, set authMode to multiuser, restart, and create the administrator in the browser. On that first setup, existing unowned chats, files, artifacts, folders and automations move to the new administrator. Remove any TINYWEBUI_PASSWORD environment variable; it no longer selects an auth mode.
The full reference lives at tinysuite.dev/docs/tinywebui:
| Topic | Covers |
|---|---|
| Quick start | npx, clone, Docker |
| Configuration | Environment variables, every setting, the model catalog |
| MCP tools | Adding servers, tool approval, built-in tools |
| Chats and attachments | Documents, images, steering a turn |
| Search | Hybrid retrieval, embedding models, tuning |
| Automations | Scheduled prompts |
| Long chats | Caching and compaction |
| Usage statistics | Token use and attribution |
| Access | Local invited users, explicit local mode, or a team behind SSO |
| Deployment as code | JavaScript config, locked settings, roles and features |
| CLI | Every command |
| Security and limits | Exposure, MCP trust, what isn't included |
In this repository: docs/architecture.md is how the pieces fit, what the app survives and how its pages are laid out, docs/deploy.md is a scripted container deployment, docs/multi-user-mcp.md covers sharing one TinySearch and TinyContext between many users, docs/mcp-management.md is the contract any MCP server can implement to get a page on the MCP page, docs/config.schema.json is the config schema (also tinywebui schema), and docs/performance.md is what the page costs a browser, with the method to measure it again.
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, and 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 (npm run build, which npm pack runs) and works from 22.13.
AGENTS.md maps the codebase and says where new code goes. npm run eval runs model-behaviour evals from evals/tasks/ and makes real API calls, so it costs money.
Copyright (C) 2026 MarcellM01
TinyWebUI is free software, released under the GNU Affero General Public License v3.0 or later. It comes with no warranty. If you run a modified version for users over a network, you must offer them the corresponding source code for that version.
Content type
Image
Digest
sha256:c2f17eb63…
Size
329.5 MB
Last updated
1 day ago
docker pull marcellm01/tinywebui