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 (recommended: no trailing slash).

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.