Tetra-AI-HA-App/DOCS.md

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.