Skip to content
chronos

Quick Start: Pull (Worker)

Your worker long-polls Chronos for jobs, runs your handler, and reports the result. You control the compute.

Prerequisites

Section titled “Prerequisites”
  • Node.js 20 or later
  • A Chronos account (sign up free)
  • An API key (create one in the dashboard under Settings → API Keys)

  1. Install the SDK

    Terminal window
    pnpm add @chronos.sh/sdk

  2. Write your handler

    worker.ts
    import { Chronos } from '@chronos.sh/sdk';
    

    const chronos = new Chronos({
      apiKey: process.env.CHRONOS_API_KEY!,
    });
    

    chronos.worker.handle('hello', async (ctx) => {
      console.log(`Job ${ctx.jobId} running (attempt ${ctx.attempt})`);
      return { ok: true };
    });
    

    await chronos.worker.start();

    The handler name "hello" is the routing key. Chronos uses it to match jobs to the right function.

  3. Start the worker

    Terminal window
    CHRONOS_API_KEY=chrns_your_api_key pnpm dlx tsx worker.ts

    The worker connects to Chronos and waits for jobs.

  4. Create a job

    In a second terminal, create a one-off job:

    Terminal window
    curl -X POST https://api.chronos.sh/v1/jobs \
      -H "Authorization: Bearer chrns_your_api_key" \
      -H "Content-Type: application/json" \
      -d '{
        "name": "My first job",
        "handler": "hello"
      }'

    Your running worker claims the job and runs the handler. You should see:

    Job a8f3e2b1-... running (attempt 1)

What just happened

Section titled “What just happened”
  1. You created a one-off job via the API
  2. Your worker long-polled Chronos and claimed it
  3. The handler ran and returned a result
  4. Chronos recorded the execution as completed

If the handler had thrown an error, Chronos would have retried up to 3 times with exponential backoff.

Make it recurring

Section titled “Make it recurring”

Create a schedule and your worker picks up jobs automatically:

Terminal window
curl -X POST https://api.chronos.sh/v1/schedules \
  -H "Authorization: Bearer chrns_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Hello every 10 minutes",
    "handler": "hello",
    "interval": { "value": 10, "unit": "minute" }
  }'

Your running worker now receives a new job every 10 minutes. To stop it, archive the schedule:

Terminal window
curl -X POST https://api.chronos.sh/v1/schedules/SCHEDULE_ID/archive \
  -H "Authorization: Bearer chrns_your_api_key"

Next steps

Section titled “Next steps”
Worker Setup Prod config: graceful shutdown, multiple handlers, error handling
Push Delivery Switch to HTTP push delivery
API Reference Full endpoint documentation