trigger.dev

Defines workflow tasks using a TypeScript-first SDK that compiles task definitions into a schema-aware registry, enabling static type checking across task inputs/outputs and automatic serialization of complex types. The Task Definition API creates tasks as first-class objects with built-in support for retries, timeouts, and concurrency limits, stored in a workerCatalog that the run engine references during execution.

Executes tasks across distributed workers using a state machine-driven run engine that persists execution checkpoints to enable resumption after failures or long-running operations. The checkpoint system captures execution state at defined points (waitpoints), allowing tasks to pause, wait for external events, and resume without re-executing completed work. Implemented via the Run Engine Architecture with dedicated checkpointSystem and waitpointSystem components that manage state transitions.

Implements distributed locking via Redis to prevent concurrent execution of the same task or conflicting state transitions. Uses Redis EVAL scripts for atomic lock acquisition and release, ensuring exactly-once semantics across multiple coordinator instances. Concurrency management system enforces per-task concurrency limits (e.g., max 5 concurrent executions), with queuing of excess requests. Prevents race conditions in checkpoint updates and dequeue operations.

Provides lifecycle hooks (onStart, onSuccess, onFailure, onRetry) that execute custom code before task execution, after success, after failure, or before retry attempts. Hooks are defined in task configuration and executed by the run engine as part of the run state machine. Enables cross-cutting concerns like metrics emission, notification sending, or resource cleanup without modifying task code. Hooks have access to task context and execution metadata.

Allows developers to define custom build extensions that transform task code during compilation, enabling code generation, instrumentation, or optimization. Build extensions hook into the Turborepo build system and can modify task definitions before they're registered in the workerCatalog. Enables use cases like automatic OpenTelemetry instrumentation, code splitting, or custom serialization logic without manual implementation.

Automatically expires and cleans up old task runs based on configurable TTL (time-to-live) policies, freeing database storage and improving query performance. The TTL system (ttlSystem component) periodically scans for expired runs and marks them for deletion. Supports per-environment TTL configuration (e.g., dev runs expire after 7 days, prod runs after 90 days). Deleted runs are archived to cold storage before permanent deletion.

Routes task execution across multiple compute providers (Docker, Kubernetes, serverless) using a provider abstraction layer that abstracts provider-specific deployment details. The dequeue system polls task queues managed by Redis, applies concurrency limits and rate limiting per task, and dispatches work to available workers based on provider capacity and task affinity. Queue management uses distributed locking to ensure exactly-once dequeue semantics across multiple coordinator instances.

Manages task execution lifecycle through a deterministic state machine (defined in runEngine.server.ts and statuses.ts) that transitions runs through states: PENDING → QUEUED → EXECUTING → COMPLETED/FAILED/RETRYING. Implements automatic retry logic with exponential backoff, configurable retry limits per task, and error categorization to distinguish transient vs permanent failures. Failed runs trigger the retryAttemptSystem which re-enqueues work based on retry policies.

Provides real-time visibility into task execution through OpenTelemetry integration that emits traces, metrics, and logs to external observability backends. The web application subscribes to execution updates via bidirectional streams (WebSocket or Server-Sent Events), displaying live run status, execution logs, and performance metrics. ClickHouse integration enables analytics queries on historical execution data, while Redis pub/sub broadcasts state changes to all connected clients.

Exposes Trigger.dev tasks as Model Context Protocol (MCP) tools that AI agents can invoke directly, with automatic schema generation from TypeScript task definitions. The MCP server translates agent tool calls into task invocations, handles result streaming back to the agent, and manages authentication via API keys. Enables AI agents (Claude, GPT-4) to trigger workflows and wait for results as part of their reasoning loop.

Triggers multiple task instances in a single operation and provides atomic wait-for-all semantics, allowing workflows to batch-trigger N tasks and wait for all to complete before proceeding. Implemented via batchTriggerAndWait system that enqueues all tasks atomically, then uses the waitpoint system to pause the parent task until all child tasks complete. Prevents partial batch execution and ensures consistent batch semantics across failures.

Manages environment-specific configuration (API keys, database URLs, feature flags) through an Environment model that isolates settings per deployment environment (dev, staging, prod). Secrets are encrypted at rest in the database and injected into task execution context at runtime. Environment switching is enforced at the project level, preventing accidental cross-environment data leaks. Integrates with the web application's Environment Management UI for non-technical configuration.

Provides a command-line interface (CLI) for local development that runs a local coordinator and worker, enabling developers to test tasks without cloud deployment. CLI commands include `trigger dev` (local execution), `trigger deploy` (push to cloud), and `trigger logs` (stream execution logs). The CLI uses the same task definition and execution engine as production, ensuring dev/prod parity. Supports hot-reloading of task code during local development.

Provides a web application (built with Remix/React) that displays task runs with real-time status updates, execution logs, and performance metrics. The dashboard subscribes to run updates via WebSocket/SSE streams, displays live execution progress, and allows filtering/searching runs by status, task name, or date range. Organization and project management UI enables multi-tenant isolation and team collaboration. Integrates with authentication system for role-based access control.