Quick Start: Pull (Worker)

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

Prerequisites

• Node.js 20 or later
• @chronos.sh/sdk 0.2.0 or later for the Node.js tabs (installed in step 1)
• Go 1.26 or later for the Go tabs
• A Chronos account (sign up free)
• An API key (create one in the dashboard under Settings → API Keys)

1. Install the SDK

   pnpm

   pnpm add @chronos.sh/sdk

   npm

   npm install @chronos.sh/sdk

   yarn

   yarn add @chronos.sh/sdk

2. Write your handler

   worker.mts

   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. The .mts extension makes tsx run the file as an ES module, which top-level await needs.

3. Start the worker

   pnpm

   CHRONOS_API_KEY=chrns_your_api_key pnpm dlx tsx worker.mts

   npm

   CHRONOS_API_KEY=chrns_your_api_key npx tsx worker.mts

   yarn

   CHRONOS_API_KEY=chrns_your_api_key yarn dlx tsx worker.mts

   The worker connects to Chronos and waits for jobs.

4. Create a job

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

   curl

   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"
     }'

   Node.js

   create-job.mts

   import { Chronos } from '@chronos.sh/sdk';
   
   const chronos = new Chronos({ apiKey: process.env.CHRONOS_API_KEY! });
   
   await chronos.jobs.create({ name: 'My first job', handler: 'hello' });

   Run it with the command from step 3, replacing worker.mts with create-job.mts.

   Go

   create-job.go

   package main
   
   import (
     "context"
     "log"
     "os"
   
     chronos "chronos.sh/go"
   )
   
   func main() {
     client, err := chronos.NewClient(os.Getenv("CHRONOS_API_KEY"))
     if err != nil {
       log.Fatal(err)
     }
     _, err = client.Jobs.Create(context.Background(), chronos.JobCreateParams{
       Name:    "My first job",
       Handler: new("hello"),
     })
     if err != nil {
       log.Fatal(err)
     }
   }

   go mod init hello && go get chronos.sh/go
   CHRONOS_API_KEY=chrns_your_api_key go run create-job.go

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

   Job a8f3e2b1-... running (attempt 1)

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

Create a schedule and your worker picks up jobs automatically:

curl

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" }
  }'

Node.js

create-schedule.mts

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

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

const schedule = await chronos.schedules.create({
  name: 'Hello every 10 minutes',
  handler: 'hello',
  interval: { value: 10, unit: 'minute' },
});
console.log(schedule.id);

Run it with the command from step 3, replacing worker.mts with create-schedule.mts. It prints the schedule id.

Go

create-schedule.go

package main

import (
  "context"
  "fmt"
  "log"
  "os"

  chronos "chronos.sh/go"
)

func main() {
  client, err := chronos.NewClient(os.Getenv("CHRONOS_API_KEY"))
  if err != nil {
    log.Fatal(err)
  }
  schedule, err := client.Schedules.Create(context.Background(), chronos.ScheduleCreateParams{
    Name:     "Hello every 10 minutes",
    Handler:  new("hello"),
    Interval: &chronos.Interval{Value: 10, Unit: chronos.IntervalUnitMinute},
  })
  if err != nil {
    log.Fatal(err)
  }
  fmt.Println(schedule.ID)
}

CHRONOS_API_KEY=chrns_your_api_key go run create-schedule.go

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

curl

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

Node.js

archive-schedule.mts

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

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

await chronos.schedules.archive(process.argv[2]);

Run it like create-schedule.mts, with the schedule id as the last argument.

Go

archive-schedule.go

package main

import (
  "context"
  "log"
  "os"

  chronos "chronos.sh/go"
)

func main() {
  client, err := chronos.NewClient(os.Getenv("CHRONOS_API_KEY"))
  if err != nil {
    log.Fatal(err)
  }
  if _, err := client.Schedules.Archive(context.Background(), os.Args[1]); err != nil {
    log.Fatal(err)
  }
}

CHRONOS_API_KEY=chrns_your_api_key go run archive-schedule.go SCHEDULE_ID

Note

The free tier supports intervals of 10 minutes or longer. See Pricing & Limits for all plan limits.

Next steps

Worker Setup Prod config: graceful shutdown, multiple handlers, error handling

Push Delivery Switch to HTTP push delivery

API Reference Full endpoint documentation