Quickstart

This guide walks you through defining your first task, registering it on a worker, and triggering it from your application.

Prerequisites

You need a running Hatchet instance and an API token. The fastest way is to sign up on Hatchet Cloud — or run Hatchet locally:

curl -fsSL https://install.hatchet.run/install.sh | bash
hatchet server start

Once running, open the dashboard, navigate to Settings → API Tokens, and create a new token.

Step 1 — Install the SDK

Python
TypeScript
Go

pip install hatchet-sdk

npm install @hatchet-dev/typescript-sdk

go get github.com/hatchet-dev/hatchet/sdks/go

Step 2 — Set your token

Set the HATCHET_CLIENT_TOKEN environment variable to the API token you created:

export HATCHET_CLIENT_TOKEN="<your-token-here>"

For a self-hosted instance, also set the server address:

export HATCHET_CLIENT_HOST_PORT="localhost:7077"

Step 3 — Define a task

Python
TypeScript
Go

workflows/first_task.py

from pydantic import BaseModel
from hatchet_sdk import Context, Hatchet

hatchet = Hatchet()

class SimpleInput(BaseModel):
    message: str

class SimpleOutput(BaseModel):
    transformed_message: str

@hatchet.task(name="first-task", input_validator=SimpleInput)
def first_task(input: SimpleInput, ctx: Context) -> SimpleOutput:
    print("first-task task called")
    return SimpleOutput(transformed_message=input.message.lower())

workflows/first-task.ts

import HatchetClient from '@hatchet-dev/typescript-sdk';

const hatchet = await HatchetClient.init();

type SimpleInput = {
  Message: string;
};

type SimpleOutput = {
  TransformedMessage: string;
};

export const firstTask = hatchet.task({
  name: 'first-task',
  fn: (input: SimpleInput, ctx): SimpleOutput => {
    return {
      TransformedMessage: input.Message.toLowerCase(),
    };
  },
});

main.go

package main

import (
    "log"
    hatchet "github.com/hatchet-dev/hatchet/sdks/go"
    "github.com/hatchet-dev/hatchet/pkg/cmdutils"
)

type SimpleInput struct {
    Message string `json:"message"`
}

type SimpleOutput struct {
    Result string `json:"result"`
}

func main() {
    client, err := hatchet.NewClient()
    if err != nil {
        log.Fatalf("failed to create hatchet client: %v", err)
    }

    task := client.NewStandaloneTask("process-message",
        func(ctx hatchet.Context, input SimpleInput) (SimpleOutput, error) {
            return SimpleOutput{
                Result: "Processed: " + input.Message,
            }, nil
        },
    )

    worker, err := client.NewWorker("simple-worker", hatchet.WithWorkflows(task))
    if err != nil {
        log.Fatalf("failed to create worker: %v", err)
    }

    interruptCtx, cancel := cmdutils.NewInterruptContext()
    defer cancel()

    if err = worker.StartBlocking(interruptCtx); err != nil {
        log.Fatalf("failed to start worker: %v", err)
    }
}

Step 4 — Start a worker

Python
TypeScript
Go

worker.py

from hatchet_sdk import Hatchet
from workflows.first_task import first_task

hatchet = Hatchet()

def main():
    worker = hatchet.worker(
        "first-worker",
        slots=10,
        workflows=[first_task],
    )
    worker.start()

if __name__ == "__main__":
    main()

Run the worker in a terminal:

python worker.py

worker.ts

import HatchetClient from '@hatchet-dev/typescript-sdk';
import { firstTask } from './workflows/first-task';

const hatchet = await HatchetClient.init();

async function main() {
  const worker = await hatchet.worker('first-worker', {
    workflows: [firstTask],
    slots: 10,
  });

  await worker.start();
}

main();

Run the worker:

npx ts-node worker.ts

The Go worker was included in the task definition above. Run:

go run main.go

Step 5 — Trigger the task

In a separate terminal (or from your application), trigger the task:

Python
TypeScript
Go

run.py

import asyncio
from workflows.first_task import SimpleInput, first_task

async def main():
    result = await first_task.aio_run(SimpleInput(message="Hello World!"))
    print("Transformed message:", result.transformed_message)

asyncio.run(main())

run.ts

import { firstTask } from './workflows/first-task';

async function main() {
  const res = await firstTask.run({
    Message: 'Hello World!',
  });

  console.log('Transformed message:', res.TransformedMessage);
}

main().catch(console.error).finally(() => process.exit(0));

trigger/main.go

package main

import (
    "context"
    "fmt"
    "log"
    hatchet "github.com/hatchet-dev/hatchet/sdks/go"
)

func main() {
    client, err := hatchet.NewClient()
    if err != nil {
        log.Fatalf("failed to create hatchet client: %v", err)
    }

    task := client.NewStandaloneTask("process-message",
        func(ctx hatchet.Context, input SimpleInput) (SimpleOutput, error) {
            return SimpleOutput{}, nil // worker handles execution
        },
    )

    result, err := task.Run(context.Background(), SimpleInput{Message: "Hello, World!"})
    if err != nil {
        log.Fatalf("task failed: %v", err)
    }

    var output SimpleOutput
    if err = result.Into(&output); err != nil {
        log.Fatalf("failed to read output: %v", err)
    }

    fmt.Println("Result:", output.Result)
}

You should see the task execute in your worker terminal, and the result printed in your trigger terminal.

What’s next

Your first task

Deep dive into task options: retries, timeouts, concurrency, and more

DAG workflows

Chain tasks together into multi-step workflows with dependencies

Flow control

Rate limits and per-user concurrency to protect your system

Dashboard

Monitor and debug your tasks in the real-time web UI

Get Started

Running Tasks

Flow Control

Workers

Observability

Self-Hosting

Prerequisites

Step 1 — Install the SDK

Step 2 — Set your token

Step 3 — Define a task

Step 4 — Start a worker

Step 5 — Trigger the task

What’s next

Your first task

DAG workflows

Flow control

Dashboard

Build docs developers (and LLMs) love

Get Started

Running Tasks

Flow Control

Workers

Observability

Self-Hosting

​Prerequisites

​Step 1 — Install the SDK

​Step 2 — Set your token

​Step 3 — Define a task

​Step 4 — Start a worker

​Step 5 — Trigger the task

​What’s next

Your first task

DAG workflows

Flow control

Dashboard

Build docs developers (and LLMs) love

Prerequisites

Step 1 — Install the SDK

Step 2 — Set your token

Step 3 — Define a task

Step 4 — Start a worker

Step 5 — Trigger the task

What’s next