Open WebUI

Tool server

Open WebUI’s backend is the MCP client, so it reaches the server over loopback. Register it under Admin Panel → Settings → Integrations → Tool Servers as an admin connection:

Field Value
Type MCP (Streamable HTTP)
URL http://127.0.0.1:8099/mcp
Auth Bearer, the service’s token
ID kioku

The ID matters: skills.toml refers to the tool as server:mcp:kioku.

Skills and the Kioku model

publish-skills publishes the convention docs as Open WebUI skills and creates the workspace models listed in skills.toml. The skills come in two groups, by tag:

Tag Skills Content
kioku kioku-cards, kioku-notes, kioku-book-notes, kioku-convert, kioku-reports, kioku-media Card rules, note style, notes from a book, HTML conversion, publishing a set of notes, images, videos and interactive pages
diagrams diagrams, diagrams-mermaid, diagrams-circuits Choosing a drawing tool, mermaid, circuits with schemdraw

The Kioku model is built on the base model named in secrets.toml, which stays untouched, so the model picker switches between the version with kioku and the one without. Kioku gets:

Other models keep their settings: enable kioku and the terminal in the chat’s menus and mention a skill with $ (e.g. $kioku-cards).

API key

The script uses an admin API key. API keys are off by default, so set them up once:

  1. Admin Panel → Settings → Authentication: turn on API keys, and turn on API key endpoint restrictions with /api/v1/skills,/api/v1/models/model,/api/v1/models/create,/api/v1/functions as the allowed endpoints. Matching is by prefix, so a leaked key can touch skills, workspace models and functions, not chats or knowledge bases. Functions run Python inside Open WebUI, so the key is as sensitive as admin access to its process. The restriction applies to every API key: add endpoints to the list if another key needs them.
  2. Settings → Account → API Keys: generate the key.

Configuration

publish-skills reads [openwebui] from secrets.toml (gitignored) in the repo root. Start from the template:

cp secrets.example.toml secrets.toml
Key Value
url Open WebUI’s base URL
api_key The restricted key from above
terminal_id ID of the Open Terminal connection, from Admin Panel → Settings → Integrations → Terminals
base_model Model the Kioku model is built on, as listed in Admin Panel → Settings → Models
compact_token_threshold Tokens above which older messages are summarized: about 75-80% of the base model’s context window (max_model_len on vLLM)
sandbox_dir Workspace path inside the Open Terminal sandbox, the server’s sandbox.mountPoint

OWUI_URL, OWUI_API_KEY and OWUI_TERMINAL_ID override the first three.

Every key except api_key is also a template variable: skills.toml and the docs marked template = true there are rendered with Jinja before publishing, so {{ sandbox_dir }} in a skill becomes the real path. A variable the templates use but secrets.toml lacks stops the script with its name.

Publishing

Publish from the repo root. The command is idempotent and restores the model defaults if they were changed in the UI: rerun it after editing a doc or skills.toml.

nix run path:.#publish-skills

Each skill should come back with its content, the filter active with the terminal ID in its valves, and the kioku model with its base_model_id, params.system, params.compact_token_threshold, and toolIds, skillIds, filterIds and builtinTools.notes = false in its meta. Anything outside the allowed endpoints gets 403:

curl -s -H "Authorization: Bearer $KEY" "$URL/api/v1/skills/id/kioku-cards"
curl -s -H "Authorization: Bearer $KEY" "$URL/api/v1/functions/id/default_terminal/valves"
curl -s -H "Authorization: Bearer $KEY" "$URL/api/v1/models/model?id=kioku"