Doramagic Project Pack · Human Manual

trigger.dev

Trigger.dev – build and deploy fully‑managed AI agents and workflows

Platform Overview & Architecture

Related topics: Run Engine, Queues, and Task Execution, Trigger.dev CLI v3 & Developer Workflows

Section Related Pages

Continue reading this section for the full explanation and source context.

Section Task Definition Model

Continue reading this section for the full explanation and source context.

Section Build System with Extensions

Continue reading this section for the full explanation and source context.

Section CLI Command Surface

Continue reading this section for the full explanation and source context.

Related topics: Run Engine, Queues, and Task Execution, Trigger.dev CLI v3 & Developer Workflows

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/:

PackagePurposeSource
cli-v3 (trigger.dev)Command-line interface for login, init, dev, deploy, and profile managementpackages/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 taskspackages/trigger-sdk/README.md:7-10
python (@trigger.dev/python)Python runtime and build extension for executing Python scriptspackages/python/package.json:3-4
schema-to-json (@trigger.dev/schema-to-json)Converts Zod, Yup, Valibot, ArkType, etc. into JSON Schemapackages/schema-to-json/package.json:3-4
plugins (@trigger.dev/plugins)Plugin contracts and interfaces for the build systempackages/plugins/package.json:3-4
rsc (@trigger.dev/rsc)React Server Components integration helperspackages/rsc/package.json:3-4
apps/webappDashboard / web UI for managing projects, runs, and deploymentsapps/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

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:

import { defineConfig } from "@trigger.dev/sdk/v3";
import { pythonExtension } from "@trigger.dev/python/extension";

export default defineConfig({
  project: "<project ref>",
  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:

CommandDescription
loginAuthenticate with Trigger.dev
initInitialize an existing project for local development
devRun tasks locally with hot reload
deployDeploy the project to the cloud
whoamiDisplay the current logged-in user and project
logoutClear stored credentials
list-profilesList all configured CLI profiles
preview archiveArchive a preview branch
promotePromote a previously deployed version to the current version
switchSwitch 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

flowchart LR
  Dev[Local Codebase<br/>trigger.config.ts] -->|trigger dev| LocalRun[Local Worker<br/>Hot Reload]
  Dev -->|trigger deploy| Build[Build Pipeline<br/>+ Extensions]
  Build --> Image[Container Image<br/>Python, deps, etc.]
  Image --> Cloud[Trigger.dev Cloud<br/>or Self-hosted Docker]
  Cloud --> Dashboard[apps/webapp<br/>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. 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
  • Python Build Extension — generated from packages/python/README.md
  • Core Package Schemas and Workers — generated from packages/core/package.json
  • Self-hosting Guide — referenced from README.md
  • Release notes — tracked at the trigger.dev releases page

Source: https://github.com/triggerdotdev/trigger.dev / Human Manual

Trigger.dev CLI v3 & Developer Workflows

Related topics: Platform Overview & Architecture, Deployment, Self-hosting & Worker Infrastructure

Section Related Pages

Continue reading this section for the full explanation and source context.

Related topics: Platform Overview & Architecture, Deployment, Self-hosting & Worker Infrastructure

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 groupPurpose
profile, login, logout, whoamiManage CLI profiles and authentication against the Trigger.dev API.
devStart the local development server for a project.
deployDeploy the project to the Trigger.dev cloud.
preview archiveArchive a preview branch.
promotePromote a previously deployed version to the current version.
switchSwitch between CLI profiles.
updateUpdate 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:

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.34.4.6), each accompanied by an updated self-hosted Docker image at ghcr.io/triggerdotdev/trigger.dev:<version>. Source: release: v4.5.0-rc.5, release: 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()

See Also

Source: https://github.com/triggerdotdev/trigger.dev / Human Manual

Run Engine, Queues, and Task Execution

Related topics: Platform Overview & Architecture, Deployment, Self-hosting & Worker Infrastructure

Section Related Pages

Continue reading this section for the full explanation and source context.

Section Core Subsystems

Continue reading this section for the full explanation and source context.

Section Run Queue and Concurrency

Continue reading this section for the full explanation and source context.

Section Schedule Engine

Continue reading this section for the full explanation and source context.

Related topics: Platform Overview & Architecture, Deployment, Self-hosting & Worker Infrastructure

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 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). 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, 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

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):

SubsystemResponsibility
DequeueSystemDequeues tasks from master queues, verifies deployment, allocates resources
RunAttemptSystemManages the attempt lifecycle: success, failure, retry, cancellation
ExecutionSnapshotSystemCreates snapshots, tracks state and progress, manages heartbeats and history
WaitpointSystemManages waitpoints for synchronization, unblocks runs, releases concurrency
BatchSystemCoordinates batch operations and batch-related runs
EnqueueSystemEnqueues 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:

  • 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), 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). 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

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 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, 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 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 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) 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
  • Schedule Engine Architecture
  • Redis Worker
  • ClickHouse Task Runs Schema
  • @trigger.dev/core Package
  • Trigger.dev Main README

Source: https://github.com/triggerdotdev/trigger.dev / Human Manual

Deployment, Self-hosting & Worker Infrastructure

Related topics: Platform Overview & Architecture, Run Engine, Queues, and Task Execution

