Automation

Configure the automation engine and template variables.

Overview

The automation engine allows you to create rules that trigger actions based on streaming events. Rules are evaluated in real-time and can execute chat commands, overlay updates, or API calls.

Permissions

Automations use six dedicated permissions:

Permission	Description
automations:read	View automations and their configuration
automations:create	Create new automations
automations:edit	Edit automation metadata, nodes, edges
automations:delete	Delete automations
automations:execute	Manually trigger and start/stop automations

Template Variables

The template engine supports 60+ variables across multiple categories. Variables are wrapped in {{doubleCurlyBraces}} and resolved at execution time.

For the full variable reference, see:

• User guide: Automation Templates
• Developer guide: Automation Template Engine

Quick Reference

Category	Example	Permission
Channel	{{channelName}}, {{platform}}	None
Bot	{{botName}}, {{commandPrefix}}	None
Time	{{date}}, {{time}}, {{timezone}}	None
User	{{username}}, {{displayName}}	chat:userinfo
Stream	{{streamTitle}}, {{category}}, {{viewerCount}}	events:read
Events	{{followerName}}, {{cheerAmount}}, {{subTier}}	events:read
Spotify	{{songName}}, {{songArtist}}, {{isPlaying}}	spotify:read

Rule Configuration

Rules consist of:

1. Trigger -- The event type that activates the rule
2. Conditions -- Optional filters (minimum amount, specific platform, etc.)
3. Actions -- What to do when triggered (send message, update overlay, etc.)

REST API

The automation CRUD surface lives under /v1/automations; the extension-node surface lives under /v1/automation. See the REST API reference for full details.

Method	Path	Permission
GET	/v1/automations	automations:read
POST	/v1/automations	automations:create
GET	/v1/automations/{id}	automations:read
PATCH	/v1/automations/{id}	automations:edit
DELETE	/v1/automations/{id}	automations:delete
PUT	/v1/automations/{id}/nodes	automations:edit
PUT	/v1/automations/{id}/edges	automations:edit
POST	/v1/automations/{id}/execute	automations:execute
GET	/v1/automation/extension-nodes	automations:read + feature:automation_node_extensions
GET	/v1/automation/webhooks/{install_id}/{automation_id}	automations:read + feature:automation_node_extensions
POST	/v1/automation/webhooks/{extension_id}/{install_id}	X-Webhook-Secret header (no session auth)

There is no automations:history permission: no execution-history surface exists, so the former account permission of that name was removed in ZAF-1094 (it gated nothing).

The GraphQL counterpart mirrors CRUD (automations, automation, createAutomation, updateAutomation, deleteAutomation, saveAutomationNodes, saveAutomationEdges, executeAutomation) plus installedAutomationNodes and automationWebhookUrl.

Extension Node Integration

The automation engine supports extension-provided nodes alongside built-in nodes. Extension nodes use the ext:{short_id} prefix in automation_nodes.node_type.

Dispatch flow

When the executor (crates/lo-automation/src/executor.rs) encounters a node_type starting with ext::

1. Look up extension_installs by short_id
2. Load automation_node_configs for schemas and node type
3. For action nodes: call dispatcher.execute_extension_node(ext_id, inst_id, "action", &node.config, &input), collect output
4. For logic nodes: call the same with "logic", parse the branch, follow that output handle
5. For trigger nodes: skip (triggers are entry points, not walked during execution)

Dispatcher::execute_extension_node is a trait method. The API's implementation in apps/api/src/dispatch.rs (RedisActionDispatcher) issues a synchronous HTTP POST to the Automation Worker's /execute/action or /execute/logic (SystemKey auth), returning the handler output for action nodes and { "branch": … } for logic nodes. It fails closed — an AutomationError::DispatchError — when the endpoint is unconfigured, when the worker reports a handler error, or on any transport/status error. The endpoint is configured under [automation_worker] (url + system_key, LUMIO__AUTOMATION_WORKER__*); an empty system_key disables extension-node dispatch. The Worker resolves the trusted install context (account_id / extension_id / install_config) from its own registry keyed by install_id and ignores those request-body fields.

Automation Worker

The Automation Worker (apps/automation-worker/, library in crates/lo-automation-worker/) is a standalone Actix Web service on port 8091 (AUTOMATION_WORKER__WORKER__PORT) that executes extension node handlers in V8 isolates. Same architecture as the Bot Module Worker.

Endpoint	Method	Timeout	Purpose
/execute/action	POST	5 s (ACTION_TIMEOUT_MS)	Execute an action node handler
/execute/logic	POST	2 s (LOGIC_TIMEOUT_MS)	Execute a logic node handler
/execute/trigger/poll	POST	5 s (TRIGGER_POLL_TIMEOUT_MS)	Poll a trigger handler
/webhooks/\{extension_id\}/\{install_id\}	POST	1 s (TRIGGER_WEBHOOK_TIMEOUT_MS)	Receive external webhook
/health	GET	--	Health check

The timeouts are constants in crates/lo-automation-worker/src/router.rs.

Trigger registration

• Webhook. automation_webhook_registrations stores one webhook_secret per (install, automation). automationWebhookUrl(installId, automationId) — REST: GET /v1/automation/webhooks/\{install_id\}/\{automation_id\} — returns the registration's URL ({public_url}/v1/automation/webhooks/\{extension_id\}/\{install_id\}) and secret. Inbound webhooks hit POST /v1/automation/webhooks/\{extension_id\}/\{install_id\} and are authenticated by an X-Webhook-Secret header compared in constant time against the stored secret — no session auth. The upsert helper (db::automation_nodes::upsert_webhook_registration) has no caller yet, so registrations are not created automatically on enable.
• Polling. poll_interval_seconds is validated to the range 10–300 in three places that must stay in sync: the manifest validator (crates/lo-extensions/src/manifest_validator.rs), the config schema (packages/extension-types/src/config.ts, mirrored in apps/web/src/app/api/schemas/lumio-config/route.ts), and a CHECK constraint on automation_node_configs. PollingEngine in crates/lo-automation-worker/src/polling.rs is currently a stub: start() logs and returns without spawning any interval tasks.

Database tables

Table	Purpose
automation_node_configs	Extension node metadata (schemas, trigger mode, icon, color)
automation_webhook_registrations	Webhook URL registrations with secrets

Feature flag

feature:automation_node_extensions (category: feature) gates store installation and the Builder toolbar section. Free tier: disabled. Pro tier: enabled.