Skip to main content
Vendo fires automations on a schedule, in response to a host event, or from a verified external webhook. Zero config: the block mounts unless you pass automations: false, and host events work immediately. vendo.emit(...) runs the matching automations in your own process, with no key and no cron. Schedules are the one trigger that needs a firing authority, and you pick one: automations.start() in a long-lived process (it polls every 60s by default), or an external cron against the tick route below.

​
Schedules

Long-lived hosts can call automations.start(). Serverless hosts schedule:
Schedules support exactly one of a five-field cron, a duration such as 15m, or a one-shot UTC timestamp. Cron evaluates in UTC. If the host misses a window, the next tick fires once and never back-fills. The bearer is the host-configured VENDO_TICK_SECRET. Point any external cron at it (Vercel cron, a GitHub Actions schedule, or crontab) as often as you like: firing is idempotent within a cron window, so a double-hit never double-runs anything.

​
Machine app schedules

The same tick drives graduated apps’ machines. An app whose box ships a vendo.json manifest declaring schedules:
gets each due target fired as POST /fn/<name> on its machine: the tick wakes the machine, posts the fn as the app owner’s away execution, records last-fired state, and the machine goes back to sleep on the normal idle policy. Due-ness is computed from store-cached state, so a tick never wakes a machine with nothing due. The response’s additive schedules field reports what fired. The host learns a box’s schedules by reading vendo.json over the machine door whenever the machine is awake at tick time (and once, on the first tick after graduation). A manifest edited while the machine sleeps is picked up the next time it is awake. vendo doctor reports machine-bearing apps, whether a schedule caller is configured, and last-fired times.

​
Host events

Emit from the host code path that owns the event:
This runs enabled automations for that principal whose host-event name matches.

​
External deliveries

Mount POST /webhooks/:source. Connector sources use their own signature scheme. Self-minted sources sign HMAC-SHA256 over id.timestamp.rawBody, place signature, timestamp, and delivery id in headers, and accept only a five-minute clock window. Vendo rejects unverified deliveries before principal resolution or dispatch. Delivery ids are deduplicated, so at-least-once retries do not double-run an automation. Secrets never travel in the URL.

​
Stopping a run

Cancel an in-flight automation run when a schedule fires against stale state, an agent is looping on a bad plan, or a user asks to abort. Post to the run under its owning principal:
The engine signals cancellation cooperatively: the current step finishes, outstanding tool calls are drained, and the run transitions to a cancelled terminal state. Parked approvals attached to the run are dropped rather than resumed. Stopping a run that has already reached a terminal state is a no-op and returns 200. Cancellation is idempotent and audit-logged. The engine uses the store’s atomic compare-and-set primitive on the run record, so concurrent stop requests and scheduler ticks cannot race a run into a resurrected state.