Recurring jobs

A recurring job is a workflow the box starts on a timer. You declare the timer next to the workflow (a cron pattern and the input to send), the box arms it every time it boots, and every tick starts an ordinary run with its own run id, its own steps and its own row under Runs. Recurring jobs in Studio lists every timer the box holds, when each fires next and how its last tick went, so a schedule that stopped firing shows as a red row.

Everything this workspace runs on a timer: two workflow crons, and the two sweeps the box runs for itself.

Run a workflow on a timer

Export a schedules array next to the workflow. The build picks it up, and the box arms it every time it boots:

import { z } from 'zod';

export const schedules = [{ cron: '0 8 * * *', input: { scope: 'daily' } }];

export const inputSchema = z.object({ scope: z.enum(['daily', 'weekly']) });
export const outputSchema = z.object({ sent: z.number() });

export async function dailyDigestWorkflow(input: z.infer<typeof inputSchema>) {
  'use workflow';
  // collect recipients, deliver, return { sent }
}

A few rules that decide what you see on the screen:

• One workflow can export several schedules. Each one gets its own row, named decl:<workflow>#<position> after its position in the array: decl:daily-digest#0, decl:daily-digest#1.
• Ticks fire on schedule whether or not the previous run has finished. If two ticks of the same workflow must not overlap, mark the workflow serial: a tick that arrives while a run is active waits in line.

The complete example, with the durable sleep that paces the sends, is A scheduled digest with a long wait.

Add a schedule at run time

For a schedule that depends on data, or that a workflow decides to add or remove, call stackbone.workflows.schedule from inside a running workflow. The stackbone client is ambient there, so there is nothing to construct:

import { stackbone } from '@stackbone/sdk';

// one dynamic schedule per workflow name; calling it again replaces cadence and input
await stackbone.workflows.schedule('reconcile', { scope: 'daily' }, '0 3 * * *');

// declarative and dynamic alike, each with its `source`
const active = await stackbone.workflows.listSchedules();
// → [{ name: 'daily-digest', cron: '0 8 * * *', input: {…}, source: 'declarative' },
//    { name: 'reconcile',    cron: '0 3 * * *', input: {…}, source: 'dynamic' }]

// removes the dynamic schedule only; a `schedules` export is untouched
await stackbone.workflows.unschedule('reconcile');

A dynamic schedule shows up as dyn:<workflow> under the Dynamic cron family. It survives boots and redeploys like a declared one, and a redeploy never removes it: only unschedule does. Calling any of the three outside a running workflow throws, because the box binds the scheduler when it dispatches the first workflow.

Watch what is armed

Open Recurring jobs under Data in the Studio sidebar. One row per timer the box holds, workflow crons and the box's own sweeps alike. The screen sorts the rows by family, then by name, so the table does not reshuffle under your cursor.

The five families:

The screen re-reads the box every 20 seconds and the rings count down on their own between reads, so a tick shows up within one refresh. Two badges say that something needs you:

• overdue, on a red row: the fire time passed more than 30 seconds ago and no read since has seen the tick. The box stopped firing it.
• not armed, on a dimmed row: the box declared this job but could not arm it. The usual cause is a cron pattern the box cannot parse. Nothing fires until you fix it.

A failed tick keeps its row: failed · 12m ago and the first line of the error, in red, until the next tick overwrites it.

The workflow's own Catalog entry shows the same rows for that one workflow, under Runs on a timer, so you can check a schedule from where you read the workflow's steps and recent runs. All recurring jobs on that block opens the full screen.

One workflow, its recent runs and its one timer, on the same page.

The screen reads one route on the box, GET /api/recurring-jobs, so a self-hosted box answers the same question without a UI. Every timestamp is the box's, and server_time is there so a client can correct its own clock:

{
  "items": [
    {
      "id": "decl:daily-digest#0",
      "family": "decl:",
      "queue": "workflow-cron",
      "cadence": { "kind": "cron", "pattern": "0 8 * * *", "tz": null },
      "next_fire_at": "2026-08-18T08:00:00.000Z",
      "active": true,
      "last_execution": {
        "started_at": "2026-08-17T12:16:10.083Z",
        "finished_at": "2026-08-17T12:16:10.243Z",
        "outcome": "done",
        "error": null
      }
    }
  ],
  "server_time": "2026-08-17T12:17:03.512Z"
}

cadence is { "kind": "cron", "pattern", "tz" } or { "kind": "every", "ms" }. next_fire_at is what the box's scheduler holds, never recomputed from the pattern, and null when nothing is armed. There is no CLI command for schedules today.

Follow every tick

A tick starts a run like any other: it sits under Runs with the chat turns and the runs you started by hand, with a status, a duration and its steps. Open it and the trace shows what the tick did.

The run one tick started: two steps, the durable sleep between the sends, and the output of the first step in the inspector.

The trace lists the steps in order with their timing, and a sleep shows as a wait. Click a step and the inspector prints its input and output. View run logs shows the console.* lines the steps printed, filtered to this run. From a terminal the same data reads as:

stackbone runs list                   # recent runs, ticks included
stackbone runs get <run-id>           # one run: status, steps, result
stackbone logs tail --run <run-id>    # that run's log lines
stackbone runs retry <run-id> --yes   # re-run a failed tick as a fresh run

The run's trigger reads workflow, the same as a run started by hand or by another workflow, so Runs and stackbone runs list do not single ticks out. To see the runs of one scheduled workflow, open its Catalog entry: its Recent runs and its Runs on a timer sit on the same page. retry does not resume the failed run in place; it starts a new run from the tick's input, one more reason to keep every step idempotent.

When things go wrong

Read more

• Background jobs & workflow triggers: a background job is a workflow run, started by name.
• A scheduled digest with a long wait: the full workflow behind the screenshots.
• Serial execution: when two ticks must never overlap.
• Integrations: the trigger links whose polling shows up as Intake link rows.
• Governance: the rest of Studio, from runs to approvals.
• Observability: logging from steps, and the run timeline.