overthinkos/openwebui-layer

openwebui -- Open WebUI with auto-configuration

Candy Properties

| Property | Value | |----------|-------| | Dependencies | python, supervisord | | Volumes | data -> /opt/data | | Ports | 8080 | | Aliases | open-webui -> open-webui | | Services | openwebui (supervisord, autostart) | | Install files | pixi.toml, task:, openwebui-entrypoint |

Environment Variables

| Variable | Value | |----------|-------| | DATA_DIR | /opt/data | | PORT | 8080 | | DOCKER | true | | ENABLE_DIRECT_CONNECTIONS | true | | ENABLE_CODE_EXECUTION | true | | ENABLE_PERSISTENT_CONFIG | false |

Optional Environment Variables (env_accept)

| Variable | Description | |----------|-------------| | OPENROUTER_API_KEY | API key for OpenRouter (maps to OPENAI_API_KEY with OpenRouter base URL) | | OLLAMA_API_KEY | API key for Ollama Cloud inference | | OLLAMA_HOST | Local Ollama server URL (auto-injected by ollama candy env_provide) | | OPENAI_API_KEY | Direct OpenAI API key | | OPENAI_API_BASE_URL | OpenAI-compatible API base URL | | WEBUI_AUTH | Enable authentication (default: true) | | WEBUI_ADMIN_EMAIL | Admin account email for first-start setup | | CHARLY_MCP_SERVERS | JSON array of MCP servers (auto-injected by mcp_provide candies) |

MCP Accepts

| Name | Description | |------|-------------| | jupyter | JupyterLab CRDT MCP server for notebook manipulation | | chrome-devtools | Chrome DevTools MCP server for browser automation |

Secrets (Two-Tier Architecture)

Tier 1: Infrastructure secrets (podman secrets via secret: field)

Auto-generated, stored in credential store (keyring/config-file fallback):

| Secret | Env Fallback | Purpose | Auto-gen path | |--------|-------------|---------|---------------| | webui-secret-key | WEBUI_SECRET_KEY | JWT + encryption key (CRITICAL: losing it breaks all sessions and OAuth tokens) | charly config time, ProvisionPodmanSecrets | | admin-password | WEBUI_ADMIN_PASSWORD | Admin account password — declared as secret_require: | charly bundle add time, ensureCandySecret |

Provisioned as Secret=charly-openwebui-<name>,type=env,target=<ENV> in the quadlet. The entrypoint checks env vars first (from type=env injection), then file mounts at /run/secrets/ as fallback.

First-run admin login: WEBUI_ADMIN_PASSWORD auto-generates as a 32-byte hex random value if not pre-set. To retrieve the auto-generated password and log in for the first time:

charly secrets get charly/secret WEBUI_ADMIN_PASSWORD

Override with a specific password before the first deploy:

charly secrets set charly/secret WEBUI_ADMIN_PASSWORD <password>
charly config openwebui  # picks up the override

Tier 2: User API keys (GPG-encrypted .secrets file)

User-provided API keys stored via charly secrets gpg:

charly secrets gpg set OPENROUTER_API_KEY sk-or-xxx
charly config openwebui --env-file .secrets     # Decrypts + injects at config time

Auto-Configuration Entrypoint

The openwebui-entrypoint runs on EVERY start (no sentinel — ENABLE_PERSISTENT_CONFIG=false means env vars always override database config):

1. Reads secrets from env vars (podman type=env) or /run/secrets/ file mounts
2. LLM provider detection:
   • OLLAMA_HOST -> OLLAMA_BASE_URL (Ollama server)
   • OPENROUTER_API_KEY -> OPENAI_API_KEY + OPENAI_API_BASE_URL=https://openrouter.ai/api/v1
   • OLLAMA_API_KEY -> OPENAI_API_KEY + OPENAI_API_BASE_URL=https://api.ollama.com/v1
3. MCP server discovery from CHARLY_MCP_SERVERS JSON -> builds TOOL_SERVER_CONNECTIONS JSON for Open WebUI
4. Jupyter detection — if a jupyter MCP server URL is found, sets CODE_EXECUTION_ENGINE=jupyter
5. Execs open-webui serve

TOOL_SERVER_CONNECTIONS Format

The entrypoint translates charly's CHARLY_MCP_SERVERS format into Open WebUI's expected TOOL_SERVER_CONNECTIONS JSON:

[{
  "type": "mcp",
  "url": "http://charly-jupyter:8888/mcp",
  "spec_type": "url", "spec": "", "path": "",
  "auth_type": "", "key": "",
  "config": {"enable": true},
  "info": {"id": "", "name": "jupyter", "description": "MCP: jupyter"}
}]

Key fields: type must be "mcp" (not "openapi"), config.enable must be true.

Key Design Choice: ENABLE_PERSISTENT_CONFIG=false

This is the critical architectural decision. Without it, Open WebUI's database config overrides environment variables after the first admin-panel save. With it disabled, env vars ALWAYS win — so the entrypoint's dynamic configuration (LLM providers, MCP servers, Jupyter) works reliably on every restart. No sentinel-guarded config patching needed (unlike hermes).

Important: No port_relay Needed

Open WebUI binds to 0.0.0.0:8080 by default. The port_relay field is only for services that bind to 127.0.0.1 (like Chrome DevTools on port 9222). Using port_relay with Open WebUI causes a socat/Open WebUI port conflict on eth0.

Build Notes

• pixi.toml uses [pypi-dependencies] (NOT [feature.default.pypi-dependencies] — the default feature is reserved in pixi)
• Open WebUI is installed via pip install open-webui in the pixi environment (~500MB+ of dependencies)
• First startup takes ~30 seconds (Alembic DB migrations, model loading). supervisord autorestart=true handles transient failures.

Usage

# charly.yml
openwebui:
  base: fedora
  candy:
    - agent-forwarding
    - openwebui
    - dbus
    - charly
  ports:
    - "8080:8080"

Related Candies

• /charly-languages:python -- Python runtime dependency
• /charly-infrastructure:supervisord -- process manager dependency
• /charly-hermes:hermes -- alternative AI agent with similar MCP/LLM auto-config pattern

Related Commands

• /charly-core:charly-config -- charly config openwebui --update-all for service discovery
• /charly-build:secrets -- charly secrets for Secret Service / GPG credential management
• /charly-core:service -- charly service status openwebui for runtime management
• /charly-build:charly-mcp-cmd -- probe the MCP servers openwebui consumes (auto-configured into TOOL_SERVER_CONNECTIONS from CHARLY_MCP_SERVERS): charly check live <provider-image> --filter mcp shows what tools openwebui will see and verifies liveness before debugging openwebui itself.

Related Boxes

• /charly-openwebui:openwebui -- the deployed box
• /charly-jupyter:jupyter -- deploy alongside for MCP notebook access and code execution
• /charly-ollama:ollama -- deploy alongside for local LLM inference
• /charly-hermes:hermes -- alternative AI frontend (CLI-based agent vs web UI)

When to Use This Skill

MUST be invoked when the task involves the openwebui candy, Open WebUI configuration, LLM provider auto-detection, MCP server discovery for Open WebUI, or the openwebui entrypoint. Invoke this skill BEFORE reading source code or launching Explore agents.

Related

• /charly-image:layer — candy authoring reference (charly.yml schema, task verbs, service declarations)
• /charly-check:check — declarative testing (check: block, charly check box, charly check live)