root
108 lines
3.9 KiB
Markdown
108 lines
3.9 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://homeassistant.local:18789` (or `http://192.168.1.10:18789`)
|
||
- Public domain with port-forward: `https://example.duckdns.org:12345`
|
||
- (in that case your router/NAT must forward `12345` → 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
|
||
|
||
### Router SSH (generic)
|
||
This add-on supports a **generic SSH configuration** for a router/firewall (or any LAN network device)
|
||
when you want the assistant to automate local network changes (e.g., port forwarding, DNS records,
|
||
firewall rules).
|
||
|
||
Config fields:
|
||
- `router_ssh_host`: host/IP of the router (reachable from the HA host network)
|
||
- `router_ssh_user`: SSH username
|
||
- `router_ssh_key_path`: path to the private key file inside the add-on (default: `/data/keys/router_ssh`)
|
||
|
||
How to provide the SSH key:
|
||
- Put the private key file under the add-on config directory so it appears in-container at `/data/keys/...`.
|
||
- Ensure permissions are restricted (recommended `chmod 600`).
|
||
|
||
Back-compat:
|
||
- Older versions used MikroTik-branded names: `mikrotik_host`, `mikrotik_ssh_user`, `mikrotik_ssh_key_path`.
|
||
These are still accepted but **deprecated**.
|
||
|
||
## 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.
|