The Problem

Developers need a platform that can run long‑lived, retry‑able AI tasks while keeping observability, queueing and human‑in‑the‑loop capabilities. Typical serverless runtimes impose hard timeouts and lack durable state, forcing teams to stitch together ad‑hoc solutions.

What This Does

trigger.dev is an open‑source suite that supplies a TypeScript SDK, a supervisor service, and a React‑based web UI. The core runtime lives in apps/supervisor (apps/supervisor/src/index.ts, apps/supervisor/src/workloadServer/index.ts) and manages task execution, persistence and socket streaming. The front‑end in apps/webapp provides hooks such as useOrganization, useProject, and UI components for run filtering, all built with React and Vite (apps/webapp/vite.config.ts). Shared utilities (e.g., database wrappers, cache, clickhouse client) are in internal-packages, while reusable UI primitives and SDK code sit in packages. Docker support (docker/Dockerfile, docker/.env.example) and a GitHub Actions CI pipeline are already present.

How It Is Wired

Execution starts at apps/supervisor/src/index.ts (function start). It creates the workload server (createWorkload) and registers the HTTP and socket routers. A request from the UI hits handler in apps/webapp/app/hooks/useEventSource.tsx, which ultimately calls wideRoute (apps/supervisor/src/workloadServer/index.ts:231). wideRoute dispatches to runWideEvent, which emits a payload via emit → buildPayload. The payload construction includes a cryptographic call (randomBytes) before the data is sent over a WebSocket (emitSocketLifecycle → newRequestId).

Database interaction is concentrated in apps/webapp/app/db.server.ts (19 functions, e.g., $transaction) and the Vercel integration model (apps/webapp/app/models/vercelIntegration.server.ts). These are the only modules that read/write the persistent store, accounting for 41 functions that touch the DB across the repo.

The most widely referenced hooks are useSearchParams (66 callers) and useOrganization (43 callers); they live in apps/webapp/app/hooks/useSearchParam.ts and apps/webapp/app/hooks/useOrganizations.ts. UI components such as RunFilters.tsx and SideMenu.tsx drive the front‑end but do not directly affect external side‑effects.

The internal call graph shows a hub around extractAISpanData (22 → num, 20 → rec, 17 → str) and TaskRunStatusIcon (16 → runStatusClassNameColor). These functions have the broadest blast radius because many UI modules depend on them for rendering AI run details.

How To Use It

# Clone the repo
git clone https://github.com/moses-y/trigger.dev
cd trigger.dev

# Install dependencies (pnpm workspace)
pnpm install

# Build the supervisor and webapp containers (Dockerfile present)
docker compose -f docker/docker-compose.yml up --build

Configuration – copy the example env files, e.g.:

cp .env.example .env               # root
cp apps/supervisor/.env.example apps/supervisor/.env
cp docker/.env.example docker/.env

Set the required keys (database URL, ClickHouse host, etc.) as described in the .env.example files.

Run the platform – the supervisor launches automatically from the Docker compose stack; the web UI is served on the port defined in docker/.env.example (default 3000).

Local development – start the supervisor and webapp directly:

pnpm --filter supervisor dev   # runs apps/supervisor/src/index.ts
pnpm --filter webapp dev       # runs Vite dev server

Real‑World Use

A SaaS product can define an AI task with the SDK (@trigger.dev/sdk) that calls an external LLM, stores partial results in the ClickHouse cache, and pauses for user approval via the humanInTheLoop API. When the task is triggered from the web UI, the supervisor queues the job, retries on failure, and streams incremental responses back to the React front‑end through the socket layer described above.

Code Health & Issues

  • High – Untracked .env – apps/webapp/.env is tracked despite .gitignore; remove with git rm --cached and rotate credentials.
  • High – Committed secret env files – Same issue across hosting/docker/webapp/.env, hosting/docker/worker/.env, internal-packages/database/.env. Delete from history and replace with examples.
  • High – CI never runs tests – GitHub Actions workflows lack a test step; add pnpm test to the existing job.
  • Medium – No dependency vulnerability scan – Add dependency-review-action or osv-scanner to PR workflow.
  • Medium – No pre‑commit secret gate – Install a pre‑commit hook (e.g., detect-secrets) and enable push protection.
  • Low – Missing job timeouts – Set timeout-minutes in .github/workflows/helm-prerelease.yml.
  • Low – Missing repo conventions – Add .editorconfig, .gitattributes and a formatter config (e.g., Prettier).

The repository includes a full test suite (816 files) and a Dockerfile, but the CI pipeline does not currently execute the tests, reducing confidence in automated quality gates.

The Bottom Line

trigger.dev provides a comprehensive, TypeScript‑first runtime for durable AI workflows, with a clear separation between supervisor, web UI, and shared libraries. The codebase is sizable and well‑structured, but secret leakage and gaps in CI compromise security and reliability. Teams that need a self‑hosted, extensible AI task platform can adopt it quickly, provided they address the high‑severity health issues first.