Docs: clarify ingress terminal + external gateway UI setup
This commit is contained in:
root
@@ -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:
|
||||
|
||||
`<gateway_public_url>/?token=<gateway_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.
|
||||
|
||||
Reference in New Issue
Block a user