Running Hatchet Locally
The Hatchet CLI provides the hatchet server commands to run a local instance of Hatchet for development and testing purposes. This local instance relies on Docker to run the necessary services.
When DOCKER_HOST is not set, Hatchet resolves the Docker host from the current Docker context. This respects DOCKER_CONTEXT when it is set, and otherwise uses the active context from your local Docker configuration. If DOCKER_HOST is set explicitly, it takes precedence.
Prerequisites
Before running Hatchet locally, you must have Docker installed on your machine. You can download Docker from here.
Starting Hatchet Locally
To start a local instance of Hatchet, run the following command in your terminal:
hatchet server startStopping Hatchet Locally
To stop the local Hatchet instance, run the following command:
hatchet server stopReference
hatchet server start
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.Running without authentication
hatchet server start --disable-auth runs the hatchet-lite-dev image, a variant built with authentication compiled out. Everything runs as the seeded admin against the default tenant, so tenant creation, signup and invites are disabled.
Workers and SDK clients still authenticate with the gRPC engine using an API token. The dev image ships a single fixed worker token (the same on every auth-disabled instance, scoped to the default tenant, non-expiring). You can view this token from the API Tokens section in Settings.
Dev variants exist for the other server images too: hatchet-api-dev, hatchet-engine-dev, hatchet-admin-dev and hatchet-dashboard-dev (ghcr.io/hatchet-dev/hatchet/hatchet-<component>-dev). They are for local development and testing only - the regular images never compile the embedded token in, so it is inert against any normal deployment.
hatchet server stop
Stop a local Hatchet server environment that was started using Docker containers with the 'hatchet server start' command.
Usage:
hatchet server stop [flags]
Examples:
# Stop the local Hatchet server
hatchet server stop
# Stop the local Hatchet server with a custom project name
hatchet server stop --project-name my-hatchet
Flags:
-h, --help help for stop
-p, --project-name string Docker project name for containers (default: hatchet-cli)
Global Flags:
-v, --version The version of the hatchet cli.