# 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.