This document describes the provider architecture components of Trigger.dev: the Coordinator, Docker Provider, Kubernetes Provider, and Supervisor v4 applications. These applications work together to orchestrate task execution in containers across different infrastructure environments.
For information about task execution orchestration and state management, see Task Execution Engine. For deployment pipeline details, see Deployment Pipeline.
The provider architecture consists of four main applications that handle task execution infrastructure:
Sources: apps/webapp/app/entry.server.tsx1-258 pnpm-lock.yaml113-211
| Component | Primary Role | Infrastructure | Communication Protocol |
|---|---|---|---|
| Coordinator | Central orchestration hub for worker lifecycle management | Standalone service | Socket.IO (bidirectional) |
| Docker Provider | Local development execution using Docker | Local Docker daemon | Process execution via execa |
| Kubernetes Provider | Cloud production execution using Kubernetes | Kubernetes cluster | Kubernetes API client |
| Supervisor v4 | Task container runtime manager | Runs inside task containers | Socket.IO to Coordinator |
Sources: pnpm-lock.yaml113-211
The Coordinator serves as the central Socket.IO server that manages the lifecycle of task execution workers. It receives execution requests from the webapp's RunEngine and coordinates with providers to create, monitor, and terminate worker containers.
Location: apps/coordinator
Sources: pnpm-lock.yaml113-139
Sources: pnpm-lock.yaml113-139 apps/coordinator/tsconfig.json1-16
The Coordinator uses path mapping to reference the core v3 APIs directly from the monorepo source.
Sources: apps/coordinator/tsconfig.json1-16
The Coordinator connects to the webapp through Socket.IO. The webapp's Express server handles Socket.IO upgrade requests:
Sources: apps/webapp/server.ts228-244
The Docker Provider enables local development by executing tasks in Docker containers on the developer's machine. It provides a lightweight alternative to Kubernetes for the trigger dev workflow.
Location: apps/docker-provider
The Docker Provider uses execa 8.0.1 for spawning and managing Docker CLI processes. This provides:
Sources: pnpm-lock.yaml141-158
execaSources: pnpm-lock.yaml141-158 apps/docker-provider/tsconfig.json1-16
Sources: apps/docker-provider/tsconfig.json1-16
Sources: pnpm-lock.yaml141-158
The Kubernetes Provider manages task execution in Kubernetes clusters for production environments. It creates and manages pods, handles resource allocation, and integrates with Kubernetes-native monitoring.
Location: apps/kubernetes-provider
The Kubernetes Provider uses a patched version of @kubernetes/client-node to fix specific issues with the upstream library.
Sources: pnpm-lock.yaml160-180 package.json76-84
The codebase applies a custom patch to @kubernetes/client-node@1.0.0:
patchedDependencies:
"@kubernetes/client-node@1.0.0":
hash: ba1a06f46256cdb8d6faf7167246692c0de2e7cd846a9dc0f13be0137e1c3745
path: patches/@kubernetes__client-node@1.0.0.patch
Sources: package.json81 pnpm-lock.yaml28-30
Sources: pnpm-lock.yaml160-180 apps/kubernetes-provider/tsconfig.json1-18
The Kubernetes Provider includes a sophisticated label management system for annotating resources with custom metadata:
Sources: apps/kubernetes-provider/src/labelHelper.ts1-154
The CustomLabelHelper class provides flexible label management:
Key Features:
Environment Variable Format:
Sources: apps/kubernetes-provider/src/labelHelper.ts1-154
Note: The Kubernetes Provider has broader path mappings than other providers, including access to all of @trigger.dev/core, not just v3.
Sources: apps/kubernetes-provider/tsconfig.json1-18
The Supervisor v4 is the runtime component that runs inside each task container. It manages the task execution lifecycle, handles Socket.IO communication back to the Coordinator, and interfaces with both Docker and Kubernetes environments.
Location: apps/supervisor
Sources: pnpm-lock.yaml182-211
The Supervisor runs in both Docker and Kubernetes environments, requiring dual infrastructure clients:
| Dependency | Purpose | Version |
|---|---|---|
dockerode | Docker daemon API client for local development | 4.0.6 |
@kubernetes/client-node | Kubernetes API client for cloud execution | 1.0.0 (patched) |
@aws-sdk/client-ecr | Pull container images from AWS ECR | 3.839.0 |
Sources: pnpm-lock.yaml182-211
Sources: pnpm-lock.yaml182-211
Sources: pnpm-lock.yaml182-211
Like the Kubernetes Provider, the Supervisor uses a patched version of the Kubernetes client:
"@kubernetes/client-node@1.0.0":
version: 1.0.0(patch_hash=ba1a06f46256cdb8d6faf7167246692c0de2e7cd846a9dc0f13be0137e1c3745)
This ensures consistent behavior across both the provider (which creates pods) and the supervisor (which runs inside pods).
Sources: pnpm-lock.yaml188-189 package.json81
The platform determines which provider to use based on the environment:
Sources: High-level system architecture diagrams
The webapp integrates with the provider architecture through several mechanisms:
Sources: apps/webapp/app/entry.server.tsx236-243 apps/webapp/server.ts225-243
The Express server in the webapp handles Socket.IO attachment and upgrade handling:
Sources: apps/webapp/server.ts225-263
The entry.server.tsx file initializes the provider architecture integration:
Sources: apps/webapp/app/entry.server.tsx236-243
All provider applications use a consistent build setup:
| Application | Builder | Target | Output Format |
|---|---|---|---|
| Coordinator | esbuild 0.19.11 | es2020 | CommonJS |
| Docker Provider | esbuild 0.19.11 | es2020 | CommonJS |
| Kubernetes Provider | esbuild 0.19.11 | es2020 | CommonJS |
| Supervisor v4 | (bundled in container) | es2020 | CommonJS |
Sources: pnpm-lock.yaml134-180
Each provider supports local development with hot reload:
All use tsx for TypeScript execution and dotenv for environment variable management.
Sources: pnpm-lock.yaml132-180
The monorepo build system coordinates provider builds:
Sources: turbo.json1-115
The webapp supports cluster mode for horizontal scaling, which affects how it communicates with the Coordinator:
Sources: apps/webapp/server.ts18-89
The provider architecture implements a layered approach to task execution:
This architecture enables:
Sources: pnpm-lock.yaml113-211 apps/webapp/server.ts1-269 apps/webapp/app/entry.server.tsx1-258
Refresh this wiki