Skip to content

Overview

Chronos schedules your jobs and monitors the ones scheduled elsewhere. You define when a job should run, and Chronos triggers your code with retries, backoff and execution tracking.

Layer Guarantee What it means
Scheduling At most one job per occurrence Each schedule occurrence produces at most one job, no matter how many app instances you run. When Chronos falls behind, it creates one job for the earliest missed occurrence and skips the rest
Delivery At-least-once execution Jobs retry with exponential backoff until they succeed or exhaust max attempts
Schedule ──spawns──▶ Job ──creates──▶ Execution
  • Schedule: A recurring pattern (cron or interval) that spawns jobs on a cadence.
  • Job: A unit of work to execute. Created by a schedule (recurring) or directly via the API (one-off).
  • Execution: A single attempt to run a job. If it fails and retries remain, a new execution is created.

Install the SDK:

Terminal window
pnpm add @chronos.sh/sdk

To create schedules and jobs from the terminal, install the chronos CLI. The worker still needs the SDK.

Create a worker that processes jobs:

import { Chronos } from '@chronos.sh/sdk';
const chronos = new Chronos({ apiKey: process.env.CHRONOS_API_KEY });
chronos.worker.handle('sync-tenant', async (ctx) => {
const tenants = await db.tenants.findMany();
for (const tenant of tenants) {
await syncData(tenant.id, ctx.payload);
}
return { synced: tenants.length };
});
await chronos.worker.start();

Create a schedule via the API, and your worker picks up jobs automatically:

Terminal window
chronos schedules create --name 'Hourly tenant sync' --handler sync-tenant --interval 1h \
--payload '{"full":false}'

Pull (worker): Your process long-polls Chronos for jobs. Best for background processing where you control the compute. This is what the example above shows.

Push (HTTP): Chronos calls your HTTP endpoint when a job is due. Best when you already have a server listening, or want jobs delivered to serverless functions.

Both paths get the same retry guarantees. Choose based on your infrastructure, not reliability needs.

For a job Chronos doesn’t trigger, such as a crontab line, a GitHub Actions workflow, or a Vercel cron route, create a heartbeat monitor. The job pings a URL when it finishes, and Chronos alerts you when it fails or doesn’t ping in time.