Marinara Engine — Home Assistant Integration

ATTENTION / ACHTUNG: This integration is currently Vibecoded and possibly not safe for production use.

Connects Marinara Engine to Home Assistant so your AI characters can control real-world devices — lights, climate, locks, covers, media players, and more — directly from chat, roleplay, and game sessions.

How it works

Marinara Engine supports custom webhook tools: when the AI decides to call a tool during generation, it POSTs to a webhook URL and feeds the result back to the language model. This integration:

1. Registers a private webhook endpoint inside Home Assistant
2. Creates all selected tool definitions in Marinara, pre-filled with that webhook URL
3. Creates a Home Assistant agent in Marinara that lists every HA tool in its enabled tools — making them appear in the chat's Function Calling picker automatically

Marinara AI  →  calls tool ha_turn_on  →  POST /api/webhook/<id>  →  HA turns on light
Marinara AI  ←  {"result": "Turned on light.living_room"}          ←  HA responds

Everything happens on first startup. You never copy URLs or configure tools manually.

Requirements

• Home Assistant 2024.1 or newer
• HACS installed
• Marinara Engine running locally or remotely

Installation

1. Add to HACS

1. Open HACS → three-dot menu → Custom repositories
2. URL: https://github.com/Gunterlie/marinara-engine-hacs
3. Category: Integration
4. Click Add, then search for Marinara Engine and install it
5. Restart Home Assistant

2. Add the integration

1. Go to Settings → Devices & Services → Add Integration
2. Search for Marinara Engine
3. Fill in the form:

Field	Required	Description
URL	Yes	Marinara Engine URL, e.g. http://localhost:7860 or https://marinara.home.example.de
Basic Auth User	No	Only if BASIC_AUTH_USER is set in Marinara's .env
Basic Auth Password	No	Only if BASIC_AUTH_PASS is set in Marinara's .env. Click the eye icon to reveal it.
Admin Secret	No	Only if ADMIN_SECRET is set in Marinara's .env. Click the eye icon to reveal it.

4. Click Submit

Tip: If Marinara runs on the same machine as Home Assistant, use http://localhost:7860 — loopback access bypasses all auth requirements.

On startup, the integration automatically:

• Registers a webhook inside Home Assistant
• Creates all tool definitions in Marinara → Settings → Custom Tools
• Creates a Home Assistant agent in Marinara → Agents with every HA tool already enabled

3. Done

Open any chat in Marinara. Your AI characters can now turn on lights, adjust the thermostat, play music, and more — they'll do it naturally as the narrative calls for it, without you having to prompt for it explicitly.

Configuration

After setup, open the integration's Configure menu to:

• Set a Primary Chat — the default target for send_message and trigger_generation HA services
• Choose Exposed Tool Categories — select which categories of HA tools Marinara can use (locks are off by default)
• Include device list in agent prompt — embeds your Home Assistant device catalog directly into the AI prompt. Off by default to save tokens. If you have many devices, leave this off and the AI will query on demand instead
• Update Basic Auth or Admin Secret if you change them in Marinara

Token usage warning: Enabling "Include device list" can consume hundreds of extra tokens per AI message (50 devices ≈ 1,500 tokens). Only enable it if you have a small home or want to reduce tool calls.

Changes take effect immediately after saving — no HA restart needed.

Authentication

Marinara Engine has two layers of authentication for external access. Your integration only needs to send what Marinara actually requires.

When is auth needed?

Marinara setup	Basic Auth needed?	Admin Secret needed?
Same machine (localhost)	❌ No	❌ No (unless MARINARA_REQUIRE_ADMIN_SECRET_ON_LOOPBACK=true)
LAN / Docker / Tailscale + ALLOW_UNAUTHENTICATED_PRIVATE_NETWORK=true	❌ No	✅ Yes
IP_ALLOWLIST matches HA's IP	❌ No	✅ Yes
BASIC_AUTH_USER + BASIC_AUTH_PASS configured	✅ Yes	✅ Yes
Nothing configured, remote IP	❌ Blocked	N/A

Admin Secret

Privileged endpoints (creating/updating tools and agents) require the X-Admin-Secret header when accessed from a non-loopback address. If you set ADMIN_SECRET in Marinara's .env, enter the same value in the integration.

⚠️ Docker Compose users: Do not wrap the secret in quotes:

# Correct
- ADMIN_SECRET=my_secret_value
# Wrong — literal quotes become part of the secret
- ADMIN_SECRET="my_secret_value"

Basic Auth

If Marinara has BASIC_AUTH_USER and BASIC_AUTH_PASS set, every request must include HTTP Basic Auth credentials. The integration sends them automatically on all API calls.

Entities

The integration creates a single Marinara Engine device with organized entities:

Controls

Entity	Type	Description
Home Assistant	Switch	Enable / disable the Home Assistant agent (enabled by default)
Abort generation	Button	Cancel any in-flight AI generation
Sync HA tools	Button	Re-sync all tool definitions and agent to Marinara

Configuration

Entity	Type	Description
Active chat	Select	Choose which chat HA services target
User activity	Text	Free-text activity string sent with every AI generation as context
Send message	Notify	Send messages to Marinara chats from HA automations or UI

Diagnostic

Entity	Type	Description
Connection	Binary Sensor	Whether Marinara Engine is reachable
Chat count	Sensor	Total number of chats
Active agent count	Sensor	Number of globally enabled agents
Version	Sensor	Marinara Engine version
Last sync	Sensor	Timestamp of the last successful tool sync

