Daemons are long-running background processes that listen for external events and feed them into Sapphire's task scheduler. When an event arrives (new Telegram message, incoming email, etc.), the daemon emits it and the scheduler fires any matching tasks.
Daemon thread (your code)
→ listens for external events (polling, websocket, etc.)
→ calls plugin_loader.emit_daemon_event(source_name, json_payload)
→ scheduler finds tasks matching that source
→ task executes (LLM chat with event data as context)
→ if auto-reply: reply_handler routes response back to source
{
"capabilities": {
"daemon": {
"entry": "daemon.py",
"event_sources": [
{
"name": "my_event",
"label": "My Event",
"description": "When something happens in my service",
"filter_fields": [
{"key": "sender", "label": "Sender Name"},
{"key": "channel", "label": "Channel"}
],
"task_fields": [
{
"key": "account",
"type": "select",
"label": "Account",
"required": true,
"dynamic": "/api/plugin/my-plugin/accounts",
"help": "Which account to monitor"
},
{
"key": "auto_reply",
"type": "boolean",
"label": "Auto-reply",
"default": false
}
]
}
]
}
}
}| Field | Type | Required | Description |
|---|---|---|---|
entry |
string | Yes | Path to daemon module (relative to plugin dir) |
event_sources |
array | No | Event types this daemon can emit |
| Field | Type | Required | Description |
|---|---|---|---|
name |
string | Yes | Unique event identifier (used in emit_daemon_event) |
label |
string | Yes | Human-readable name (shown in Schedule UI) |
description |
string | No | Tooltip/help text |
filter_fields |
array | No | Fields users can filter on when creating tasks |
task_fields |
array | No | Per-task configuration fields shown in Schedule UI |
Filter fields let users narrow which events trigger their task. Each filter is matched against the event payload JSON.
{"key": "username", "label": "Username"}The scheduler ANDs all filters — every filter must match for the task to fire.
Task fields are per-task configuration shown in the Schedule UI when creating a daemon task. They support these types:
| Type | Description | Extra Properties |
|---|---|---|
select |
Dropdown | options (static) or dynamic (API URL for async loading) |
boolean |
Toggle | default |
The dynamic property fetches options from an API endpoint at render time — useful for account lists that change.
Your daemon.py must export start() and stop():
# daemon.py — Minimal daemon skeleton
import logging
import threading
logger = logging.getLogger(__name__)
_thread = None
_stop_event = threading.Event()
_plugin_loader = None
def start(plugin_loader, settings):
"""Called by plugin_loader when the plugin loads."""
global _thread, _plugin_loader
_plugin_loader = plugin_loader
_stop_event.clear()
_thread = threading.Thread(target=_run, daemon=True, name="my-daemon")
_thread.start()
# Register reply handler if you support auto-reply
plugin_loader.register_reply_handler("my-plugin", _reply_handler)
logger.info("[MY-PLUGIN] Daemon started")
def stop():
"""Called by plugin_loader when the plugin unloads."""
global _thread
_stop_event.set()
if _thread and _thread.is_alive():
_thread.join(timeout=5)
_thread = None
logger.info("[MY-PLUGIN] Daemon stopped")| Param | Type | Description |
|---|---|---|
plugin_loader |
PluginLoader |
The plugin loader instance — used for emitting events and reading state |
settings |
dict |
Plugin settings (merged manifest defaults + user overrides) |
Called once when the plugin loads. If the scheduler isn't ready yet (early boot), the call is deferred automatically — you don't need to handle this.
Called when the plugin unloads (toggle off, hot-reload, shutdown). Clean up threads, close connections.
When your daemon detects something interesting, emit an event:
import json
def _run():
while not _stop_event.is_set():
events = poll_my_service()
for event in events:
payload = json.dumps({
"account": "main",
"sender": event.sender,
"channel": event.channel,
"text": event.text,
})
_plugin_loader.emit_daemon_event("my_event", payload)
_stop_event.wait(60) # poll intervalemit_daemon_event(source_name, event_data)
| Param | Type | Description |
|---|---|---|
source_name |
str |
Must match an event_sources[].name from your manifest |
event_data |
str |
JSON string — the event payload passed to matching tasks |
The payload keys should include anything declared in your filter_fields so the scheduler can match filters. Include enough context for the LLM to understand what happened.
If your daemon supports auto-reply (sending the AI's response back to the source platform), register a reply handler in start():
plugin_loader.register_reply_handler("my-plugin", _reply_handler)The handler is called when an event-triggered task completes:
def _reply_handler(task, event_data, response_text):
"""Route LLM response back to the source.
Args:
task: The task dict that was triggered
event_data: The original event payload (dict, already parsed)
response_text: The LLM's response text
"""
channel = event_data.get("channel")
send_to_my_service(channel, response_text)The reply handler name in register_reply_handler must match your plugin name, and the source name must be registered by your plugin — the system uses this to look up the correct handler.
If your daemon manages multiple accounts, use active_daemon_accounts() to only connect accounts that have active tasks:
active = plugin_loader.active_daemon_accounts("my_event")
# Returns: {"account1", "account2"} — only accounts with enabled daemon tasksThis avoids connecting to accounts nobody is listening on.
- Plugin loads →
start(plugin_loader, settings)called - If scheduler not ready → start is deferred until scheduler registers
- Daemon thread runs, polling/listening for events
- Event detected →
emit_daemon_event()→ scheduler fires matching tasks - Task completes with auto-reply → reply handler routes response back
- Plugin unloads →
stop()called → clean up threads/connections
Daemons survive hot-reload — stop() is called before unload, then start() again after reload.
| Plugin | Event Source | What It Does |
|---|---|---|
plugins/telegram/ |
telegram_message |
Telethon client, listens for incoming messages via asyncio event loop |
plugins/discord/ |
discord_message |
Discord.py bot, listens for channel messages |
plugins/email/ |
email_message |
IMAP polling (configurable interval), checks for UNSEEN mail |
plugins/mcp_client/ |
— | MCP server connections (daemon without event sources) |
DAEMON SYSTEM:
- Plugin declares
capabilities.daemonwithentry(module path) andevent_sources(what events it emits) - Module exports
start(plugin_loader, settings)andstop() - Daemon thread listens for external events, calls
plugin_loader.emit_daemon_event(source_name, json_payload) - Scheduler finds tasks matching source, fires them with event data as context
- Reply handlers route LLM responses back to source platform
active_daemon_accounts(source_name)returns set of accounts with active tasks- Filter fields: AND-matched against event payload
- Task fields: per-task config (select with static/dynamic options, boolean)
- Lifecycle: start on load, stop on unload, survives hot-reload