Hatchet

https://docs.hatchet.run
Admin
Hatchet is a modern orchestration platform for building low-latency, high-throughput data ingestion...
Tokens:484,945
Snippets:4,113
Trust Score:8.3
Update:19 hours ago
Show doc for...
Tokens:
Raw
### Run interactive quickstart

Source: https://docs.hatchet.run/llms/reference/cli/quickstarts.md

Run `hatchet quickstart` with no flags to start an interactive setup that prompts for use case, language, package manager, name, and directory.

```sh
hatchet quickstart
```

--------------------------------

### hatchet quickstart reference

Source: https://docs.hatchet.run/llms/reference/cli/quickstarts.md

Full CLI reference for `hatchet quickstart`, including description, usage, examples, and flags. Shows supported package managers and default values.

```txt
Generate a quickstart Hatchet worker project with boilerplate code in your language of choice.

Supports multiple package managers:
  Python: poetry, uv, pip
  TypeScript: npm, pnpm, yarn, bun
  Go: go modules

Use-case templates are selected with --use-case. The default, simple, is a
minimal worker with one workflow. Other use cases, such as scheduled, may
support a subset of languages.

Usage:
  hatchet quickstart [flags]

Examples:
  # Generate a project interactively (prompts for use case, language, package manager, name, and directory)
  hatchet quickstart

  # Generate a Python project with Poetry
  hatchet quickstart --language python --package-manager poetry

  # Generate a TypeScript project with pnpm
  hatchet quickstart --language typescript --package-manager pnpm --project-name my-worker

  # Generate the scheduled use case in Go
  hatchet quickstart --use-case scheduled --language go

  # Generate a Python project with uv using short flags
  hatchet quickstart -l python -m uv -p my-worker -d ./my-worker

Flags:
  -d, --directory string         Directory to create the project in (default: ./{project-name})
  -h, --help                     help for quickstart
  -l, --language string          Programming language (python, typescript, go)
  -m, --package-manager string   Package manager (poetry, uv, pip for Python; npm, pnpm, yarn, bun for TypeScript)
  -p, --project-name string      Name of the project (default: hatchet-worker)
  -u, --use-case string          Use case template (default: simple)
```

--------------------------------

### Start the TypeScript worker for the support agent example

Source: https://docs.hatchet.run/llms/cookbooks/hatchet-claude-agent-sdk-trusted-env.md

Run this command in a terminal to start the worker for the TypeScript support agent example. The worker must be running before the agent calls any tools.

```bash
cd sdks/typescript
pnpm exec tsx -r tsconfig-paths/register src/v1/examples/support_agent_tools/worker.ts
```

--------------------------------

### hatchet server start command reference

Source: https://docs.hatchet.run/llms/reference/cli/running-hatchet-locally.md

Full command reference for 'hatchet server start', including usage, examples, and flags. Shows how to customize ports, project name, profile, and disable authentication.

```txt
Start a local Hatchet server environment using Docker containers. This command will start both a PostgreSQL database and a Hatchet server instance, automatically creating a local profile for easy access.

Usage:
  hatchet server start [flags]

Examples:
  # Start server with default settings (port 8888)
  hatchet server start

  # Start server with custom dashboard port
  hatchet server start --dashboard-port 9000

  # Start server with custom ports and project name
  hatchet server start --dashboard-port 9000 --grpc-port 8077 --project-name my-hatchet

  # Start server with custom profile name
  hatchet server start --profile my-local

  # Start server with authentication disabled (local development only)
  hatchet server start --disable-auth

Flags:
      --disable-auth          Disable authentication by running the hatchet-lite-dev image (local development only)
  -d, --dashboard-port int    Port for the Hatchet dashboard (default: auto-detect starting at 8888)
  -g, --grpc-port int         Port for the Hatchet gRPC server (default: auto-detect starting at 7077)
  -h, --help                  help for start
  -n, --profile string        Name for the local profile (default: local) (default "local")
  -p, --project-name string   Docker project name for containers (default: hatchet-cli)

Global Flags:
  -v, --version   The version of the hatchet cli.
```

--------------------------------

### Install MCP server with profile grant

Source: https://docs.hatchet.run/llms/reference/cli/mcp.md

Applies grants during installation, exactly like `hatchet mcp auth --grant`. This example grants the `local` profile while installing for `claude-code`.

