docs: add Open WebUI setup guide (#390)

docs/README.md

@@ -10,6 +10,7 @@ LettaBot is a multi-channel AI assistant powered by [Letta](https://letta.com) t
 - [Commands Reference](./commands.md) - Bot commands reference
 - [CLI Tools](./cli-tools.md) - Agent/operator CLI tools
 - [Chat API](./configuration.md#chat-endpoint) - HTTP endpoint for programmatic agent access
+- [Open WebUI Setup](./openwebui-setup.md) - Web chat UI via OpenAI-compatible API
 - [Response Directives](./directives.md) - XML action directives (reactions, etc.)
 - [Scheduling Tasks](./cron-setup.md) - Cron jobs and heartbeats
 - [Gmail Pub/Sub](./gmail-pubsub.md) - Email notifications integration

docs/openwebui-setup.md

@@ -0,0 +1,75 @@
+# Open WebUI Setup for LettaBot
+
+LettaBot exposes an [OpenAI-compatible API](./configuration.md#api-server-configuration) that any standard OpenAI client can connect to. [Open WebUI](https://github.com/open-webui/open-webui) is an open-source chat frontend that speaks this protocol, giving you a polished web interface for your LettaBot agent.
+
+## Prerequisites
+
+- **Docker** installed and running
+- **LettaBot running in API mode** (`server.mode: api` in `lettabot.yaml`)
+- **API key** from `lettabot-api.json` (auto-generated on first run)
+
+## Step 1: Start Open WebUI
+
+LettaBot's API server defaults to port 8080, so map Open WebUI to a different port (3000 in this example):
+
+```bash
+docker run -d -p 3000:8080 \
+  -e OPENAI_API_KEY=your_api_key_from_lettabot_api_json \
+  -e OPENAI_API_BASE_URL=http://host.docker.internal:8080/v1 \
+  --add-host=host.docker.internal:host-gateway \
+  -v open-webui:/app/backend/data \
+  --name open-webui \
+  --restart always \
+  ghcr.io/open-webui/open-webui:main
+```
+
+| Environment Variable | Description |
+|---------------------|-------------|
+| `OPENAI_API_KEY` | API key from `lettabot-api.json` or `LETTABOT_API_KEY` env var |
+| `OPENAI_API_BASE_URL` | LettaBot's OpenAI-compatible endpoint. Use `host.docker.internal` to reach the host machine from inside Docker |
+
+## Step 2: Create an Account
+
+Open http://localhost:3000 in your browser. The first account you create becomes the admin. This is local to the Docker volume -- pick any email and password.
+
+## Step 3: Select Model and Chat
+
+In the chat interface, open the model dropdown (top of the chat area) and select your agent's name. The model list is built from the `name` field of each agent in your `lettabot.yaml` -- e.g., if your agent is named `LettaBot`, that's what appears. Type a message and you should see your agent respond with full streaming support.
+
+## Troubleshooting
+
+### Port conflict
+
+If port 3000 is already in use, change the host port in the Docker command (e.g., `-p 3001:8080`).
+
+### "Invalid API key" from LettaBot
+
+Verify the key matches what's in `lettabot-api.json`:
+
+```bash
+cat lettabot-api.json
+```
+
+### Can't log in after recreating the container
+
+Open WebUI persists data in a Docker volume. If you forgot your password, remove the volume and start fresh:
+
+```bash
+docker rm -f open-webui
+docker volume rm open-webui
+```
+
+Then re-run the `docker run` command from Step 1.
+
+### Connection refused from Open WebUI
+
+Make sure LettaBot is running and the `--add-host=host.docker.internal:host-gateway` flag is included. This allows the container to reach services on your host machine. On Linux, you may also need `--network=host` instead.
+
+## Cleanup
+
+To stop and remove Open WebUI:
+
+```bash
+docker rm -f open-webui        # Remove container
+docker volume rm open-webui    # Remove data (optional)
+```