From 392f5b3d0c83d10eb7e79a927c3e861b24ae92b8 Mon Sep 17 00:00:00 2001 From: root Date: Fri, 30 Jan 2026 15:13:53 +0200 Subject: [PATCH] Docs: clarify ingress terminal + external gateway UI setup --- DOCS.md | 98 ++++++++++++++++++++++++++++++++++++++++--------------- README.md | 5 +++ 2 files changed, 76 insertions(+), 27 deletions(-) diff --git a/DOCS.md b/DOCS.md index 15170f1..15b9e24 100644 --- a/DOCS.md +++ b/DOCS.md @@ -4,12 +4,19 @@ This add-on runs a Moltbot Assistant instance on Home Assistant OS (Supervisor a > Note: Moltbot is the new name for the upstream Clawdbot project. Internally, this add-on may still use the `clawdbot` CLI/package as a compatibility layer. -## Features -- Ingress UI inside Home Assistant (no LAN port required) -- Telegram channel support (bot token) -- Optional Brave web search (Brave API key) -- Optional Home Assistant long-lived token persisted in the add-on secrets folder -- Optional web terminal inside Home Assistant (disabled by default) +## What this add-on provides + +### 1) Ingress page (embedded) +The add-on’s **Ingress UI** is intentionally kept simple and reliable: +- a landing page +- an **embedded web terminal** (optional) +- a button/link that opens the **Gateway Web UI in a separate browser tab** (not embedded) + +This avoids Home Assistant Ingress websocket edge-cases. + +### 2) Gateway Web UI (separate tab) +The Gateway Web UI requires websockets. Instead of trying to tunnel that through HA Ingress, +we open it directly using a user-provided public/base URL. ## Installation 1. Home Assistant → Settings → Add-ons → Add-on store @@ -17,31 +24,68 @@ This add-on runs a Moltbot Assistant instance on Home Assistant OS (Supervisor a - Add-on store → ⋮ → Repositories → paste the GitHub repo URL 3. Install **Moltbot Assistant** -## Configuration -Configure via the add-on UI. +## Configuration overview +All configuration is done via the add-on UI (Options). -Required: +### Required - `telegram_bot_token` -Recommended: -- `gateway_bind`: `loopback` -- `gateway_token`: set a fixed token (Ingress proxy uses it server-side) +### Recommended baseline (safe defaults) +- `gateway_bind: loopback` +- `gateway_port: 18789` +- `gateway_token: ""` (auto-generated by gateway when loopback) +- `enable_terminal: false` -Optional: -- `telegram_allow_from`: comma-separated Telegram user IDs -- `homeassistant_token`: written to `/config/secrets/homeassistant.token` +### Terminal (Ingress) setup +To enable the embedded web terminal: +- Set `enable_terminal: true` + +Then open the add-on Ingress page. You will see a terminal iframe. + +Security note: the terminal is powerful. Only enable if you trust HA admins with shell access +inside the add-on container. + +### Gateway Web UI (separate tab) setup +To open the gateway UI in a separate tab reliably: + +1) Expose the gateway: +- Set `gateway_bind: lan` +- Set `gateway_port` (default `18789`) +- Set a **fixed** `gateway_token` (required when `gateway_bind=lan`) + +2) Tell the add-on what URL to open: +- Set `gateway_public_url` to a base URL that the browser can reach. + +Examples: +- LAN only: `http://192.168.88.31:18789` +- DuckDNS with port-forward: `https://vanevihomeha.duckdns.org:38123` + - (in that case your router/NAT must forward 38123 → HA host → gateway port) + +The Ingress landing page button will open: + +`/?token=` + +Notes: +- This is intentionally **not embedded**. +- This avoids the unreliable “ingress websocket proxy” path. + +## Optional options +- `telegram_allow_from`: comma-separated Telegram user IDs (locks DMs) - `brave_api_key`: exported as `BRAVE_API_KEY` (for web search) -- `enable_terminal`: enables web terminal at `/terminal/` - -## UI / Ingress -- The add-on uses **Ingress**. Open the add-on page to access the gateway UI. -- If `enable_terminal=true`, the terminal is available under the same ingress base at `/terminal/`. - -## Security notes -- Keep `gateway_bind=loopback` unless you know what you’re doing. -- Terminal is powerful: only enable it if you trust all Home Assistant admins with shell access to the add-on container. +- `homeassistant_token`: written to `/config/secrets/homeassistant.token` inside the container +- MikroTik SSH fields: `mikrotik_host`, `mikrotik_ssh_user`, `mikrotik_ssh_key_path` ## Troubleshooting -- If Ingress loads but the gateway UI is unauthorized, verify `gateway_token` is set. -- If Telegram doesn’t connect, verify the bot token using @BotFather and check add-on logs. -- If search tools fail, check that `brave_api_key` is set and that your plan limits aren’t exceeded. + +### Terminal doesn’t show +- Ensure `enable_terminal=true` +- Check add-on logs for `Starting web terminal (ttyd)` + +### Gateway button opens but UI says unauthorized +- Ensure `gateway_token` is set when using `gateway_bind=lan`. +- Ensure the opened URL includes `?token=...` (the add-on button does this automatically). + +### Gateway button opens but cannot connect +- Confirm the browser can reach `gateway_public_url`. +- Confirm your NAT/port-forward rules (if using DuckDNS/Nabu Casa is **not** involved here). +- If you want Nabu Casa support for the gateway UI, do **not** expose the gateway; use the assistant via Telegram and keep gateway loopback. diff --git a/README.md b/README.md index 1a905dd..9c24c8b 100644 --- a/README.md +++ b/README.md @@ -21,6 +21,11 @@ Upstream note: Moltbot is the new name for the Clawdbot project. The add-on may 2. Install **Moltbot Assistant** 3. Configure options (at minimum: Telegram bot token) +## Setup / Docs +See **DOCS.md** for the supported setups: +- embedded terminal via Ingress +- opening Gateway Web UI in a new tab (not embedded) + ## Configuration All configuration is done via the add-on UI. See the schema in `moltbot_assistant/config.yaml`.