Get a Hatchet token
Hogsend's one prerequisite. Local dev auto-mints it for you in bootstrap; for production, get a token from the self-hosted hatchet-lite dashboard, Hatchet Cloud, or your own instance and set three env vars.
Hatchet is the durable execution engine underneath every journey — it's what makes ctx.sleep(days(2)) survive a deploy and resume two days later exactly where it left off. Hogsend connects to whatever Hatchet you point it at through three environment variables, and a token is the one thing the engine needs before its first boot.
Good news for getting started: you don't have to mint one by hand for local dev. The scaffolder's pnpm bootstrap step brings up a local hatchet-lite container and mints a token straight into your .env. The manual paths below are for production, or for the times you want to do it yourself.
The fast path — let bootstrap do it
If you're following Installation, you've already scaffolded an app:
pnpm dlx create-hogsend@latest my-app
cd my-app
pnpm bootstrappnpm bootstrap runs a 7-step local setup. Step 5 is minting the Hatchet token: it starts hatchet-lite in Docker, reads the tenant id out of the running container, mints a token with hatchet-admin token create, and writes it to .env as HATCHET_CLIENT_TOKEN. The local .env.example already sets the other two values for the insecure compose path:
HATCHET_CLIENT_HOST_PORT=localhost:7077
HATCHET_CLIENT_TLS_STRATEGY=noneSo for local dev there is nothing to copy-paste. You get:
[5/7] Minting Hatchet token
✓ Minted a Hatchet API token → .envBootstrap is idempotent. Re-running it sees an existing valid token and leaves it alone (✓ HATCHET_CLIENT_TOKEN already set — keeping it). It also auto-mints an ingest-scoped data-plane key (HOGSEND_API_KEY) in a later step, so your local instance is ready to receive events the moment it boots.
The local hatchet-lite dashboard is at http://localhost:8888, default login admin@example.com / Admin123!! — handy for watching journey runs, even though you won't need to touch it to mint a token.
The three env vars
Whichever path you take, Hatchet is configured through exactly three variables. The @hatchet-dev/typescript-sdk reads them straight from the environment; Hogsend's env schema validates that the token is present and the TLS strategy is one of the allowed values, then hands them to the SDK.
| Variable | Required | Default | What it is |
|---|---|---|---|
HATCHET_CLIENT_TOKEN | Yes | — | Bearer JWT for the engine. The SDK throws if it's empty. The only mandatory value. Auto-minted by pnpm bootstrap for local dev. |
HATCHET_CLIENT_HOST_PORT | No | localhost:7077 | gRPC host:port. Falls back to the address embedded in the token, but set it explicitly for clarity. |
HATCHET_CLIENT_TLS_STRATEGY | No | tls | One of none | tls | mtls. Secure by default (matches Hatchet Cloud); the local hatchet-lite path uses none. |
HATCHET_CLIENT_NAMESPACE | No | (empty) | Optional per-tenant isolation namespace on a shared engine. |
The same three values work for every path below — only what you put in them differs. The full annotated env list lives in .env.example and on the Configuration page.
Getting a token by hand
For production — or when you're bootstrapping a token outside the scaffold flow — pick the path that matches how you run the engine.
Path A — self-hosted hatchet-lite (the default)
This is what pnpm bootstrap automates for you locally; the steps below do it manually. The local docker compose (and the production compose file) runs hatchet-lite alongside the app. Since the app needs a token to boot but the token only exists once the engine is up, bring the engine up first, mint a token in its dashboard, then start the app:
# 1. Bring up just the Hatchet engine.
docker compose up -d hatchet-lite
# 2. Open the dashboard, log in, and mint a token:
# http://localhost:8888 (default login below)
# → Settings → API Tokens → create → copy the JWT
# 3. Paste it into .env, then bring up the rest.
# HATCHET_CLIENT_TOKEN=<the JWT you just copied>
docker compose up -dDefault dashboard login: admin@example.com / Admin123!!.
For hatchet-lite the engine speaks insecure gRPC. Locally the engine listens on localhost:7077:
HATCHET_CLIENT_HOST_PORT=localhost:7077
HATCHET_CLIENT_TLS_STRATEGY=noneWhen the app and the engine run on the same Docker network (the production compose file), dial the service name instead:
HATCHET_CLIENT_HOST_PORT=hatchet-lite:7077
HATCHET_CLIENT_TLS_STRATEGY=noneChange the default admin credentials before exposing the dashboard to any network, and treat the minted token as a secret. The token embeds the engine's gRPC broadcast address, so a token minted against localhost won't work from a real domain — if you move the host, mint a fresh token. Set the engine's public host (see the compose file) so the dashboard URL, cookie domain, and the address the token embeds all match what clients dial.
Path B — Hatchet Cloud (managed)
Zero infrastructure to run. Create a tenant, generate an API token, paste it.
- Sign up at Hatchet Cloud and create a tenant.
- Generate an API token (Settings → API Tokens).
- Set it:
HATCHET_CLIENT_TOKEN=<the Cloud token>
HATCHET_CLIENT_HOST_PORT=<your Cloud gRPC address> # or omit; the token embeds it
HATCHET_CLIENT_TLS_STRATEGY=tlsCloud speaks TLS, so leave HATCHET_CLIENT_TLS_STRATEGY at its tls default.
Path C — bring your own Hatchet
Already running a Hatchet engine, or pointing at one your platform team operates? Supply the three values yourself:
HATCHET_CLIENT_TOKEN=<token from your engine>
HATCHET_CLIENT_HOST_PORT=<your engine's gRPC host:port>
HATCHET_CLIENT_TLS_STRATEGY=<none | tls | mtls — match your engine>