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.
The guarantee
Section titled “The guarantee”| 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 |
How it works
Section titled “How it works”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.
Example worker
Section titled “Example worker”Install the SDK:
pnpm add @chronos.sh/sdknpm install @chronos.sh/sdkyarn add @chronos.sh/sdkTo 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:
chronos schedules create --name 'Hourly tenant sync' --handler sync-tenant --interval 1h \ --payload '{"full":false}'curl -X POST https://api.chronos.sh/v1/schedules \ -H "Authorization: Bearer chrns_your_api_key" \ -H "Content-Type: application/json" \ -d '{ "name": "Hourly tenant sync", "handler": "sync-tenant", "interval": { "value": 1, "unit": "hour" }, "payload": { "full": false } }'await chronos.schedules.create({ name: 'Hourly tenant sync', handler: 'sync-tenant', interval: { value: 1, unit: 'hour' }, payload: { full: false },});client, err := chronos.NewClient(os.Getenv("CHRONOS_API_KEY"))if err != nil { return err}_, err = client.Schedules.Create(context.Background(), chronos.ScheduleCreateParams{ Name: "Hourly tenant sync", Handler: new("sync-tenant"), Interval: &chronos.Interval{Value: 1, Unit: chronos.IntervalUnitHour}, Payload: map[string]any{"full": false},})if err != nil { return err}Two ways to receive jobs
Section titled “Two ways to receive jobs”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.
Watch jobs scheduled elsewhere
Section titled “Watch jobs scheduled elsewhere”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.