Note: Individual agent switches (other than Home Assistant) are created but disabled by default. Enable them in the entity settings if you want to toggle them from Home Assistant.

Tool categories

You can choose which categories to expose in the integration's Configure menu. Locks are off by default.

Category	Tools
Lights & Switches	ha_turn_on, ha_turn_off, ha_toggle, ha_set_brightness, ha_set_color, ha_set_color_temp
Climate	ha_set_temperature, ha_set_hvac_mode
Covers (Blinds & Garage)	ha_open_cover, ha_close_cover, ha_set_cover_position
Locks	ha_lock, ha_unlock
Media Players	ha_media_play, ha_media_pause, ha_set_volume
Scenes & Scripts	ha_activate_scene, ha_run_script
Query & Generic	ha_get_state, ha_list_entities, ha_call_service, ha_notify

The Home Assistant agent

On first sync the integration creates a Home Assistant agent in Marinara (visible under Agents). This agent:

• Runs in parallel during every generation turn
• Has all enabled HA tools listed in its Function Calling settings
• Carries a prompt that instructs the AI to act on smart home cues naturally — dimming lights when a character reaches for the switch, adjusting the thermostat when the temperature comes up in conversation, and so on

The agent is kept in sync automatically — pressing Sync HA Tools after changing the enabled categories will update the agent's tool list in place. No manual deletion needed.

HA Services

Use these in automations to interact with Marinara from Home Assistant's side.

notify.marinara_engine

Send a message to a Marinara chat. Accepts chat name or chat ID as target.

Field	Required	Description
message	Yes	Message content
target	No	Chat ID or chat name (defaults to primary chat)
role	No	user / assistant / system / narrator. Defaults to user. Note: Conversation mode only supports user and assistant
trigger_generation	No	Also trigger an AI response (default: false)

Example — send a quick message from Developer Tools:

service: notify.marinara_engine
data:
  message: "Someone just arrived at the front door."
  target: "Dave RP"
  role: "system"
  trigger_generation: true

Example — automation:

automation:
  trigger:
    platform: state
    entity_id: binary_sensor.front_door
    to: "on"
  action:
    service: notify.marinara_engine
    data:
      message: "Someone just arrived at the front door."
      trigger_generation: true

marinara_engine.send_message

Low-level service to send a message to a Marinara chat. Prefer notify.marinara_engine for most use cases.

Field	Required	Description
message	Yes	Message content
chat_id	No	Target chat ID (defaults to primary chat)
role	No	user / assistant / system / narrator
trigger_generation	No	Also trigger an AI response (default: false)

marinara_engine.trigger_generation

Start an AI generation turn in a chat.

Field	Required	Description
chat_id	No	Target chat ID (defaults to primary chat)
user_message	No	Optional user message to include

Events

The integration fires a Home Assistant event every time Marinara calls a tool via the webhook:

Event type: marinara_engine_tool_called

Event data:

Field	Description
tool	Tool name, e.g. ha_turn_on
arguments	Arguments the AI passed to the tool
result	The result returned to Marinara

Use this in automations to react to AI-driven device control — for example, logging every tool call, showing a dashboard notification, or triggering a chime when a lock is accessed.

automation:
  trigger:
    platform: event
    event_type: marinara_engine_tool_called
    event_data:
      tool: ha_turn_on
  action:
    service: notify.mobile_app
    data:
      message: "AI turned something on: {{ trigger.event.data.arguments }}"

Re-syncing tools

Press Marinara Sync HA Tools on the integration's device page to push any missing tools and recreate the agent if it was deleted. Tools that already exist are updated in place — it's safe to press at any time.

Troubleshooting

Cannot connect on setup Make sure Marinara Engine is running and the URL you entered is reachable from Home Assistant. Try curl http://marinara:7860/api/health from the HA container.

Sync HA Tools returns 403 Forbidden Marinara's privileged API requires both Basic Auth (if configured) and X-Admin-Secret from non-loopback addresses.

1. Check that Admin Secret is set in the integration (matching ADMIN_SECRET in Marinara's .env)
2. If BASIC_AUTH_USER/PASS is set in Marinara, enter them in the integration too
3. If Marinara and HA run on the same machine, use http://localhost:7860 as the URL to bypass auth requirements

Tools not appearing in Marinara's Custom Tools Press Marinara Sync HA Tools, or restart Home Assistant. Verify under Settings → Custom Tools in Marinara.

Home Assistant agent not showing up in Marinara Press Marinara Sync HA Tools. If it's already in the Agents list but not visible in a chat, it may be disabled — enable it there.

Tools not available in a chat's Function Calling picker The Home Assistant agent must be enabled in Marinara (Agents list). If it's there but disabled, enable it. If it's missing entirely, press Sync HA Tools to recreate it.

Webhook calls failing Check that Home Assistant is reachable from the machine running Marinara Engine. If they run on the same machine, the internal URL (http://localhost:8123) is used automatically. If Marinara runs on a different device, make sure HA's local network URL is accessible from that device.

Finding the webhook URL manually Go to Settings → Devices & Services → Marinara Engine in HA. The webhook ID is stored in the config entry. The full URL follows the pattern:

http://<homeassistant-ip>:8123/api/webhook/<webhook-id>

Each tool in Marinara's Custom Tools list already has this URL set.