# https://github.com/triggerdotdev/trigger.dev Project Manual Generated at: 2026-06-12 04:11:13 UTC ## Table of Contents - [Platform Overview & Architecture](#page-overview) - [Trigger.dev CLI v3 & Developer Workflows](#page-cli) - [Run Engine, Queues, and Task Execution](#page-run-engine) - [Deployment, Self-hosting & Worker Infrastructure](#page-deployment) ## Platform Overview & Architecture ### Related Pages Related topics: [Run Engine, Queues, and Task Execution](#page-run-engine), [Trigger.dev CLI v3 & Developer Workflows](#page-cli)
Related Source Files The following source files were used to generate this page: - [README.md](https://github.com/triggerdotdev/trigger.dev/blob/main/README.md) - [packages/cli-v3/README.md](https://github.com/triggerdotdev/trigger.dev/blob/main/packages/cli-v3/README.md) - [packages/cli-v3/package.json](https://github.com/triggerdotdev/trigger.dev/blob/main/packages/cli-v3/package.json) - [packages/core/package.json](https://github.com/triggerdotdev/trigger.dev/blob/main/packages/core/package.json) - [packages/trigger-sdk/README.md](https://github.com/triggerdotdev/trigger.dev/blob/main/packages/trigger-sdk/README.md) - [packages/python/package.json](https://github.com/triggerdotdev/trigger.dev/blob/main/packages/python/package.json) - [packages/python/README.md](https://github.com/triggerdotdev/trigger.dev/blob/main/packages/python/README.md) - [packages/schema-to-json/package.json](https://github.com/triggerdotdev/trigger.dev/blob/main/packages/schema-to-json/package.json) - [packages/plugins/package.json](https://github.com/triggerdotdev/trigger.dev/blob/main/packages/plugins/package.json) - [packages/rsc/package.json](https://github.com/triggerdotdev/trigger.dev/blob/main/packages/rsc/package.json) - [apps/webapp/package.json](https://github.com/triggerdotdev/trigger.dev/blob/main/apps/webapp/package.json)
# Platform Overview & Architecture ## Purpose and Scope Trigger.dev is an open source platform for building and deploying fully-managed AI agents and workflows. It enables developers to write workflows in standard async TypeScript, supporting everything from simple tasks to long-running AI agents, heavy media processing, and complex real-time systems. The platform provides full observability, managed queues, and elastic infrastructure that handles horizontal scaling automatically. Source: [README.md:1-15]() The repository is a monorepo containing the CLI, SDK packages, build extensions, and the web application that powers the Trigger.dev dashboard. Each component is published as an independently versioned npm package, currently aligned at `4.5.0-rc.5`. Source: [packages/cli-v3/package.json:2](), [packages/core/package.json:2](), [packages/python/package.json:2]() The platform can be deployed as a managed cloud service or self-hosted via the official Docker image: `ghcr.io/triggerdotdev/trigger.dev`. Source: [packages/cli-v3/README.md:18-20]() ## Repository Structure The repository is organized as a pnpm workspace with the following top-level packages under `packages/` and the control-plane web application under `apps/`: | Package | Purpose | Source | | :--- | :--- | :--- | | `cli-v3` (`trigger.dev`) | Command-line interface for login, init, dev, deploy, and profile management | [packages/cli-v3/package.json:1-5]() | | `core` (`@trigger.dev/core`) | Shared code used across SDK and platform (schemas, OTP, JWT, errors, workers) | [packages/core/package.json:3-7]() | | `trigger-sdk` (`@trigger.dev/sdk`) | Official TypeScript SDK for defining and triggering tasks | [packages/trigger-sdk/README.md:7-10]() | | `python` (`@trigger.dev/python`) | Python runtime and build extension for executing Python scripts | [packages/python/package.json:3-4]() | | `schema-to-json` (`@trigger.dev/schema-to-json`) | Converts Zod, Yup, Valibot, ArkType, etc. into JSON Schema | [packages/schema-to-json/package.json:3-4]() | | `plugins` (`@trigger.dev/plugins`) | Plugin contracts and interfaces for the build system | [packages/plugins/package.json:3-4]() | | `rsc` (`@trigger.dev/rsc`) | React Server Components integration helpers | [packages/rsc/package.json:3-4]() | | `apps/webapp` | Dashboard / web UI for managing projects, runs, and deployments | [apps/webapp/package.json]() | All packages use workspace dependencies (`workspace:*` or `workspace:4.5.0-rc.5`) to reference `@trigger.dev/core`, ensuring a single shared source of truth for schemas, types, and utilities. Source: [packages/cli-v3/package.json:38-40](), [packages/core/package.json:54-56]() ## Core Architecture ### Task Definition Model Tasks are defined inside the user's codebase using the SDK. Each task exports a `task({ id, run })` factory call, where `id` is a unique identifier and `run` is an async TypeScript function that may run for arbitrarily long durations. Source: [README.md:62-72]() ```ts import { task } from "@trigger.dev/sdk"; export const helloWorld = task({ id: "hello-world", run: async (payload: { message: string }) => { console.log(payload.message); }, }); ``` This model keeps version control, testing, and review inside the developer's normal workflow rather than moving logic into an external scheduler. Source: [README.md:55-61]() ### Build System with Extensions The platform exposes a build extension API. Extensions hook into the deploy pipeline to install runtimes, bundle code, and configure container images. The Python extension, for example, installs Python via `pip`, creates a virtual environment at `/opt/venv`, and exposes helper functions (`run`, `runInline`, `runScript`) for executing Python from TypeScript tasks. Source: [packages/python/README.md:18-30]() Extensions are registered in `trigger.config.ts`: ```ts import { defineConfig } from "@trigger.dev/sdk/v3"; import { pythonExtension } from "@trigger.dev/python/extension"; export default defineConfig({ project: "", build: { extensions: [ pythonExtension({ requirementsFile: "./requirements.txt", devPythonBinaryPath: ".venv/bin/python", scripts: ["src/python/**/*.py"], }), ], }, }); ``` Source: [packages/python/README.md:9-25]() ### CLI Command Surface The CLI (`trigger.dev`) is the developer entry point and exposes the following commands: | Command | Description | | :--- | :--- | | `login` | Authenticate with Trigger.dev | | `init` | Initialize an existing project for local development | | `dev` | Run tasks locally with hot reload | | `deploy` | Deploy the project to the cloud | | `whoami` | Display the current logged-in user and project | | `logout` | Clear stored credentials | | `list-profiles` | List all configured CLI profiles | | `preview archive` | Archive a preview branch | | `promote` | Promote a previously deployed version to the current version | | `switch` | Switch between CLI profiles | Source: [packages/cli-v3/README.md:8-18]() ### Runtime Concerns The core package centralizes concerns that are reused by both the SDK and the platform server: OpenTelemetry tracing (`./v3/otel`), JWT issuance and validation (`./v3/jwt`), Zod-based schemas (`./v3/schemas`), durable workers (`./v3/workers`), and the run engine worker (`./v3/runEngineWorker`). Source: [packages/core/package.json:14-48]() ## Development, Deployment, and Known Issues ### Local-to-Cloud Workflow ```mermaid flowchart LR Dev[Local Codebase
trigger.config.ts] -->|trigger dev| LocalRun[Local Worker
Hot Reload] Dev -->|trigger deploy| Build[Build Pipeline
+ Extensions] Build --> Image[Container Image
Python, deps, etc.] Image --> Cloud[Trigger.dev Cloud
or Self-hosted Docker] Cloud --> Dashboard[apps/webapp
Dashboard & Observability] Source: [README.md:74-78](), [packages/python/README.md:20-26](), [packages/cli-v3/README.md:8-18]() ``` The `dev` command runs tasks locally while preserving the same observability surface as production, and `deploy` produces an immutable version that can later be promoted via `trigger promote`. Source: [packages/cli-v3/README.md:8-18]() ### Distribution Channels Each major version is published both as an npm package (`trigger.dev`) and as a GitHub Container Registry image. Self-hosters pin to a specific tag such as `ghcr.io/triggerdotdev/trigger.dev:v4.5.0-rc.5`. Source: [packages/cli-v3/README.md:20-24]() ### Known Limitation: Workspace Catalogs A documented bug affects projects that reference `@trigger.dev/*` dependencies through pnpm or bun `catalog:` protocols. The CLI crashes with `Invalid comparator: catalog:` because the version comparator parser does not recognize the catalog syntax. Source: GitHub issue [#3905](https://github.com/triggerdotdev/trigger.dev/issues/3905). Workarounds include pinning the `@trigger.dev/*` dependencies to explicit versions or using `workspace:*` ranges instead of named catalogs until the comparator is updated. ## See Also - CLI Command Reference — generated from [packages/cli-v3/README.md](https://github.com/triggerdotdev/trigger.dev/blob/main/packages/cli-v3/README.md) - Python Build Extension — generated from [packages/python/README.md](https://github.com/triggerdotdev/trigger.dev/blob/main/packages/python/README.md) - Core Package Schemas and Workers — generated from [packages/core/package.json](https://github.com/triggerdotdev/trigger.dev/blob/main/packages/core/package.json) - Self-hosting Guide — referenced from [README.md](https://github.com/triggerdotdev/trigger.dev/blob/main/README.md) - Release notes — tracked at the [trigger.dev releases page](https://github.com/triggerdotdev/trigger.dev/releases) --- ## Trigger.dev CLI v3 & Developer Workflows ### Related Pages Related topics: [Platform Overview & Architecture](#page-overview), [Deployment, Self-hosting & Worker Infrastructure](#page-deployment)
Related Source Files The following source files were used to generate this page: - [packages/cli-v3/package.json](https://github.com/triggerdotdev/trigger.dev/blob/main/packages/cli-v3/package.json) - [packages/cli-v3/README.md](https://github.com/triggerdotdev/trigger.dev/blob/main/packages/cli-v3/README.md) - [packages/trigger-sdk/package.json](https://github.com/triggerdotdev/trigger.dev/blob/main/packages/trigger-sdk/package.json) - [packages/trigger-sdk/README.md](https://github.com/triggerdotdev/trigger.dev/blob/main/packages/trigger-sdk/README.md) - [packages/python/package.json](https://github.com/triggerdotdev/trigger.dev/blob/main/packages/python/package.json) - [packages/python/README.md](https://github.com/triggerdotdev/trigger.dev/blob/main/packages/python/README.md) - [packages/core/package.json](https://github.com/triggerdotdev/trigger.dev/blob/main/packages/core/package.json) - [packages/schema-to-json/README.md](https://github.com/triggerdotdev/trigger.dev/blob/main/packages/schema-to-json/README.md) - [packages/plugins/package.json](https://github.com/triggerdotdev/trigger.dev/blob/main/packages/plugins/package.json) - [README.md](https://github.com/triggerdotdev/trigger.dev/blob/main/README.md)
# Trigger.dev CLI v3 & Developer Workflows ## Overview & Purpose The Trigger.dev CLI v3 is the official command-line interface for Trigger.dev projects. Published as the unscoped `trigger.dev` package on npm, it is the entry point developers use to scaffold projects, run tasks locally, deploy workflows to the Trigger.dev cloud, and manage authenticated profiles. Source: [packages/cli-v3/package.json:1-15]() The CLI targets the same `v3` runtime that the TypeScript SDK exposes. Trigger.dev is an open-source platform for building and deploying fully-managed AI agents and long-running workflows written in normal async TypeScript, with managed queues, elastic scaling, and full observability. Source: [README.md:1-30](), [packages/trigger-sdk/README.md:1-30]() The CLI also advertises an MCP (Model Context Protocol) integration through its `mcpName` field (`io.github.triggerdotdev/trigger.dev`), which lets editor/agent hosts discover and invoke the CLI as a tool surface. Source: [packages/cli-v3/package.json:18-21]() ## Package Architecture & Distribution The CLI is a pure ESM package (`"type": "module"`) shipped as `dist` plus a `skills` directory, and exposes a single binary called `trigger` that resolves to `dist/esm/index.js`. Source: [packages/cli-v3/package.json:9-37](). The package's keyword set signals its target ecosystem: `typescript`, `workflows`, `orchestration`, `events`, `webhooks`, `integrations`, `apis`, `jobs`, `background jobs`, `nextjs`, and `tanstack-intent`. Source: [packages/cli-v3/package.json:22-32]() The CLI is one node in a wider monorepo of `@trigger.dev/*` packages that the `update` command keeps in lockstep. The current coordinated release is `4.5.0-rc.5`, which is also the version the Python extension, the SDK, and `@trigger.dev/core` carry. Source: [packages/cli-v3/package.json:3](), [packages/trigger-sdk/package.json:3](), [packages/python/package.json:3](), [packages/core/package.json:3]() Cross-package boundaries are enforced through the `@trigger.dev/core` package, which re-exports the shared types, schemas, build pipeline, JWT helpers, error shapes, OpenTelemetry utilities, and the v3 tracer that the CLI and SDK both consume. Source: [packages/core/package.json:28-44]() ## CLI Commands & Core Developer Workflow The CLI is organized around a small set of command groups. The README documents the following top-level commands and their purpose: | Command group | Purpose | |---|---| | `profile`, `login`, `logout`, `whoami` | Manage CLI profiles and authentication against the Trigger.dev API. | | `dev` | Start the local development server for a project. | | `deploy` | Deploy the project to the Trigger.dev cloud. | | `preview archive` | Archive a preview branch. | | `promote` | Promote a previously deployed version to the current version. | | `switch` | Switch between CLI profiles. | | `update` | Update all `@trigger.dev/*` packages to match the CLI version. | Source: [packages/cli-v3/README.md:1-30]() The end-to-end developer loop is: install the CLI (`npm i -g trigger.dev` or via `npx`), run `init` to scaffold a project (with `trigger.config.ts` and a starter task), develop tasks with `dev`, and ship with `deploy`. The SDK exposes the `task` builder that backs those commands: ```ts import { task } from "@trigger.dev/sdk"; export const helloWorld = task({ id: "hello-world", run: async (payload: { message: string }) => { console.log(payload.message); }, }); ``` Source: [README.md:32-46](), [packages/trigger-sdk/README.md:1-30]() ## SDK Integration & Build Extensions The CLI drives the build pipeline, but the configuration surface that developers edit is owned by the SDK. `trigger.config.ts` is the single place where projects register build extensions, declare the project reference, and pin runtime options. Source: [packages/python/README.md:1-20]() Build extensions are pluggable. The Python extension (`@trigger.dev/python`) is a good example: it adds the `pythonExtension` to `build.extensions`, accepts a `requirementsFile`, an optional `devPythonBinaryPath`, and a `scripts` glob. It installs Python dependencies with `pip` (except in dev), creates a virtual environment at `/opt/venv` in containers, and exposes `python.run`, `python.runInline`, and `python.runScript` helpers for use inside tasks. Source: [packages/python/README.md:1-30](), [packages/python/package.json:1-30]() The wider extension contract lives in `@trigger.dev/plugins`, which provides the plugin interfaces that extensions like Python implement, and in `@trigger.dev/schema-to-json`, which converts schemas from Zod, Yup, ArkType, Effect/Schema, and TypeBox into JSON Schema for task payload validation. Source: [packages/plugins/package.json:1-30](), [packages/schema-to-json/README.md:1-30]() The SDK itself exposes several sub-entries relevant to workflow authors: the default `.` / `./v3` entry, an `./ai` entry (with `./ai/skills-runtime` and `./ai/test`) for agent-style tasks, and `./chat`, `./chat/react`, and `./chat-server` for chat surfaces. Source: [packages/trigger-sdk/package.json:21-37]() ## Community & Known Issues The CLI ships a coordinated release train. Recent release notes show rapid `4.5.0-rc.x` progression (rc.0 through rc.5) on top of the stable `4.4.x` line (`4.4.3`–`4.4.6`), each accompanied by an updated self-hosted Docker image at `ghcr.io/triggerdotdev/trigger.dev:`. Source: [release: v4.5.0-rc.5](https://github.com/triggerdotdev/trigger.dev/releases/tag/v4.5.0-rc.5), [release: v4.4.6](https://github.com/triggerdotdev/trigger.dev/releases/tag/v4.4.6)() A notable real-world failure mode reported by users on Windows 11 with Node 22.20.0 and bun 1.3.14 is the `Invalid comparator: catalog:` error raised by the CLI when `@trigger.dev/*` dependencies are declared via the bun or pnpm `catalog:` workspace protocol. The `update` workflow cannot parse a version range that begins with the `catalog:` shorthand, so monorepos using workspace catalogs must pin `@trigger.dev/*` versions explicitly until the comparator is taught about the protocol. Source: [issue #3905](https://github.com/triggerdotdev/trigger.dev/issues/3905)() ## See Also - [@trigger.dev/sdk — TypeScript SDK overview](https://github.com/triggerdotdev/trigger.dev/blob/main/packages/trigger-sdk/README.md) - [@trigger.dev/python — Python build extension](https://github.com/triggerdotdev/trigger.dev/blob/main/packages/python/README.md) - [@trigger.dev/schema-to-json — Schema conversion](https://github.com/triggerdotdev/trigger.dev/blob/main/packages/schema-to-json/README.md) - [Self-hosting overview](https://trigger.dev/docs/self-hosting/overview) - [CLI introduction (docs)](https://trigger.dev/docs/cli-introduction) --- ## Run Engine, Queues, and Task Execution ### Related Pages Related topics: [Platform Overview & Architecture](#page-overview), [Deployment, Self-hosting & Worker Infrastructure](#page-deployment)
Related Source Files The following source files were used to generate this page: - [internal-packages/run-engine/README.md](https://github.com/triggerdotdev/trigger.dev/blob/main/internal-packages/run-engine/README.md) - [internal-packages/schedule-engine/README.md](https://github.com/triggerdotdev/trigger.dev/blob/main/internal-packages/schedule-engine/README.md) - [packages/redis-worker/README.md](https://github.com/triggerdotdev/trigger.dev/blob/main/packages/redis-worker/README.md) - [internal-packages/clickhouse/src/taskRuns.ts](https://github.com/triggerdotdev/trigger.dev/blob/main/internal-packages/clickhouse/src/taskRuns.ts) - [internal-packages/clickhouse/src/taskRuns.test.ts](https://github.com/triggerdotdev/trigger.dev/blob/main/internal-packages/clickhouse/src/taskRuns.test.ts) - [packages/cli-v3/README.md](https://github.com/triggerdotdev/trigger.dev/blob/main/packages/cli-v3/README.md) - [packages/trigger-sdk/README.md](https://github.com/triggerdotdev/trigger.dev/blob/main/packages/trigger-sdk/README.md) - [README.md](https://github.com/triggerdotdev/trigger.dev/blob/main/README.md) - [packages/core/package.json](https://github.com/triggerdotdev/trigger.dev/blob/main/packages/core/package.json)
# Run Engine, Queues, and Task Execution ## Purpose and Scope The Run Engine is the central control plane of the Trigger.dev platform responsible for the full lifecycle of a task run: triggering, queueing, executing, retrying, and completing. It is described in [internal-packages/run-engine/README.md](https://github.com/triggerdotdev/trigger.dev/blob/main/internal-packages/run-engine/README.md) as the process that "runs from triggering, to executing, retrying, and completing" runs. Concretely, the engine creates, updates, and completes runs, operates the run queue (including concurrency enforcement), heartbeats active runs to detect stalls, and registers checkpoints that allow long-running runs to pause and resume. Source: [internal-packages/run-engine/README.md]() The Run Engine is part of the broader Trigger.dev platform, which is "an open source platform for building and deploying fully-managed AI agents and workflows" written in async TypeScript ([README.md](https://github.com/triggerdotdev/trigger.dev/blob/main/README.md)). It depends on shared resources surfaced via `@trigger.dev/core` (the v4.5.0-rc.5 release) and the CLI published as the `trigger` binary ([packages/core/package.json](https://github.com/triggerdotdev/trigger.dev/blob/main/packages/core/package.json), [packages/cli-v3/package.json](https://github.com/triggerdotdev/trigger.dev/blob/main/packages/cli-v3/package.json)). ## High-Level Architecture The Run Engine is organized as a single orchestrator (`RunEngine`) that composes several cooperating subsystems backed by shared infrastructure. Source: [internal-packages/run-engine/README.md]() ```mermaid flowchart TB Client[Client / SDK trigger] --> EnqQ[EnqueueSystem] Sched[ScheduleEngine] --> EnqQ EnqQ --> MasterQ[RunQueue] MasterQ --> DeqQ[DequeueSystem] DeqQ --> Attempt[RunAttemptSystem] Attempt --> Snap[ExecutionSnapshotSystem] Attempt --> Wait[WaitpointSystem] Attempt --> Batch[BatchSystem] Snap --> DB[(Prisma / ClickHouse)] Wait --> MasterQ Heartbeat[Heartbeat Watcher] --> Attempt Checkpoint[Checkpoint Store] --> Attempt ``` ### Core Subsystems The RunEngine composes six specialized subsystems, each with a bounded responsibility ([internal-packages/run-engine/README.md](https://github.com/triggerdotdev/trigger.dev/blob/main/internal-packages/run-engine/README.md)): | Subsystem | Responsibility | |-----------|----------------| | **DequeueSystem** | Dequeues tasks from master queues, verifies deployment, allocates resources | | **RunAttemptSystem** | Manages the attempt lifecycle: success, failure, retry, cancellation | | **ExecutionSnapshotSystem** | Creates snapshots, tracks state and progress, manages heartbeats and history | | **WaitpointSystem** | Manages waitpoints for synchronization, unblocks runs, releases concurrency | | **BatchSystem** | Coordinates batch operations and batch-related runs | | **EnqueueSystem** | Enqueues runs, schedules, and creates execution snapshots | The subsystems share infrastructure resources including `Prisma` (database), `Logger`, `Tracer`, `RunQueue`, `RunLocker`, `EventBus`, `Worker`, and `ReleaseConcurrencyQueue`. The `RunEngine` orchestrates them and `ExecutionSnapshotSystem` is invoked by all other systems to record state transitions. Source: [internal-packages/run-engine/README.md]() ## Worker Hierarchy and Run Execution Trigger.dev runs tasks on a tiered runtime model described in the glossary of [internal-packages/run-engine/README.md](https://github.com/triggerdotdev/trigger.dev/blob/main/internal-packages/run-engine/README.md): - **Platform** — the main Trigger.dev API, dashboard, and database. The Run Engine lives here. - **Worker group** — a set of workers pulling from the same queue (for example, `us-east-1` or `my-self-hosted-workers`). - **Worker** — a "server" that connects to the platform and receives runs. - **Supervisor** — pulls new runs from the queue, communicates with the platform, and spins up Deploy executors. - **Deploy container** — a container derived from a specific deployment of a user project. - **Run controller** — the code that manages running a task. - **Run executor** — the actual running task. This hierarchy separates durable orchestration (Run Engine) from ephemeral execution (Run executor). The local development experience is provided by the `dev` CLI command ([packages/cli-v3/README.md](https://github.com/triggerdotdev/trigger.dev/blob/main/packages/cli-v3/README.md)), which runs Trigger.dev tasks against the user's local codebase using the same task definitions. The `deploy` command uploads the built image so that worker Supervisors can spin up Deploy containers. Source: [packages/cli-v3/README.md]() ## Queues, Scheduling, and Persistence ### Run Queue and Concurrency The Run Engine operates the `RunQueue` and `ReleaseConcurrencyQueue` resources to enforce per-queue concurrency limits. When a run is dequeued, the engine verifies the task deployment is valid before allocating resources. The `RunLocker` ensures that only one supervisor at a time executes a given run, while `EventBus` propagates state changes to other subsystems. Source: [internal-packages/run-engine/README.md]() A complementary lightweight queueing primitive is provided by the `redis-worker` package, which is "a simple worker that pulls tasks from a Redis queue" with "configurable settings for concurrency and pull speed," "job payloads," "a schema so only defined jobs can be added to the queue," and "the ability to have future dates for jobs" ([packages/redis-worker/README.md](https://github.com/triggerdotdev/trigger.dev/blob/main/packages/redis-worker/README.md)). This is useful for first-in/first-out job processing without the full Run Engine semantics. ### Schedule Engine Cron-style schedules are handled by the dedicated `ScheduleEngine` package, which "encapsulates all scheduling logic for Trigger.dev" and mirrors the RunEngine pattern with centralized schedule management, Redis-based distributed scheduling, and a `distributionWindow` (default 30s) to "prevent thundering herd issues by distributing executions across time windows." Source: [internal-packages/schedule-engine/README.md](https://github.com/triggerdotdev/trigger.dev/blob/main/internal-packages/schedule-engine/README.md) The ScheduleEngine exposes operations like `registerNextTaskScheduleInstance` and `upsertTaskSchedule`, and it integrates with the Run Engine by handing off due instances for execution. ### Run State and Analytics Task run records are persisted to ClickHouse with a wide, well-typed column schema. The `TASK_RUN_COLUMNS` tuple in [internal-packages/clickhouse/src/taskRuns.ts](https://github.com/triggerdotdev/trigger.dev/blob/main/internal-packages/clickhouse/src/taskRuns.ts) includes `run_id`, `status` (e.g., `PENDING`, `EXECUTING`, `COMPLETED_SUCCESSFULLY`), `environment_type` (`DEVELOPMENT`, etc.), `task_identifier`, `queue`, `attempt`, `engine` (`V2`), `usage_duration_ms`, `cost_in_cents`, `tags`, `trace_id`, `span_id`, `idempotency_key`, `concurrency_key`, `worker_queue`, `task_kind`, and `is_warm_start`. A matching `TaskRunFieldTypes` mapping and `TASK_RUN_INDEX` are auto-generated from this tuple so that column indices stay in sync. Source: [internal-packages/clickhouse/src/taskRuns.ts]() A type-safe query builder, `getTaskRunsQueryBuilder`, is exercised in [internal-packages/clickhouse/src/taskRuns.test.ts](https://github.com/triggerdotdev/trigger.dev/blob/main/internal-packages/clickhouse/src/taskRuns.test.ts), where test fixtures insert `PENDING` and `EXECUTING` runs and then filter by `environment_id` and `status` to demonstrate how the Run Engine's state transitions are queryable downstream. ## Common Failure Modes and Operational Notes - **Workspace catalog CLI crash** — Issue [#3905](https://github.com/triggerdotdev/trigger.dev/issues/3905) reports that the CLI crashes with "Invalid comparator: catalog:" when `@trigger.dev/*` dependencies use the bun/pnpm `catalog:` protocol. This affects the `dev` and `deploy` commands in [packages/cli-v3/README.md](https://github.com/triggerdotdev/trigger.dev/blob/main/packages/cli-v3/README.md) because dependency resolution walks `package.json` during the build phase. - **Stalled runs** — mitigated by the heartbeat watcher in `ExecutionSnapshotSystem`; runs that stop emitting heartbeats are auto-recovered by the Run Engine. Source: [internal-packages/run-engine/README.md]() - **Concurrency exhaustion** — when a queue is saturated, the `ReleaseConcurrencyQueue` is responsible for returning tokens as runs complete; if this stalls, downstream dequeueing can be blocked. Source: [internal-packages/run-engine/README.md]() - **Versioning** — the v4.5.0-rc.5 release ([release notes](https://github.com/triggerdotdev/trigger.dev/releases/tag/v4.5.0-rc.5)) and earlier v4.4.x patch releases indicate active iteration on the run engine; self-hosted users upgrade via `npx trigger.dev@latest update` and the matching Docker image at `ghcr.io/triggerdotdev/trigger.dev:v4.5.0-rc.5`. ## See Also - [CLI Commands Reference](https://github.com/triggerdotdev/trigger.dev/blob/main/packages/cli-v3/README.md) - [Schedule Engine Architecture](https://github.com/triggerdotdev/trigger.dev/blob/main/internal-packages/schedule-engine/README.md) - [Redis Worker](https://github.com/triggerdotdev/trigger.dev/blob/main/packages/redis-worker/README.md) - [ClickHouse Task Runs Schema](https://github.com/triggerdotdev/trigger.dev/blob/main/internal-packages/clickhouse/src/taskRuns.ts) - [@trigger.dev/core Package](https://github.com/triggerdotdev/trigger.dev/blob/main/packages/core/package.json) - [Trigger.dev Main README](https://github.com/triggerdotdev/trigger.dev/blob/main/README.md) --- ## Deployment, Self-hosting & Worker Infrastructure ### Related Pages Related topics: [Platform Overview & Architecture](#page-overview), [Run Engine, Queues, and Task Execution](#page-run-engine)
Related Source Files The following source files were used to generate this page: - [README.md](https://github.com/triggerdotdev/trigger.dev/blob/main/README.md) - [hosting/README.md](https://github.com/triggerdotdev/trigger.dev/blob/main/hosting/README.md) - [hosting/k8s/helm/README.md](https://github.com/triggerdotdev/trigger.dev/blob/main/hosting/k8s/helm/README.md) - [packages/cli-v3/README.md](https://github.com/triggerdotdev/trigger.dev/blob/main/packages/cli-v3/README.md) - [packages/cli-v3/package.json](https://github.com/triggerdotdev/trigger.dev/blob/main/packages/cli-v3/package.json) - [packages/core/package.json](https://github.com/triggerdotdev/trigger.dev/blob/main/packages/core/package.json) - [packages/trigger-sdk/README.md](https://github.com/triggerdotdev/trigger.dev/blob/main/packages/trigger-sdk/README.md) - [internal-packages/run-engine/README.md](https://github.com/triggerdotdev/trigger.dev/blob/main/internal-packages/run-engine/README.md) - [packages/python/README.md](https://github.com/triggerdotdev/trigger.dev/blob/main/packages/python/README.md) - [packages/plugins/package.json](https://github.com/triggerdotdev/trigger.dev/blob/main/packages/plugins/package.json) - [packages/rsc/package.json](https://github.com/triggerdotdev/trigger.dev/blob/main/packages/rsc/package.json) - [packages/schema-to-json/package.json](https://github.com/triggerdotdev/trigger.dev/blob/main/packages/schema-to-json/package.json)
# Deployment, Self-hosting & Worker Infrastructure ## Overview Trigger.dev is an open-source platform for building and deploying AI agents and workflows, offering two primary deployment paths: a fully-managed cloud and a self-hosted stack. The self-hosted option supports both Docker Compose and Kubernetes (via an official Helm chart), while the worker infrastructure is powered by an in-house Run Engine that orchestrates task execution, queues, and state management. The CLI is the primary user-facing tool for deployment workflows. Distributed as the `trigger` binary, it handles authentication, project initialization, local development, and cloud deployment ([`packages/cli-v3/README.md`](https://github.com/triggerdotdev/trigger.dev/blob/main/packages/cli-v3/README.md)). The current CLI version is `4.5.0-rc.5`, as published in [`packages/cli-v3/package.json`](https://github.com/triggerdotdev/trigger.dev/blob/main/packages/cli-v3/package.json), and the platform follows the same versioning across SDK packages ([`packages/core/package.json`](https://github.com/triggerdotdev/trigger.dev/blob/main/packages/core/package.json), [`packages/python/package.json`](https://github.com/triggerdotdev/trigger.dev/blob/main/packages/python/package.json)). ## Deployment with the CLI The CLI exposes a focused set of commands for moving code from a developer's machine to a deployed environment. The most relevant for deployment are: | Command | Purpose | | :--- | :--- | | `init` | Initialize an existing project for development with Trigger.dev | | `dev` | Run Trigger.dev tasks locally | | `deploy` | Deploy a v3 project to the cloud | | `promote` | Promote a previously deployed version to the current version | | `preview archive` | Archive a preview branch | | `whoami` | Display the current logged-in user and project details | Source: [`packages/cli-v3/README.md`](https://github.com/triggerdotdev/trigger.dev/blob/main/packages/cli-v3/README.md) A typical deployment flow begins with `login` to authenticate, `init` to scaffold configuration, `dev` for local iteration, and finally `deploy` to ship the workload. The `promote` command enables version-controlled rollouts by swapping an existing deployment into the current version slot, which is useful for staging-to-production promotions. The CLI is published to npm under the name `trigger` ([`packages/cli-v3/package.json`](https://github.com/triggerdotdev/trigger.dev/blob/main/packages/cli-v3/package.json)) and the repository provides an MCP metadata field (`mcpName: io.github.triggerdotdev/trigger.dev`) for editor integrations. ## Self-hosting Options Trigger.dev ships first-class self-hosting artifacts for both Docker and Kubernetes. The [`hosting/README.md`](https://github.com/triggerdotdev/trigger.dev/blob/main/hosting/README.md) file serves as the entry point for the self-hosting directory, and the project documentation links to dedicated guides for each runtime. ### Docker Docker Compose is the recommended path for evaluation, single-node deployments, and small production setups. The official Docker image is published to GHCR for every release (for example, `ghcr.io/triggerdotdev/trigger.dev:v4.5.0-rc.5`), and an upgrade command is provided: ```sh npx trigger.dev@latest update ``` A production-ready Docker deployment must override default secrets, configure persistent storage, and set up TLS via a reverse proxy. The community frequently references `docker-compose.traefik.yml` and a multi-service `docker-compose.yml` for this purpose. ### Kubernetes (Helm) For production-grade or multi-node deployments, Trigger.dev publishes an official Helm chart. The chart is OCI-distributed: ```bash helm upgrade --install trigger \ oci://ghcr.io/triggerdotdev/charts/trigger.dev \ --version 4.1.0 ``` Source: [`hosting/k8s/helm/README.md`](https://github.com/triggerdotdev/trigger.dev/blob/main/hosting/k8s/helm/README.md) The Helm chart includes a production-readiness checklist emphasizing security: all required secrets must be 32 hexadecimal characters (16 bytes), pod-level security contexts must run as non-root, and `readOnlyRootFilesystem: true` should be enabled where possible. Users are also instructed to set `appVersion` in `Chart.yaml` to match the Trigger.dev release using the v-prefixed image tag. The dashboard is exposed via a Kubernetes Service and is typically reached through `kubectl port-forward`: ```bash kubectl port-forward svc/trigger-webapp 3040:3030 --address 0.0.0.0 ``` Once a self-hosted instance is reachable, tasks are deployed to it from a developer's machine using the standard CLI plus the `--push` flag, which is required when targeting a local or self-hosted coordinator: ```bash npx trigger.dev@latest deploy --push ``` Source: [`hosting/k8s/helm/README.md`](https://github.com/triggerdotdev/trigger.dev/blob/main/hosting/k8s/helm/README.md) ## Worker Infrastructure (Run Engine) The worker layer that executes tasks is the Run Engine, documented in [`internal-packages/run-engine/README.md`](https://github.com/triggerdotdev/trigger.dev/blob/main/internal-packages/run-engine/README.md). It is a modular system composed of several cooperating subsystems that share a common set of resources (Prisma, Logger, Tracer, RunQueue, RunLocker, EventBus, Worker, and a ReleaseConcurrencyQueue). ```mermaid flowchart LR Client[Client / SDK] --> EnqueueSystem EnqueueSystem --> RunQueue RunQueue --> DequeueSystem DequeueSystem --> RunAttemptSystem RunAttemptSystem --> ExecutionSnapshotSystem RunAttemptSystem --> WaitpointSystem RunAttemptSystem --> BatchSystem WaitpointSystem --> EnqueueSystem ExecutionSnapshotSystem --> DB[(Prisma / Postgres)] Tracer[Tracer & Logger] -.-> DequeueSystem Tracer -.-> RunAttemptSystem Tracer -.-> WaitpointSystem ``` The `DequeueSystem` pulls tasks from the master queue, enforces resource constraints, and verifies deployments. `RunAttemptSystem` owns the lifecycle of each attempt, handling success, failure, retry, and cancellation. `ExecutionSnapshotSystem` creates periodic snapshots, heartbeats, and an execution history, while `WaitpointSystem` coordinates blocked runs and synchronizes concurrency release through `EnqueueSystem`. `BatchSystem` coordinates batch-triggered task runs. The shared resources are critical to horizontal scaling: `RunQueue` distributes work, `RunLocker` prevents duplicate execution, and `EventBus` decouples subsystems so they can be scaled or restarted independently. The Run Engine is exported from the core package's deep export path `@trigger.dev/core/v3/runEngineWorker`, alongside related modules such as `machines`, `workers`, and `serverOnly` ([`packages/core/package.json`](https://github.com/triggerdotdev/trigger.dev/blob/main/packages/core/package.json)). ## SDK, Build Extensions, and Server Components The deployment pipeline is extensible through a build-extension model. The official Python extension, for example, adds a `pythonExtension` that installs Python dependencies, creates a virtual environment at `/opt/venv`, and exposes `python.run`, `python.runInline`, and `python.runScript` helpers ([`packages/python/README.md`](https://github.com/triggerdotdev/trigger.dev/blob/main/packages/python/README.md)). The extension is registered in `trigger.config.ts` under `build.extensions`, allowing users to compose custom build steps before deployment. The SDK itself is published as `@trigger.dev/sdk` and provides the `task` definition primitive used to declare runnable units ([`packages/trigger-sdk/README.md`](https://github.com/triggerdotdev/trigger.dev/blob/main/packages/trigger-sdk/README.md)). Adjacent packages extend the platform further: `@trigger.dev/rsc` adds React Server Components support ([`packages/rsc/package.json`](https://github.com/triggerdotdev/trigger.dev/blob/main/packages/rsc/package.json)), `@trigger.dev/plugins` provides the plugin contract ([`packages/plugins/package.json`](https://github.com/triggerdotdev/trigger.dev/blob/main/packages/plugins/package.json)), and `@trigger.dev/schema-to-json` converts various validation libraries into JSON Schema for payload validation ([`packages/schema-to-json/package.json`](https://github.com/triggerdotdev/trigger.dev/blob/main/packages/schema-to-json/package.json)). ## Known Issues and Community Notes A known CLI bug tracked in the community affects deployments that use workspace catalogs (the `catalog:` protocol in `pnpm` and `bun`). When `@trigger.dev/*` dependencies are declared via a workspace catalog, the CLI crashes with `Invalid comparator: catalog:`. This is a monorepo-resolution limitation in the dependency comparator and is documented in issue #3905. The current workaround is to pin `@trigger.dev/*` dependencies to explicit versions or to local `workspace:*` references until the fix lands in a later `4.5.x` release. ## See Also - Run Engine internals ([`internal-packages/run-engine/README.md`](https://github.com/triggerdotdev/trigger.dev/blob/main/internal-packages/run-engine/README.md)) - CLI reference ([`packages/cli-v3/README.md`](https://github.com/triggerdotdev/trigger.dev/blob/main/packages/cli-v3/README.md)) - Helm chart guide ([`hosting/k8s/helm/README.md`](https://github.com/triggerdotdev/trigger.dev/blob/main/hosting/k8s/helm/README.md)) - Self-hosting entry point ([`hosting/README.md`](https://github.com/triggerdotdev/trigger.dev/blob/main/hosting/README.md)) - Python build extension ([`packages/python/README.md`](https://github.com/triggerdotdev/trigger.dev/blob/main/packages/python/README.md)) - Project root overview ([`README.md`](https://github.com/triggerdotdev/trigger.dev/blob/main/README.md)) --- --- ## Pitfall Log Project: triggerdotdev/trigger.dev Summary: Found 19 structured pitfall item(s), including 0 high/blocking item(s). Top priority: Identity risk - Identity risk requires verification. ## 1. Identity risk - Identity risk requires verification - Severity: medium - Evidence strength: runtime_trace - Finding: Project evidence flags a identity risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Repro command: `npm install @trigger.dev/sdk` - Evidence: identity.distribution | github_repo:572570113 | https://github.com/triggerdotdev/trigger.dev ## 2. Installation risk - Installation risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Developers should check this installation risk before relying on the project: bug: CLI crashes with "Invalid comparator: catalog:" when @trigger.dev/* deps use workspace catalogs (bun/pnpm catalog: protocol) - User impact: Developers may fail before the first successful local run: bug: CLI crashes with "Invalid comparator: catalog:" when @trigger.dev/* deps use workspace catalogs (bun/pnpm catalog: protocol) - Evidence: failure_mode_cluster:github_issue | https://github.com/triggerdotdev/trigger.dev/issues/3905 ## 3. Installation risk - Installation risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Developers should check this installation risk before relying on the project: trigger.dev v4.4.3 - User impact: Upgrade or migration may change expected behavior: trigger.dev v4.4.3 - Evidence: failure_mode_cluster:github_release | https://github.com/triggerdotdev/trigger.dev/releases/tag/v4.4.3 ## 4. Installation risk - Installation risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Developers should check this installation risk before relying on the project: trigger.dev v4.4.4 - User impact: Upgrade or migration may change expected behavior: trigger.dev v4.4.4 - Evidence: failure_mode_cluster:github_release | https://github.com/triggerdotdev/trigger.dev/releases/tag/v4.4.4 ## 5. Installation risk - Installation risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Developers should check this installation risk before relying on the project: trigger.dev v4.4.5 - User impact: Upgrade or migration may change expected behavior: trigger.dev v4.4.5 - Evidence: failure_mode_cluster:github_release | https://github.com/triggerdotdev/trigger.dev/releases/tag/v4.4.5 ## 6. Installation risk - Installation risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Developers should check this installation risk before relying on the project: trigger.dev v4.4.6 - User impact: Upgrade or migration may change expected behavior: trigger.dev v4.4.6 - Evidence: failure_mode_cluster:github_release | https://github.com/triggerdotdev/trigger.dev/releases/tag/v4.4.6 ## 7. Installation risk - Installation risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Developers should check this installation risk before relying on the project: trigger.dev v4.5.0-rc.0 - User impact: Upgrade or migration may change expected behavior: trigger.dev v4.5.0-rc.0 - Evidence: failure_mode_cluster:github_release | https://github.com/triggerdotdev/trigger.dev/releases/tag/v4.5.0-rc.0 ## 8. Installation risk - Installation risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Developers should check this installation risk before relying on the project: trigger.dev v4.5.0-rc.1 - User impact: Upgrade or migration may change expected behavior: trigger.dev v4.5.0-rc.1 - Evidence: failure_mode_cluster:github_release | https://github.com/triggerdotdev/trigger.dev/releases/tag/v4.5.0-rc.1 ## 9. Installation risk - Installation risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Developers should check this installation risk before relying on the project: trigger.dev v4.5.0-rc.2 - User impact: Upgrade or migration may change expected behavior: trigger.dev v4.5.0-rc.2 - Evidence: failure_mode_cluster:github_release | https://github.com/triggerdotdev/trigger.dev/releases/tag/v4.5.0-rc.2 ## 10. Installation risk - Installation risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Developers should check this installation risk before relying on the project: trigger.dev v4.5.0-rc.3 - User impact: Upgrade or migration may change expected behavior: trigger.dev v4.5.0-rc.3 - Evidence: failure_mode_cluster:github_release | https://github.com/triggerdotdev/trigger.dev/releases/tag/v4.5.0-rc.3 ## 11. Installation risk - Installation risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Developers should check this installation risk before relying on the project: trigger.dev v4.5.0-rc.4 - User impact: Upgrade or migration may change expected behavior: trigger.dev v4.5.0-rc.4 - Evidence: failure_mode_cluster:github_release | https://github.com/triggerdotdev/trigger.dev/releases/tag/v4.5.0-rc.4 ## 12. Installation risk - Installation risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Developers should check this installation risk before relying on the project: trigger.dev v4.5.0-rc.5 - User impact: Upgrade or migration may change expected behavior: trigger.dev v4.5.0-rc.5 - Evidence: failure_mode_cluster:github_release | https://github.com/triggerdotdev/trigger.dev/releases/tag/v4.5.0-rc.5 ## 13. Installation risk - Installation risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: community_evidence:github | https://github.com/triggerdotdev/trigger.dev/issues/3905 ## 14. Capability evidence risk - Capability evidence risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: README/documentation is current enough for a first validation pass. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: capability.assumptions | github_repo:572570113 | https://github.com/triggerdotdev/trigger.dev ## 15. Maintenance risk - Maintenance risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Project evidence flags a maintenance risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: evidence.maintainer_signals | github_repo:572570113 | https://github.com/triggerdotdev/trigger.dev ## 16. Security or permission risk - Security or permission risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: no_demo - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: downstream_validation.risk_items | github_repo:572570113 | https://github.com/triggerdotdev/trigger.dev ## 17. Security or permission risk - Security or permission risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: no_demo - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: risks.scoring_risks | github_repo:572570113 | https://github.com/triggerdotdev/trigger.dev ## 18. Maintenance risk - Maintenance risk requires verification - Severity: low - Evidence strength: source_linked - Finding: issue_or_pr_quality=unknown。 - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: evidence.maintainer_signals | github_repo:572570113 | https://github.com/triggerdotdev/trigger.dev ## 19. Maintenance risk - Maintenance risk requires verification - Severity: low - Evidence strength: source_linked - Finding: release_recency=unknown。 - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: evidence.maintainer_signals | github_repo:572570113 | https://github.com/triggerdotdev/trigger.dev