Section Related Pages

Continue reading this section for the full explanation and source context.

Section Docker

Continue reading this section for the full explanation and source context.

Section Kubernetes (Helm)

Continue reading this section for the full explanation and source context.

Related topics: Platform Overview & Architecture, Run Engine, Queues, and Task Execution

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). The current CLI version is 4.5.0-rc.5, as published in packages/cli-v3/package.json, and the platform follows the same versioning across SDK packages (packages/core/package.json, 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:

CommandPurpose
initInitialize an existing project for development with Trigger.dev
devRun Trigger.dev tasks locally
deployDeploy a v3 project to the cloud
promotePromote a previously deployed version to the current version
preview archiveArchive a preview branch
whoamiDisplay the current logged-in user and project details

Source: 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) 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 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:

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:

helm upgrade --install trigger \
  oci://ghcr.io/triggerdotdev/charts/trigger.dev \
  --version 4.1.0

Source: 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:

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:

npx trigger.dev@latest deploy --push

Source: 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. 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).

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

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). 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). Adjacent packages extend the platform further: @trigger.dev/rsc adds React Server Components support (packages/rsc/package.json), @trigger.dev/plugins provides the plugin contract (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).

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)
  • CLI reference (packages/cli-v3/README.md)
  • Helm chart guide (hosting/k8s/helm/README.md)
  • Self-hosting entry point (hosting/README.md)
  • Python build extension (packages/python/README.md)
  • Project root overview (README.md)

Source: https://github.com/triggerdotdev/trigger.dev / Human Manual

Doramagic Pitfall Log

Source-linked risks stay visible on the manual page so the preview does not read like a recommendation.

medium Identity risk requires verification

May increase setup, validation, or first-run risk for the user.

medium Installation risk requires verification

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)

medium Installation risk requires verification

Upgrade or migration may change expected behavior: trigger.dev v4.4.3

medium Installation risk requires verification

Upgrade or migration may change expected behavior: trigger.dev v4.4.4

Doramagic Pitfall Log

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
  • 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.
  • Recommended check: Reproduce the official install and quickstart path in an isolated environment.
  • Evidence: identity.distribution | github_repo:572570113 | https://github.com/triggerdotdev/trigger.dev

2. Installation risk: Installation risk requires verification

  • Severity: medium
  • 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)
  • Recommended check: Before packaging this project, run the relevant install/config/quickstart check for: bug: CLI crashes with "Invalid comparator: catalog:" when @trigger.dev/* deps use workspace catalogs (bun/pnpm catalog: protocol). Context: Observed when using node, windows
  • Evidence: failure_mode_cluster:github_issue | https://github.com/triggerdotdev/trigger.dev/issues/3905

3. Installation risk: Installation risk requires verification

  • Severity: medium
  • 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
  • Recommended check: Before packaging this project, run the relevant install/config/quickstart check for: trigger.dev v4.4.3. Context: Observed when using node, python, docker
  • 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
  • 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
  • Recommended check: Before packaging this project, run the relevant install/config/quickstart check for: trigger.dev v4.4.4. Context: Observed when using node, docker
  • 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
  • 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
  • Recommended check: Before packaging this project, run the relevant install/config/quickstart check for: trigger.dev v4.4.5. Context: Observed when using node, docker
  • 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
  • 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
  • Recommended check: Before packaging this project, run the relevant install/config/quickstart check for: trigger.dev v4.4.6. Context: Observed when using node, python, docker
  • 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
  • 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
  • Recommended check: Before packaging this project, run the relevant install/config/quickstart check for: trigger.dev v4.5.0-rc.0. Context: Observed when using node, docker
  • 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
  • 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
  • Recommended check: Before packaging this project, run the relevant install/config/quickstart check for: trigger.dev v4.5.0-rc.1. Context: Observed when using node, python, docker
  • 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
  • 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
  • Recommended check: Before packaging this project, run the relevant install/config/quickstart check for: trigger.dev v4.5.0-rc.2. Context: Observed when using node, python, docker
  • 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
  • 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
  • Recommended check: Before packaging this project, run the relevant install/config/quickstart check for: trigger.dev v4.5.0-rc.3. Context: Observed when using node, python, docker
  • 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
  • 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
  • Recommended check: Before packaging this project, run the relevant install/config/quickstart check for: trigger.dev v4.5.0-rc.4. Context: Observed when using node, python, docker
  • 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
  • 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
  • Recommended check: Before packaging this project, run the relevant install/config/quickstart check for: trigger.dev v4.5.0-rc.5. Context: Observed when using node, python, docker
  • Evidence: failure_mode_cluster:github_release | https://github.com/triggerdotdev/trigger.dev/releases/tag/v4.5.0-rc.5

Source: Doramagic discovery, validation, and Project Pack records

Community Discussion Evidence

These external discussion links are review inputs, not standalone proof that the project is production-ready.

Sources 12

Count of project-level external discussion links exposed on this manual page.

Use Review before install

Open the linked issues or discussions before treating the pack as ready for your environment.

Community Discussion Evidence

Doramagic exposes project-level community discussion separately from official documentation. Review these links before using trigger.dev with real data or production workflows.

Source: Project Pack community evidence and pitfall evidence