---
title: Routines
description: Run a Chat or Tasks agent, or one of your bots, on a schedule, when an email arrives or when a webhook is called, and keep every run with its status, cost and result.
section: computers
order: 20
audience: [user, operator, builder, agent]
sources: [services/nodejs-cloud/lib/routines/index.ts, services/nodejs-cloud/lib/routines/pure.ts, services/nodejs-cloud/lib/routines/sink.ts, services/nodejs-cloud/lib/routines/http.ts, services/nodejs-cloud/lib/routines/mcp.ts, services/nodejs-cloud/components/computers/RoutinesPanel.tsx, services/nodejs-cloud/app/api/routines, services/nodejs-cloud/migrations/0268_routines.sql]
features: [cloud.api-routines]
---

A routine is an instruction an agent carries out without anyone asking. It belongs to an agent: a Chat channel's agent, a
Tasks agent, or one of your [bots](/docs/agents/bots), with or without a computer. It has a name, an instruction, one trigger, an optional place to post the result, and
an on/off switch. Every start is a run, kept with its status until you delete the routine.

Routines of Chat and Tasks agents need the Venom Computers add-on. Find them in the channel's settings (the agent section)
and on the agent's computer page (the details panel).

A bot's routines live in Venom Agents, on the bot's page, and need no Computers add-on unless the bot has a computer of its
own. Only the bot's owner sees or changes them; org admins don't. The rest of this page applies to them too, with the
differences in [Bots](/docs/agents/bots): each run is a quick chat with the bot that can go on for up to 5 turns, a
destructive tool waits for the owner or is approved by the bot's autonomy, and the bot's daily cap ($2 by default)
applies.

## Triggers

**Schedule.** Every day, every weekday, chosen days of the week, a day of the month, or every few weeks, at a time in a time
zone. A 09:00 routine stays at 09:00 across daylight saving. If the cloud was down at the time, the routine runs once for the
latest occurrence that was due and passes over the older ones; it never piles up. Turning a routine back on starts from the next
occurrence. Each occurrence is claimed once, even with several cloud instances sweeping.

**Email.** The routine has an address, `https://<cloud>/api/routines/<id>/inbound`. Point your mail provider's inbound
webhook at it (Postmark, SendGrid Inbound Parse, Mailgun routes or your own forwarder, the same shapes Venom Support takes),
with the routine's secret as `?secret=…`, a bearer token, or the password of HTTP Basic auth. The sender, subject, body and the
names of the attachments become the run's context. The attachments themselves are not opened. A repeat of the same Message-ID is
the same run.

**Webhook.** `POST https://<cloud>/api/routines/<id>/hook` with the secret as `Authorization: Bearer <secret>` or
`x-venom-routine-secret`, or sign the body: `x-venom-signature: sha256=<hex HMAC-SHA256 of the body>`. The JSON payload (up to
1 MiB) becomes the run's context. Send `x-venom-delivery` or `Idempotency-Key` to make a retry the same run.

**When something happens in Venom** (`event`, a bot's routines only). A person added or changed, an interaction logged, a
deal created or moved to another stage, an issue created or changed, a note created or changed, with filters (your own
people, a pipeline and stage, a team or issues assigned to you, a vault and folder). The bot hears only of what its owner can
see, changes wait and go to one run together, and what a bot's own run writes never starts it again. The details are in
[Bots → Events](/docs/agents/bots#events). A Chat or Tasks agent's routine cannot use this trigger.

```sh
curl -X POST 'https://<cloud>/api/routines/<id>/hook' \
  -H 'Authorization: Bearer vrt_…' -H 'Content-Type: application/json' -d '{"event":"deploy","ok":true}'
```

The secret is shown once, when the routine is made or its secret is replaced (**New secret**; the old one stops working at
once). It is stored sealed in the vault (when the deployment has a vault key; without one only the bearer forms work, as the
cloud keeps just a hash). The two addresses are public and answer a wrong secret, an unknown id and a routine of the other
kind the same way. They allow 60 calls a minute per routine. A routine that is off answers 409.

## Where the run goes

| The agent | The run |
|---|---|
| has a computer | a computer run on its browser, with approvals and Needs you as in [Agents on computers](/docs/computers/agents-on-computers); the routine's owner decides them |
| is a Chat agent without a computer | the Chat agent answers a message the routine posts in its channel, with the owner's rights in the other products |
| is a Tasks agent without a computer | an issue created in the Tasks team you pick, delegated to the agent; the run is done when the issue is completed |
| is a bot without a computer | a quick chat with the bot as its owner, driven turn by turn by the cloud; its transcript is linked from the run |

**Post the result to** is the run history only (default), the agent's channel in Chat, or a new Tasks issue in a team. A bot's
routine can instead add the result to a note in its owner's own Notes vault (target `note`, `target_ref` the note's path or
empty for `Bots/<bot>/<routine>`), one dated section per run, and can push its owner when a run finishes (`notify_done`).

## Runs

A run is queued, running, needs you (a person must answer an approval or take over), done, failed or skipped. The detail shows
why a run was skipped or failed, the context it was given, the result, the cost, and a link to the computer.

A run is **skipped**, with the reason, when:

- the previous run is still going and **allow overlap** is off (the default);
- the agent's daily limit is reached (the same limit as its other runs, [Agents on computers](/docs/computers/agents-on-computers));
- the agent is no longer there (the channel was archived, the Tasks agent turned off), or a Chat agent is off in the channel.

A run still open after six hours is closed as failed (a bot's run: six hours with no activity, or a day waiting for its owner). **Run now** makes a run as the trigger would and marks it manual.

## Who can change them

A channel owner or an org admin for a Chat agent, an org admin for a Tasks agent. An agent cannot schedule itself. Members who
can see the channel (or any member, for a Tasks agent) can read routines and runs.

## MCP tools

On the Computers MCP server (`/workspace/mcp/computers`, scopes `computers:read` and `computers:write`):
`computers_routine_list`, `_get`, `_create`, `_update`, `_delete`, `_run_now`, `_rotate_secret`, `computers_routine_run_list` and
`computers_routine_run_get`. The REST twins are under `/api/workspace/routines`.

A bot's routines are on the Agents MCP server instead (`agents_bot_routine_*`, `agents_bot_run_*`, scopes `agents:read` and
`agents:write`), with REST twins under `/api/workspace/agents/routines`; see [Bots](/docs/agents/bots).