```sh
hatchet mcp install --target claude-code --grant local
```

--------------------------------

### Run the TypeScript agent for the support agent example

Source: https://docs.hatchet.run/llms/cookbooks/hatchet-claude-agent-sdk-trusted-env.md

Run this command in a second terminal to start the agent for the TypeScript support agent example. The worker must be running before the agent calls any tools.

```bash
cd sdks/typescript
pnpm exec tsx -r tsconfig-paths/register src/v1/examples/support_agent_tools/agent-claude.ts
```

--------------------------------

### TypeScript test command for welcome email example

Source: https://docs.hatchet.run/llms/cookbooks/welcome-email.md

Runs the end-to-end tests for the welcome email example using pnpm.

```bash
pnpm run test:e2e -- --testPathPattern=welcome_email
```

--------------------------------

### Start Hatchet with docker compose up

Source: https://docs.hatchet.run/llms/self-hosting/docker-compose.md

Command to start all Hatchet services defined in docker-compose.yml. Run from the repository root.

```bash
docker compose up
```

--------------------------------

### Install Hatchet SDK extra for OpenAI

Source: https://docs.hatchet.run/cookbooks/hatchet-and-mcp

Install the Hatchet SDK with the OpenAI provider extra using pip.

```bash
pip install "hatchet-sdk[openai]"
```

--------------------------------

### Install OpenAI Agents SDK (TypeScript)

Source: https://docs.hatchet.run/llms/cookbooks/hatchet-and-mcp.md

Install the OpenAI agents SDK for TypeScript.

```bash
npm install @openai/agents
```

--------------------------------

### Install Claude Agent SDK (TypeScript)

Source: https://docs.hatchet.run/llms/cookbooks/hatchet-and-mcp.md

Install the Claude agent SDK for TypeScript.

```bash
npm install @anthropic-ai/claude-agent-sdk
```

--------------------------------

### Install Hatchet SDK extra for Claude

Source: https://docs.hatchet.run/cookbooks/hatchet-and-mcp

Install the Hatchet SDK with the Claude provider extra using pip.

```bash
pip install "hatchet-sdk[claude]"
```

--------------------------------

### Start LocalStack using docker-compose

Source: https://docs.hatchet.run/cookbooks/workflow-aws-s3

Starts the LocalStack container (localstack/localstack:4.14) using the provided docker-compose.yaml. This is required for running the worker locally.

```bash
docker compose -f examples/aws/s3/docker-compose.yml up -d --wait
```

--------------------------------

### Python: Wire tools into OpenAI Agent and run

Source: https://docs.hatchet.run/llms/cookbooks/hatchet-openai-agents-sdk-trusted-env.md

Creates three tools and passes them to an OpenAI Agent via the tools array, then runs the agent once with a support query and prints the final output. Requires the tools module from examples.support_agent_tools.tools.

```python
import asyncio

from agents import Agent, Runner
from examples.support_agent_tools.tools import (
    create_lookup_customer_tool_openai,
    create_check_order_status_tool_openai,
    create_ticket_tool_openai,
)


async def main() -> None:
    lookup_customer_tool = create_lookup_customer_tool_openai()
    check_order_status_tool = create_check_order_status_tool_openai()
    ticket_tool = create_ticket_tool_openai()

    agent = Agent(
        name="support-agent",
        tools=[lookup_customer_tool, check_order_status_tool, ticket_tool],
    )

    result = await Runner.run(
        agent,
        "Customer C-100 says order ORD-9987 has not arrived. "
        "Look up the customer, check the order status, and create a "
        "support ticket if the order has a known issue or delayed delivery. "
        'If you create a ticket, use priority "high", subject '
        '"Delayed order ORD-9987", and a body that summarizes the known '
        "carrier delay. Then summarize what happened.",
    )
    print(result.final_output)


if __name__ == "__main__":
    asyncio.run(main())
```

--------------------------------

### Get a workflow by ID (example with workflow-123)

Source: https://docs.hatchet.run/llms/reference/ruby/feature-clients/workflows.md

Retrieves a workflow by its ID. This example uses 'workflow-123' as the ID. Raises HatchetSdkRest::ApiError on failure.

```ruby
workflow = hatchet.workflows.get("workflow-123")
```

--------------------------------

### Get a worker by ID (with example ID)

Source: https://docs.hatchet.run/llms/reference/ruby/feature-clients/workers.md

