# 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.

For other ways to run Hatchet locally, including embedded mode with no Docker at all, see [Running Hatchet Locally](/v1/running-locally).

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](https://www.docker.com/get-started).

## Starting Hatchet Locally

To start a local instance of Hatchet, run the following command in your terminal:

```sh
hatchet server start
```

## Stopping Hatchet Locally

To stop the local Hatchet instance, run the following command:

```sh
hatchet server stop
```

## Reference

#### `hatchet server start`

```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.
```

#### 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`

```txt
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.
```