TypeScript SDK
Add to CursorAdd to ClaudeCopy for LLMView as MD

Embedded

Embedded mode runs a full local Hatchet engine as a sidecar process managed by your application. It needs no API token, no Docker, and no external services (by default the sidecar starts a bundled Postgres), which makes it a good fit for local development and CI.

import { HatchetEmbeddedClient } from "@hatchet-dev/typescript-sdk/v1/embedded";

const hatchet = await HatchetEmbeddedClient.init();
// ... register workers and run tasks as usual ...
await hatchet.stopEmbedded();

See the embedded mode guide for setup and configuration details.

Hatchet Embedded Client

Entry point for embedded mode. init() starts a full local Hatchet engine and returns a regular Hatchet client connected to it. No API token or Docker is needed. See the embedded mode guide.

Methods

init()

Runs a full Hatchet engine locally via the hatchet-embedded sidecar (downloaded on first use) and returns a client wired to it. No API token or Docker is needed, which makes this a good fit for local development and CI. By default the sidecar starts a bundled Postgres; pass databaseUrl to point it at your own instead.

See the embedded mode guide.

Parameters

ParameterTypeDescription
embeddedOpts?EmbeddedOptionsOptions for the embedded engine (version, ports, database, ...).
config?Omit<Partial<ClientConfig>, "middleware">Optional configuration overrides for the client.
options?HatchetClientOptionsOptional client options.
axiosConfig?AxiosRequestConfig<any>Optional Axios configuration for HTTP requests.

Returns

Promise<EmbeddedClient<T, U>>

A new Hatchet client instance connected to the embedded engine.

Interfaces

EmbeddedOptions

Options for the embedded engine sidecar. All fields are optional; by default the latest hatchet-embedded release is downloaded and started with a bundled Postgres.

Properties

PropertyTypeDescription
apiPort?numberbind the REST API server to this port
binaryPath?stringpath to an existing sidecar binary, skips the download (or HATCHET_CLIENT_EMBEDDED_BINARY_PATH)
checksum?stringexpected sha256 hex digest of the sidecar binary. When set, it replaces the release's checksums.txt as the trust anchor, so a compromised release channel cannot substitute the binary. Pin it together with version.
databaseUrl?stringuse an existing Postgres instead of the bundled one
grpcPort?numberbind the engine's gRPC server to this port
logLevel?stringlog level for the engine's output
postgresDataDir?stringstore the bundled Postgres runtime and data under this directory
rabbitmqUrl?stringuse RabbitMQ instead of the Postgres message queue
readyTimeoutMs?numberhow long to wait for the engine to become ready, in milliseconds (default 300000)
runMigrations?booleanset to false to skip running migrations on startup
startApi?booleanset to false to start only the engine + gRPC, no REST API
version?stringhatchet-embedded release tag to download (defaults to HATCHET_CLIENT_EMBEDDED_VERSION or latest). Tags correspond to the Hatchet engine version baked into the sidecar, so pinning this pins the engine.

EmbeddedSidecar

A running embedded engine sidecar and its connection details, as returned by startEmbeddedSidecar.

Properties

PropertyTypeDescription
apiUrlstringbase URL of the REST API (empty when startApi is false)
grpcAddressstringhost:port of the engine's gRPC server
stop() => Promise<void>gracefully stops the sidecar and resolves once it has fully exited
tenantIdstringID of the sidecar's default tenant
tokenstringAPI token for the sidecar's default tenant

Type Aliases

Embedded Client

type EmbeddedClient<T, U> = HatchetClient<T, U> & object;

A HatchetClient connected to an embedded engine, extended with stopEmbedded. Returned by HatchetEmbeddedClient.init.

Type Declaration

NameTypeDescription
stopEmbedded()() => Promise<...>Gracefully stops the embedded engine sidecar and resolves once it has fully exited, including its bundled Postgres. Call this before your process exits so the engine's shutdown output does not print after your program has returned.

Functions

startEmbeddedSidecar()

Downloads (and caches) the hatchet-embedded sidecar binary, spawns it, and waits until the embedded engine is ready. The sidecar shuts down when this process exits. Use HatchetEmbeddedClient.init unless you need the raw connection details.

Parameters

ParameterType
optsEmbeddedOptions

Returns

Promise<EmbeddedSidecar>

stopEmbeddedSidecar()

Gracefully stops every sidecar started in this process by HatchetEmbeddedClient.init() (or startEmbeddedSidecar) and resolves once they have fully exited, including their bundled Postgres. Call this before your process exits so the engine's shutdown output does not print after your program has returned.

Returns

Promise<void>

Last updated on September 1, 2026

Context

Previous Page

CEL

Next Page

On this page

EmbeddedHatchet Embedded ClientMethodsinit()InterfacesEmbeddedOptionsEmbeddedSidecarType AliasesEmbedded ClientType DeclarationFunctionsstartEmbeddedSidecar()stopEmbeddedSidecar()