Retrieves a worker using a specific example ID 'worker-123'. The worker_id parameter is required. Raises HatchetSdkRest::ApiError if the API request fails.

```ruby
worker = hatchet.workers.get("worker-123")
```

--------------------------------

### Run agent example (Python)

Source: https://docs.hatchet.run/cookbooks/hatchet-and-mcp

Commands to run the Claude or OpenAI agent example in a second terminal. Requires the provider SDK and API key (ANTHROPIC_API_KEY or OPENAI_API_KEY). If successful, the agent will invoke the tool and print the temperature result.

```bash
cd sdks/python
poetry run python -m examples.agent.agent_claude
# or
poetry run python -m examples.agent.agent_openai
```

--------------------------------

### docker-compose example with PostgreSQL and PgBouncer

Source: https://docs.hatchet.run/llms/self-hosting/using-pgbouncer.md

Example docker-compose setup with PostgreSQL 15.6 and PgBouncer v1.25.1-p0. PgBouncer is configured with transaction pool mode and connects to the postgres service. Adjust ports and credentials as needed.

```yaml
version: "3.8"
services:
  postgres:
    image: postgres:15.6
    command: postgres -c 'max_connections=500' -c 'shared_preload_libraries=auto_explain' -c 'auto_explain.log_min_duration=1000' -c 'auto_explain.log_analyze=on' -c 'auto_explain.log_verbose=on' -c 'auto_explain.log_timing=on' -c 'auto_explain.log_buffers=on' -c 'auto_explain.log_wal=on' -c 'auto_explain.log_triggers=on' -c 'auto_explain.log_format=text'
    restart: always
    environment:
      - POSTGRES_USER=hatchet
      - POSTGRES_PASSWORD=hatchet
      - POSTGRES_DB=hatchet
    ports:
      - "5431:5432"
    volumes:
      - hatchet_postgres_data:/var/lib/postgresql/data
    shm_size: 4g
  pgbouncer:
    image: edoburu/pgbouncer:v1.25.1-p0
    restart: always
    environment:
      - DATABASE_URL=postgres://hatchet:hatchet@postgres:5432/hatchet
      - POOL_MODE=transaction
      - MAX_CLIENT_CONN=1000
      - DEFAULT_POOL_SIZE=50
      - AUTH_TYPE=plain
      - LISTEN_PORT=6432
    ports:
      - "6431:6432"
    depends_on:
      - postgres
```

--------------------------------

### Get

Source: https://docs.hatchet.run/llms/reference/go/feature-clients/filters.md

Get gets a filter by its ID.

```APIDOC
## Get

### Description
Get gets a filter by its ID.

### Method
Get

### Signature
```go
func (c *FiltersClient) Get(ctx context.Context, filterID string) (*rest.V1Filter, error)
```

### Parameters
- `ctx` (context.Context) - Required - The context for the operation.
- `filterID` (string) - Required - The ID of the filter to retrieve.

### Returns
- `*rest.V1Filter` - The retrieved filter.
- `error` - An error if the operation fails.
```

--------------------------------

### Install Hatchet CLI via install script

Source: https://docs.hatchet.run/llms/reference/cli.md

Installs the Hatchet CLI on macOS, Linux, or WSL using the official install script. This is the recommended method.

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

--------------------------------

### Create a Hatchet client with default options

Source: https://docs.hatchet.run/llms/reference/ruby/client.md

Initializes a Hatchet client with no arguments, using default configuration and environment variables.

```ruby
hatchet = Hatchet::Client.new()
```

--------------------------------

### Define SignupInput and WelcomeEmailResult models (Python)

Source: https://docs.hatchet.run/cookbooks/welcome-email

Defines the input and output Pydantic models for the welcome email workflow. The input contains the user's email and ID, and the output indicates whether the welcome and follow-up emails were sent.

```python
class SignupInput(BaseModel):
    email: str
    user_id: str


class WelcomeEmailResult(BaseModel):
    user_id: str
    welcome_sent: bool
    follow_up_sent: bool
```

--------------------------------

### Get

Source: https://docs.hatchet.run/reference/go/feature-clients/filters

Get gets a filter by its ID. It takes a context and a filter ID and returns a rest.V1Filter or an error.

