# Wake-ups

How you decide what starts an agent, how the wake reaches it, and how the agent works through its queue. What wake-ups are and what they cost is on [Services](/services).

## Before you start

Every agent has wake-ups, with or without an account. Rules, schedules, settings and the webhook are set by the owner or an admin. An agent cannot change its own.

## Wake on an event

```text
When email from anna@example.com arrives, wake the assistant to read and answer it.
```

The client calls `stack_set_wake_rule`. From code or the terminal:

```typescript
await stack.wakes.createRule({
  name: 'Mail from Anna',
  source: 'email',
  filters: { from: ['anna@example.com'] },
  task: 'Read and answer the new email.',
}, 'agt_123');
```

```bash
npx @getstackrun/cli wake rule-add agt_123 --name "Mail from Anna" --source email \
  --from anna@example.com --task "Read and answer the new email."
```

- Mail, texts, Telegram messages, voicemail, payments and post need a rule before they wake anyone.
- A ringing call, the end of a call, the start and the end of a meeting, a schedule, a calendar event, a hand-off from another of your agents and a decision the agent waited for wake it without a rule.
- filters.from takes addresses, @domain for a whole domain, phone numbers, or a Telegram sender as telegram:\<username>. filters.min_amount_cents is for payments.
- task is your own text. Nothing the sender wrote is ever part of it. Without one, the agent gets a fixed line such as "New email."
- Leave the agent id out to set a rule for every agent of the account.

## Wake on a schedule

```typescript
await stack.wakes.createSchedule('agt_123', {
  name: 'Morning',
  cron: '0 9 * * 1-5',
  time_zone: 'Europe/Stockholm',
  task: 'Check the open invoices.',
});
```

The tool is `stack_set_wake_schedule`. `cron` takes five fields, or `@hourly`, `@daily`, `@weekly` or `@monthly`. A schedule fires at most every 5 minutes.

## How the wake reaches the agent

A wake is tried in this order, which you can change with `delivery`:

- A notification on the agent's open MCP session.
- A signed POST to the agent's webhook, when one is set.
- The agent's queue, always. A wake is never lost because nothing was listening.

Set a webhook, and STACK returns its signing secret once:

```bash
npx @getstackrun/cli wake settings set agt_123 --webhook-url https://agent.example.com/wake
```

Check each wake your server receives before acting on it:

```typescript
import { verifyWakeWebhook } from '@getstackrun/sdk';

const result = verifyWakeWebhook({ headers: request.headers, body: rawBody, secret });
if (!result.ok) return reply.status(400).send(result.reason);
// result.wake.wake_id, result.wake.source, result.wake.task
```

- The address must be https on a public host, with no query and no fragment.
- A failed delivery is retried up to 8 times, then the queue alone holds the wake.
- wake rotate-secret gives a new secret. The old one keeps working for 24 hours.
- wake test-webhook sends a test wake to the address.

The secret is shown once and cannot be read back. It is never returned to a chat sign-in: set the webhook from the terminal or with an API key.

## Work through the queue

```typescript
const queue = await stack.wakes.list('agt_123', { status: 'open' }, { passportToken });
for (const wake of queue.wakes) {
  // do the task, then:
  await stack.wakes.acknowledge('agt_123', wake.id, { passportToken });
}
```

The tools are `stack_list_wakes`, `stack_get_wake` and `stack_acknowledge_wake`. `open` is the queue, oldest first. A delivered wake nobody acknowledges expires after 30 days.

## Quiet hours and limits

```bash
npx @getstackrun/cli wake settings set agt_123 --time-zone Europe/Stockholm \
  --quiet 22:00-07:00 --quiet-mode hold --rate-limit 30 --rate-window 3600
```

- Quiet hours hold wakes until they end, or drop them, as quiet_mode says.
- There is no limit on wakes unless you set one. Past your limit, events are dropped and counted.
- There is no limit on the number of rules or schedules.
- Events that arrive close together become one wake that lists them all.
- --disable switches wake-ups off for the agent.

## What counts as an action

Each wake delivered is one action. Setting rules, schedules and settings, reading the queue and acknowledging are free. A wake that is refused is not charged.

## When it is refused

- 400 WAKE_WEBHOOK_ADDRESS_REFUSED - the webhook address is not https on a public host, or carries a query or a fragment.
- 400 VALIDATION_ERROR - a cron line, time zone or clock time is wrong.
- 403 on a settings, rule or schedule call - an agent called it. These are the owner's.
- With controls on, each wake of an agent with an account is asked of your policy or your own server as wake.deliver. A refused wake is not delivered.

## Reference

Every field is on [Wake-ups, Calendar and Meetings](/docs/api/wake-ups). Every tool is in the [tool reference](/docs/mcp-tools).
