hkuds--nanobot/docs/automations.md

Automations

Automations are agent turns that run later in a linked chat/session. Use them when nanobot should do work without someone actively typing: reminders, recurring checks, nightly summaries, CI follow-ups, local script reports, or webhook-driven events.

Create automations from the chat, channel, or WebUI session where the result should appear. That lets nanobot keep the right session history, workspace, and reply target.

Choose an Automation Type

Type	Starts from	Best for	Created with
Scheduled automation	Time, interval, or cron expression	Recurring reminders, scheduled summaries, one-time future tasks	Ask nanobot in the target session to schedule it with the cron tool
Local trigger	A local nanobot trigger ... command	CI jobs, webhooks, shell scripts, generated reports	/trigger <name> in the target session
Heartbeat	Protected system schedule	Quiet recurring checks that should only report useful results	Edit <workspace>/HEARTBEAT.md

The two user-created automation types are scheduled automations and local triggers. Heartbeat uses the same background service but is system-managed and protected from normal automation edits.

Before You Create One

Keep nanobot gateway running. The gateway owns background delivery for chat apps, WebUI sessions, scheduled automations, local triggers, heartbeat, and Dream jobs.

Use the same workspace and config for the gateway and any process that sends local trigger messages. If you run multiple nanobot instances, pass the matching --config or --workspace option to nanobot trigger.

Create each automation from the target session. An automation without a linked chat/session cannot be enabled or run from the WebUI because nanobot would not know where to deliver the turn.

Scheduled Automations

Scheduled automations are created by the agent's cron tool. In practice, ask nanobot from the target chat or WebUI session:

Every weekday at 9am, check open pull requests and summarize blockers here.

or:

Tomorrow at 4pm, remind me to send the release notes.

The cron tool supports interval schedules, cron expressions, and one-time scheduled tasks. Cron expressions can include an IANA timezone such as America/Vancouver; otherwise nanobot uses the runtime default timezone.

Scheduled automations normally deliver the result back to the session where they were created. Use them for work that should run on a predictable schedule and report each run.

For background checks that should stay quiet unless there is something useful to report, use heartbeat instead of a user-created scheduled automation.

Local Triggers

Local triggers let a local script or external service send a message into a specific nanobot session later.

Create the trigger from the chat or WebUI session where future messages should arrive:

/trigger PR review

nanobot replies with a trigger ID and a command shaped like:

nanobot trigger trg_8K4P2Q9X "Review PR #4502"

Replace the quoted text with the message nanobot should receive. For generated or longer content, pipe stdin:

generate-report | nanobot trigger trg_8K4P2Q9X

For multiple instances, use the same config or workspace selector as the gateway:

nanobot trigger --config ./bot-a/config.json trg_8K4P2Q9X "Nightly report"
nanobot trigger --workspace ./bot-a/workspace trg_8K4P2Q9X "Nightly report"

nanobot does not provide a built-in public webhook receiver for local triggers. If GitHub, CI, or another external system should wake nanobot, run your own small webhook service and have it call nanobot trigger after it builds the final message.

Heartbeat

Heartbeat is for recurring workspace checks that should usually stay quiet. It reads <workspace>/HEARTBEAT.md, executes active tasks, and sends only useful or actionable results to the most recently active chat target.

Use heartbeat for checks such as "watch this repo for important failures" or "periodically inspect this workspace and only tell me when action is needed." Use a scheduled automation instead when every run should produce a visible reminder or report.

Heartbeat is enabled by default when nanobot gateway starts. Configure it in configuration.md#gateway-heartbeat.

Manage Automations

Use the WebUI Automations view to:

• filter by all, active, paused, needs-attention, or system jobs;
• search by task name, message, trigger command, linked chat, schedule, or status;
• sort by next run, last run, updated time, or name;
• run scheduled automations now;
• pause or resume, rename, or delete user-created automations;
• copy the CLI command for local triggers;
• inspect protected system automations without changing them.

Local triggers do not have a WebUI "Run now" action because each run needs a message. Copy the nanobot trigger ... command from the WebUI and replace "message" with the content that should be delivered.

Delivery and Reliability

Automation delivery is workspace-local. Scheduled jobs and local trigger deliveries use the same workspace as the gateway.

Local trigger messages are written to a durable queue. If the gateway is not running yet, the message waits in that workspace. If the linked session is already running a turn, the trigger waits until the session becomes idle instead of being injected into the active turn.

The local trigger queue is at-least-once, not exactly-once. If the gateway exits after claiming a delivery but before the linked turn completes, the next gateway start requeues that delivery. External scripts should make repeated trigger messages safe. If the delivery reaches the agent and the turn fails, the delivery is marked failed instead of retrying forever.

Each local trigger delivery writes an audit record under <workspace>/triggers/runs. Run one gateway consumer per workspace; the local queue is not a distributed multi-consumer queue.

Common Patterns

For a nightly report, ask from the target session:

Every night at 9pm, review today's workspace changes and summarize anything I should handle tomorrow.

For a CI follow-up, create a trigger once:

/trigger CI follow-up

Then have your CI or webhook adapter call:

nanobot trigger <trigger-id> "Build failed on main. Inspect the logs and suggest the next fix."

For a local report script:

generate-report | nanobot trigger <trigger-id>

Troubleshooting

If an automation does not run, check that nanobot gateway is running, the automation is enabled, and it was created from a linked chat/session.

If a local trigger waits forever, confirm the command uses the same workspace or config as the gateway.

If a trigger message appears twice after a restart, treat it as expected at-least-once delivery and make the external message idempotent.

If you need to edit, pause, resume, rename, delete, or inspect automations, use the WebUI Automations view.

Related Docs

• webui.md#automations for the browser management view
• chat-commands.md#local-triggers for /trigger
• cli-reference.md#local-triggers for nanobot trigger
• configuration.md#gateway-heartbeat for heartbeat settings
• guides/long-running-ai-agent.md for long-running agent work