```APIDOC
## Get

### Description
Get gets a filter by its ID.

### Method
func (c *FiltersClient) Get(ctx context.Context, filterID string) (*rest.V1Filter, error)

### Parameters
- **ctx** (context.Context) - Required - The context for the operation.
- **filterID** (string) - Required - The ID of the filter to retrieve.

### Returns
- **rest.V1Filter** - The requested filter.
- **error** - An error if the operation failed.
```

--------------------------------

### Verify Hatchet CLI installation

Source: https://docs.hatchet.run/llms/reference/cli.md

Checks the installed Hatchet CLI version to confirm the installation was successful.

```sh
hatchet --version
```

--------------------------------

### Database Individual Parameters (DATABASE_POSTGRES_HOST)

Source: https://docs.hatchet.run/llms/self-hosting/configuration-options.md

Required for Hatchet startup. Sets individual PostgreSQL connection parameters; each falls back to its default if not set.

```bash
DATABASE_POSTGRES_HOST=127.0.0.1
DATABASE_POSTGRES_PORT=5432
DATABASE_POSTGRES_USERNAME=hatchet
DATABASE_POSTGRES_PASSWORD=<your-password>
DATABASE_POSTGRES_DB_NAME=hatchet
DATABASE_POSTGRES_SSL_MODE=disable
```

--------------------------------

### Install specific Hatchet CLI version via install script

Source: https://docs.hatchet.run/llms/reference/cli.md

Installs a specific version of the Hatchet CLI by passing a release tag to the install script. Replace vX.Y.Z with the desired version.

```sh
curl -fsSL https://install.hatchet.run/install.sh | bash -s -- vX.Y.Z
```

--------------------------------

### get

Source: https://docs.hatchet.run/llms/reference/ruby/feature-clients/events.md

Get a specific event by ID.

```APIDOC
## get

### Description
Get a specific event by ID.

### Method
get

### Parameters
#### Path Parameters
- **event_id** (String) - Required - The event ID.

### Response
#### Success Response
- **Object** - The event details.

### Errors
- **Hatchet::Error** - If the API request fails or returns an error.
```

--------------------------------

### Database Connection String (DATABASE_URL)

Source: https://docs.hatchet.run/llms/self-hosting/configuration-options.md

Required for Hatchet startup. Provides the PostgreSQL connection string.

```bash
DATABASE_URL="postgresql://user:password@host:port/dbname"
```

--------------------------------

### Get

Source: https://docs.hatchet.run/llms/reference/go/feature-clients/workers.md

Get retrieves a worker by its ID.

```APIDOC
## Get

### Description
Get retrieves a worker by its ID.

### Method
Get

### Signature
func (w *WorkersClient) Get(ctx context.Context, workerId string) (*rest.Worker, error)

### Parameters
- **ctx** (context.Context) - Required - The context for the request.
- **workerId** (string) - Required - The ID of the worker to retrieve.

### Returns
- **\*rest.Worker** - The retrieved worker.
- **error** - An error if the operation failed.
```

--------------------------------

### Install MCP server into agents

Source: https://docs.hatchet.run/llms/reference/cli/mcp.md

Runs the interactive installer that writes the MCP server configuration into supported AI coding agents. Without flags, it opens a multi-select of agents, pre-checking those detected in the current project or home directory. After writing configs, it offers to grant profiles if none are granted yet.

```sh
hatchet mcp install
```

--------------------------------

### Python trigger script for welcome email workflow

Source: https://docs.hatchet.run/cookbooks/welcome-email

Starts the welcome-email workflow, pushes an onboarding-completed event scoped to the user, and waits for the workflow to complete.

```python
from examples.welcome_email.worker import (    ONBOARDING_EVENT_KEY,    SignupInput,    hatchet,    welcome_email,)signup = SignupInput(    email="alice@example.com",    user_id="user-123",)# Start the welcome-email workflowref = welcome_email.run(signup, wait_for_result=False)print(f"Started workflow run: {ref.workflow_run_id}")# Push onboarding-completed event (scoped to this user)print("Pushing onboarding-completed event...")hatchet.event.push(    ONBOARDING_EVENT_KEY,    {"status": "done"},    scope=signup.user_id,)# Wait for the workflow to completeresult = ref.result()print(f"Workflow completed: {result}")
```

