root
92 lines
3.3 KiB
Markdown
92 lines
3.3 KiB
Markdown
# Moltbot Assistant (Home Assistant Add-on)
|
||
|
||
This add-on runs a Moltbot Assistant instance on Home Assistant OS (Supervisor add-on).
|
||
|
||
> 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.
|
||
|
||
## 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
|
||
2. Add repository URL:
|
||
- Add-on store → ⋮ → Repositories → paste the GitHub repo URL
|
||
3. Install **Moltbot Assistant**
|
||
|
||
## Configuration overview
|
||
All configuration is done via the add-on UI (Options).
|
||
|
||
### Required
|
||
- `telegram_bot_token`
|
||
|
||
### Recommended baseline (safe defaults)
|
||
- `gateway_bind: loopback`
|
||
- `gateway_port: 18789`
|
||
- `gateway_token: ""` (auto-generated by gateway when loopback)
|
||
- `enable_terminal: false`
|
||
|
||
### 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)
|
||
- `homeassistant_token`: written to `/config/secrets/homeassistant.token` inside the container
|
||
- MikroTik SSH fields: `mikrotik_host`, `mikrotik_ssh_user`, `mikrotik_ssh_key_path`
|
||
|
||
## Troubleshooting
|
||
|
||
### 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.
|