Manual runs exit after one execution. Schedules, watchers, network listeners, hotkeys, startup events, and serial readers must remain alive waiting for input, so they require a long-running background runner.
The background runner is the part of BaudBound that keeps listening after no script is actively running. Opening the desktop window does not automatically prove that this listener is active. Check the status shown at the top of the desktop application. If it says Runner stopped, open Service and choose Start. Enable Start background runner on launch in Settings when listeners should start every time the desktop application opens.
A listener waits for one kind of event. A hotkey listener waits for keyboard input. A schedule listener waits for a timer. A webhook listener waits for an HTTP request. When the expected event arrives, the listener starts the connected script path.
| Method | Use | Lifetime |
|---|---|---|
| Desktop Service Start | Normal interactive desktop use | Until stopped or desktop application quits |
baudbound serve |
Foreground testing and diagnostics | Until Ctrl+C, stop IPC, or process failure |
| OS service manager | Headless unattended operation | Supervised according to operator configuration |
Do not start more than one method against the same runner home.
A trigger registers only when:
config.toml.The service reports skipped and failed registrations instead of silently claiming they are active.
Installed script import, update, enablement, approval, revocation, and removal create durable state changes and request an immediate trigger reload through SQLite. The running service also checks for changes at runner.trigger_reload_seconds and can receive an authenticated loopback IPC reload request.
Reload rebuilds script registrations. Configuration fields are loaded into service options at startup. Use Service Reload or restart the external process after changing listener addresses, family switches, targets, or serial mappings.
baudbound script run SCRIPT, or explicit trigger dispatch.schedules_enabled = true, enabled/current script, positive interval of at least one millisecond.For a first test, use a one-minute schedule and Log action from Tutorials.
file_watch_enabled = true. Static existing regular file or directory accessible to the account running BaudBound.path, original watched path, and normalized event (created, modified, deleted, renamed).Applications can produce several OS events for one save. Workflows should be idempotent or tolerate duplicates where practical.
process_watch_enabled = true. Match mode supported on target.startup_enabled = true. Enabled/current script.hotkeys_enabled = true, Windows Desktop target, active signed-in desktop session, enabled and current script, and an approved package.A, F8, K+L, F1+T, Ctrl+Shift+B, Numpad7, and MediaPlayPause.A does not fire while another key is held, and K+L fires when the second required key is pressed regardless of which one was pressed first.key and event timestamp.The supported catalog includes letters, digits, F1 through F24, navigation and editing keys, punctuation, numpad keys, and standard browser, volume, media, and launch keys that Windows identifies consistently. Firmware-only keys such as most Fn keys are unavailable to normal applications. Windows also reserves secure-attention input such as Ctrl+Alt+Delete, so it cannot be used as a BaudBound hotkey.
The desktop background runner installs the native listener automatically and updates it when eligible scripts change. The CLI baudbound hotkey dispatch and baudbound hotkey listen --stdin commands exercise the same dispatch path using explicit test input. They do not replace the native desktop listener.
serial_enabled = true. Logical device ID mapped to a valid port/protocol. Optional identity checks pass.CR, LF, and CRLF. Raw mode exposes operating system chunks without promising complete messages.auto_reconnect retries after disconnect. Auto rebind can save one unambiguous changed port when identity requirements pass. Input and output immediately use the new shared connection.Use Configuration and Serial Devices for hardware setup.
webhooks_enabled = true. Configured bind/port available. Network-server policy and approval allow registration. Runner-owned token authentication is enabled by default./events/HOOK_NAME route.X-BaudBound-Token. BaudBound removes this header before exposing request headers to the graph.websockets_enabled = true. Bind/port available. Network-server policy and approval allow registration. Runner-owned token authentication is enabled by default./.X-BaudBound-Token. Browser clients provide bbtoken.TOKEN as a WebSocket subprotocol and must use an allowed Origin.Tokens are generated by the runner and are never exported in a .bbs package. Approval displays newly created tokens once, then only their hashes remain in storage. Existing trigger tokens survive package updates when the script ID, node ID, and trigger type remain unchanged. Webhook and WebSocket setup is documented in Webhooks, WebSockets, and Network Access.
In the desktop application, open Monitor and choose Start monitoring before sending real input. The monitor shows the exact registered trigger type, received payload, and whether the runner accepted the event for execution. It is useful for serial, webhook, WebSocket, file, process, schedule, hotkey, and startup testing. Captured events remain in memory only.
Show registrations:
baudbound script triggers
Inspect service preflight without opening listeners:
baudbound serve --dry-run
Use JSON for automation:
baudbound serve --dry-run --json
Dispatch one known trigger with a test payload without waiting for its external source:
baudbound script dispatch-trigger SCRIPT TRIGGER --payload-json '{"test":true}'
Replace SCRIPT and TRIGGER with values shown by inspection. Shell quoting differs. PowerShell accepts the single-quoted JSON example as one argument.
The JSON object is test input for that one run. The selected trigger exposes its fields as output variables. Read Supplying trigger test data before using this command.
baudbound serve --once --run-schedules-immediately is useful for controlled schedule testing: schedules are marked due immediately and the service exits after the first due batch.
In a foreground terminal, press Ctrl+C once and wait for final service status. In the desktop application, choose Stop or Quit BaudBound. For an external service, use its manager's stop command.
Forced termination can interrupt active actions and leave clients without a response. If shutdown does not complete, preserve logs and status before killing the process.