```python
from examples.welcome_email.worker import (
    ONBOARDING_EVENT_KEY,
    SignupInput,
    hatchet,
    welcome_email,
)

signup = SignupInput(
    email="alice@example.com",
    user_id="user-123",
)

# Start the welcome-email workflow
ref = welcome_email.run(signup, wait_for_result=False)
print(f"Started workflow run: {ref.workflow_run_id}")

# Push onboarding-completed event (scoped to this user)
print("Pushing onboarding-completed event...")
hatchet.event.push(
    ONBOARDING_EVENT_KEY,
    {"status": "done"},
    scope=signup.user_id,
)

# Wait for the workflow to complete
result = ref.result()
print(f"Workflow completed: {result}")
```

--------------------------------

### Get

Source: https://docs.hatchet.run/llms/reference/go/feature-clients/webhooks.md

Get retrieves a specific webhook by its name.

```APIDOC
## Get

### Description
Get retrieves a specific webhook by its name.

### Method
Get

### Signature
```go
func (c *WebhooksClient) Get(ctx context.Context, webhookName string) (*rest.V1Webhook, error)
```

### Parameters
- `ctx` (context.Context) - Required - The context for the request.
- `webhookName` (string) - Required - The name of the webhook to retrieve.

### Returns
- `*rest.V1Webhook` - The retrieved webhook.
- `error` - An error if the operation failed.
```

--------------------------------

### Create support agent with OpenAI Agents SDK (Python)

Source: https://docs.hatchet.run/cookbooks/hatchet-openai-agents-sdk-trusted-env

Creates a support agent with three tools (lookup customer, check order status, create ticket) and runs it once, printing the final output. Unlike the Claude version, no in-process MCP server or pre-approved tool names are used.

```python
import asyncio

from agents import Agent, Runner
from examples.support_agent_tools.tools import (
    create_lookup_customer_tool_openai,
    create_check_order_status_tool_openai,
    create_ticket_tool_openai,
)


async def main() -> None:
    lookup_customer_tool = create_lookup_customer_tool_openai()
    check_order_status_tool = create_check_order_status_tool_openai()
    ticket_tool = create_ticket_tool_openai()

    agent = Agent(
        name="support-agent",
        tools=[lookup_customer_tool, check_order_status_tool, ticket_tool],
    )

    result = await Runner.run(
        agent,
        "Customer C-100 says order ORD-9987 has not arrived. "
        "Look up the customer, check the order status, and create a "
        "support ticket if the order has a known issue or delayed delivery. "
        'If you create a ticket, use priority "high", subject '
        '"Delayed order ORD-9987", and a body that summarizes the known '
        "carrier delay. Then summarize what happened.",
    )
    print(result.final_output)


if __name__ == "__main__":
    asyncio.run(main())

```

--------------------------------

### Install HA Helm chart with helm install

Source: https://docs.hatchet.run/llms/self-hosting/high-availability.md

Adds the Hatchet Helm repository and installs the hatchet-ha chart. Use this to deploy Hatchet in a high availability configuration.

```sh
helm repo add hatchet https://hatchet-dev.github.io/hatchet-charts
helm install hatchet-ha hatchet/hatchet-ha
```

--------------------------------

### Create

Source: https://docs.hatchet.run/llms/reference/go/feature-clients/webhooks.md

Create creates a new webhook configuration.

```APIDOC
## Create

### Description
Create creates a new webhook configuration.

### Method
Create

### Signature
```go
func (c *WebhooksClient) Create(ctx context.Context, opts CreateWebhookOpts) (*rest.V1Webhook, error)
```

### Parameters
- `ctx` (context.Context) - Required - The context for the request.
- `opts` (CreateWebhookOpts) - Required - Options for creating the webhook.

### Returns
- `*rest.V1Webhook` - The created webhook.
- `error` - An error if the operation failed.
```

--------------------------------

### get()

Source: https://docs.hatchet.run/llms/reference/typescript/feature-clients/workflows.md

Gets a workflow by its name, ID, or object. Returns a promise that resolves to the workflow.

```APIDOC
## get()

### Description
Gets a workflow by its name, ID, or object.

### Method
GET

### Endpoint
WorkflowsClient.get()

### Parameters
#### Parameters
- **workflow** (string | BaseWorkflowDeclaration<any, any> | Workflow) - Required - The workflow name, ID, or object.

### Returns
`Promise<Workflow>` - A promise that resolves to the workflow.

```
Tokens:
Raw