@trigger.dev/sdk 0.0.0-python-preview-20250226140121 → 0.0.0-rc-4-8-0-20261021151928

package/docs/self-hosting/overview.mdx

@@ -0,0 +1,145 @@
+---
+title: "Self-hosting overview"
+sidebarTitle: "Overview"
+description: "You can self-host Trigger.dev on your own infrastructure."
+---
+
+Self-hosting Trigger.dev means you run and manage the platform on your own infrastructure, giving you full control over your environment, deployment process, and the URLs you expose the service on.
+
+You are responsible for provisioning resources, handling updates, and managing any security, scaling or reliability challenges that arise. See [Security & vulnerability reporting](/self-hosting/security) for how to report issues and stay informed about security releases.
+
+We provide version-tagged releases for self-hosted deployments. It's highly advised to use these tags exclusively and keep them locked with your CLI version.
+
+<Warning>
+  **v3 is end of life.** Trigger.dev 4.5.0 is the last version we officially support for running
+  v3 (SDK v3) tasks. If you still have v3 tasks, stay on 4.5.0 or [migrate to
+  v4](/migrating-from-v3). 4.5.1 and later reject v3 triggers, batch triggers, and deploys with an
+  upgrade message; v4 workloads are unaffected.
+</Warning>
+
+## Should you self-host?
+
+Trigger.dev Cloud is fully managed, scalable, and comes with dedicated support. For most users, it offers the best experience. However, if you have specific requirements around data residency, compliance, or infrastructure control, self-hosting may be the right choice for you.
+
+The self-hosted version is functionally the same as Trigger.dev Cloud with [some exceptions](#feature-comparison), but our managed Cloud infrastructure is designed for high availability, security, and scale.
+
+Because we don't manage self-hosted instances, we cannot guarantee how Trigger.dev will perform on your infrastructure. You assume all responsibility and risk for your deployment, including security, uptime, and data integrity.
+
+For more details, carry on reading and follow our guides for instructions on setting up a self-hosted Trigger.dev instance. If you prefer a managed experience, you can [sign up](https://cloud.trigger.dev/login) for our Cloud offering instead - we have a generous [free tier](https://trigger.dev/pricing) for you to try it out.
+
+## Architecture
+
+The self-hosted version is a set of containers running on your own infrastructure. It's split into two parts that can be scaled independently:
+
+- **Webapp**: includes the dashboard and other services like Redis and Postgres.
+- **Worker**: includes the supervisor and the runners that execute your tasks.
+
+![Self-hosting architecture](./architecture.png)
+
+## Feature comparison
+
+While [limits](#limits) are generally configurable when self-hosting, some features are only available on Trigger.dev Cloud:
+
+| Feature           | Cloud | Self-hosted | Description                             |
+| :---------------- | :---- | :---------- | :-------------------------------------- |
+| Warm starts       | ✅    | ❌          | Faster startups for consecutive runs    |
+| Auto-scaling      | ✅    | ❌          | No need for manual worker node scaling  |
+| Checkpoints       | ✅    | ❌          | Non-blocking waits, less resource usage |
+| Dedicated support | ✅    | ❌          | Direct access to our support team       |
+| Community support | ✅    | ✅          | Access to our Discord community         |
+| ARM support       | ✅    | ✅          | ARM-based deployments                   |
+
+
+## Limits
+
+Most of the [limits](/limits) are configurable when self-hosting, with some hardcoded exceptions. You can configure them via environment variables on the [webapp](/self-hosting/env/webapp) container.
+
+| Limit             | Configurable | Hardcoded value |
+| :---------------- | :----------- | :-------------- |
+| Concurrency       | ✅           | —               |
+| Rate limits       | ✅           | —               |
+| Queued tasks      | ✅           | —               |
+| Task payloads     | ✅           | —               |
+| Batch payloads    | ✅           | —               |
+| Task outputs      | ✅           | —               |
+| Batch size        | ✅           | —               |
+| Log size          | ✅           | —               |
+| Machines          | ✅           | —               |
+| OTel limits       | ✅           | —               |
+| Log retention     | —            | Never deleted   |
+| I/O packet length | ❌           | 128KB           |
+| Alerts            | ❌           | 100M            |
+| Schedules         | ❌           | 100M            |
+| Team members      | ❌           | 100M            |
+| Preview branches  | ❌           | 100M            |
+
+### Machine overrides
+
+You can override the machine type for a task by setting the `MACHINE_PRESETS_OVERRIDE_PATH` environment variable to a JSON file with the following structure.
+
+```json
+{
+  "defaultMachine": "small-1x",
+  "machines": {
+    "micro": { "cpu": 0.25, "memory": 0.25 },
+    "small-1x": { "cpu": 0.5, "memory": 0.5 },
+    "small-2x": { "cpu": 1, "memory": 1 }
+    // ...etc
+  }
+}
+```
+
+All fields are optional. Partial overrides are supported:
+
+```json
+{
+  "defaultMachine": "small-2x",
+  "machines": {
+    "small-1x": { "memory": 2 }
+  }
+}
+```
+
+## Custom base images
+
+Deploys build on the published `triggerdotdev/node` and `triggerdotdev/bun` Debian images. To require a different base for every deploy to your instance, such as a FIPS-validated or hardened Node image, set `DEPLOY_BASE_IMAGES` on the webapp (and optionally `DEPLOY_BUILD_BASE_IMAGES` for the build stage):
+
+```bash
+DEPLOY_BASE_IMAGES="node-26=registry.example.com/node-fips:26@sha256:<64-character-digest>"
+```
+
+Entries are comma-separated `runtime=image@sha256:<digest>`. The runtimes are `node-22`, `node-24`, `node-26` and `bun`, and every image must be pinned by digest. An invalid value prevents the webapp from starting. Projects with `runtime: "node"` in their config resolve to the current default Node runtime (`node-24` today), so set that key for them. With the Helm chart, set the variables through `webapp.extraEnvVars`.
+
+Runtimes with an entry build on that image; the others keep the published images. Deploys from CLI versions that cannot apply the images are rejected with an error asking to upgrade, and so are `--native-build`, `--local-bundle` and `--from-bundle` deploys. This is a self-hosting setting and does not apply to Trigger.dev Cloud.
+
+You own a custom base image. It must provide:
+
+- `node` on `PATH` at the runtime's major version (for `bun`, both `bun` and `node`, because the final stage starts the app with `dumb-init node`)
+- `busybox`, `ca-certificates`, `dumb-init`, `git` and `openssl`
+- a `node` user (a `bun` user for the Bun runtime)
+- glibc, so native modules built in the build stage load at runtime
+
+A `DEPLOY_BUILD_BASE_IMAGES` image needs everything the base image provides, plus `python3`, `make` and `g++`. Build extensions that add image instructions are replayed on it. Without an entry, the build stage uses the published build image, except for projects whose build extensions add image instructions: those build from your base image and install the toolchain with `apt-get`, so that base must be Debian-based. To avoid the published images entirely, set both variables.
+
+<Warning>
+  `image.pkgs` and build extensions that run `apt-get` (such as `aptGet` and `playwright`) assume a
+  Debian base. On other distributions, install those packages in your base image instead.
+</Warning>
+
+## Community support
+
+It's dangerous to go alone! Join the self-hosting channel on our [Discord server](https://discord.gg/NQTxt5NA7s).
+
+## Next steps
+
+<CardGroup>
+  <Card title="Docker compose" color="#2496ED" icon="docker" href="/self-hosting/docker">
+    Learn how to self-host Trigger.dev with Docker compose.
+  </Card>
+  <Card title="Kubernetes" color="#326CE5" icon="dharmachakra" href="/self-hosting/kubernetes">
+    Learn how to self-host Trigger.dev with Kubernetes.
+  </Card>
+  <Card title="Security" icon="shield-halved" href="/self-hosting/security">
+    Report vulnerabilities and stay informed about security releases.
+  </Card>
+</CardGroup>

package/docs/self-hosting/security.mdx

@@ -0,0 +1,67 @@
+---
+title: "Security & vulnerability reporting"
+description: "How to report security issues in Trigger.dev, our response targets, and how self-hosters receive security notices."
+sidebarTitle: "Security"
+---
+
+We take the security of Trigger.dev seriously, for both Cloud and self-hosted deployments. This page covers how to report a vulnerability, what to expect, and how to stay informed about security releases.
+
+<Note>
+  Unlike Trigger.dev Cloud, the self-hosted setup is optimized for single-tenant use, with code and
+  users you trust. It is not designed to run untrusted code or untrusted payloads.
+</Note>
+
+<Warning>
+  Do not report security vulnerabilities through public GitHub issues, pull requests, or Discord. Use one of the private channels below.
+</Warning>
+
+## What is in scope
+
+A self-hosted deployment is a single trust domain: as above, it is built for code and users you trust. Role separation inside an organization is therefore not a security boundary there. Role-based access control comes from a plugin that is not part of the open-source distribution, and without it the permission layer falls back to a permissive ability for session users and personal access tokens. That is deliberate.
+
+**Out of scope for self-hosted:** a member of an organization performing a privileged action inside that same organization, such as renaming or deleting the organization or managing other members. Control who you invite, or use Cloud, if you need that separation.
+
+**In scope from any deployment:** reaching data or actions belonging to an organization the caller is not a member of, or bypassing authentication. Organization is a hard boundary on Trigger.dev Cloud, and Cloud runs this same code, so report these even though your own install is single-tenant.
+
+Tell us which deployment you tested against. The same report can be out of scope for self-hosting and in scope for Cloud.
+
+The [security policy](https://github.com/triggerdotdev/trigger.dev/blob/main/SECURITY.md) is canonical.
+
+## Reporting a vulnerability
+
+<Steps>
+  <Step title="Choose a private channel">
+    - **GitHub (preferred):** open a private report from the repository's **Security** tab using **"Report a vulnerability"** ([direct link](https://github.com/triggerdotdev/trigger.dev/security/advisories/new)).
+    - **Email:** `security@trigger.dev`
+  </Step>
+  <Step title="Include the details">
+    A description and impact, steps to reproduce (a proof of concept helps), affected versions/components, and any suggested fix.
+  </Step>
+  <Step title="We track it privately">
+    Every report is tracked in a private GitHub Security Advisory. If you email us, we open the advisory on your behalf.
+  </Step>
+</Steps>
+
+## What to expect
+
+| Stage | Target |
+| --- | --- |
+| Acknowledgement | within 3 business days |
+| Validation + CVSS 3.1 severity assessment | within 1 week |
+
+We score issues with CVSS 3.1 and prioritise remediation by severity:
+
+| Severity (CVSS 3.1) | Target time to resolve |
+| --- | --- |
+| Critical (9.0–10.0) | 7 days |
+| High (7.0–8.9) | 30 days |
+| Medium (4.0–6.9) | 90 days |
+| Low (0.1–3.9) | As needed |
+
+<Note>
+  These are best-effort targets measured from when we validate and accept a report, not guarantees. We follow coordinated disclosure with a default 90-day window, and publish a GitHub Security Advisory (requesting a CVE where applicable) once a fix ships.
+</Note>
+
+## Supported versions
+
+We patch the **latest released version line** only. Run the latest version-tagged release to receive security fixes — see [Self-hosting overview](/self-hosting/overview).

package/docs/skills.mdx

@@ -0,0 +1,85 @@
+---
+title: "Skills"
+description: "Install Trigger.dev agent skills to teach any AI coding assistant how to write tasks, realtime frontends, and chat.agent AI agents."
+sidebarTitle: "Skills"
+---
+
+## What are agent skills?
+
+Skills are portable instruction sets that teach AI coding assistants how to use Trigger.dev effectively. Unlike vendor-specific config files (`.cursor/rules`, `CLAUDE.md`), skills use an open standard that works across all major AI assistants, so Cursor users and Claude Code users get the same knowledge from a single install.
+
+Each skill is a directory containing a `SKILL.md` file: YAML frontmatter (name, description) plus markdown instructions with patterns, examples, and common mistakes that AI assistants discover on demand and follow.
+
+<Note>
+  Skills pair with the [MCP Server](/mcp-introduction), which gives your assistant live access to
+  your project (deploy, trigger, monitor). Skills teach it how to write the code; the MCP server
+  lets it act on your project. See [how they fit together](/building-with-ai#skills-and-the-mcp-server).
+</Note>
+
+## Installation
+
+Run the installer with the CLI:
+
+```bash
+npx trigger.dev@latest skills
+```
+
+The CLI detects your installed AI tools, lets you pick which skills to install, and writes each one into that tool's native skills directory (`.claude/skills/`, `.cursor/skills/`, `.github/skills/`, `.agents/skills/`). It also adds a one-line pointer to your primary instructions file (`CLAUDE.md`, `.cursor/rules`, etc.) so your assistant always knows the skills are there and loads the right one on demand.
+
+When you run `trigger dev` for the first time, the CLI offers to install the skills for you.
+
+The installed skills are lightweight. Most point to the full, version-pinned reference that ships inside `@trigger.dev/sdk`, which your assistant reads straight from `node_modules`. The API guidance it follows always matches the `@trigger.dev/sdk` version installed in your project, with no extra step on your part. The `trigger-getting-started` skill is self-contained, since it runs before the SDK is installed.
+
+### Non-interactive install
+
+Pass `--target` to choose tools and `-y` to install every skill without prompting (useful in scripts and CI):
+
+```bash
+npx trigger.dev@latest skills --target claude-code --target cursor -y
+```
+
+## Available skills
+
+| Skill                  | Use for                                                        | Covers                                                                       |
+| ---------------------- | -------------------------------------------------------------- | ---------------------------------------------------------------------------- |
+| `trigger-authoring-tasks`      | Writing background and scheduled tasks                         | `task`/`schemaTask`, retries, queues, waits, idempotency, metadata, triggering, cron, `trigger.config.ts` |
+| `trigger-realtime-and-frontend`| Live run updates and triggering from the browser               | `runs.subscribeToRun`, `@trigger.dev/react-hooks`, public access tokens, streams |
+| `trigger-authoring-chat-agent` | Building durable AI chat agents                                | `chat.agent` run loop, `toStreamTextOptions`, server actions, `useChat` transport, tools, lifecycle hooks |
+| `trigger-chat-agent-advanced`  | Advanced chat.agent patterns                                   | sessions, human-in-the-loop, sub-agents, compaction, fast starts, resilience, version upgrades |
+| `trigger-cost-savings`         | Auditing and reducing compute spend                            | right-sizing machines, `maxDuration`, batch vs sequential, debounce, schedule frequency, MCP run analysis |
+
+Not sure which to install? Pick `trigger-authoring-tasks`; it covers the most common patterns for writing Trigger.dev tasks.
+
+## Supported AI assistants
+
+Skills use the open [Agent Skills standard](https://agentskills.io). The CLI installs natively into the tools that support a skills directory today:
+
+| Assistant | Installs to |
+| --- | --- |
+| [Claude Code](https://docs.anthropic.com/en/docs/claude-code) | `.claude/skills/` |
+| [Cursor](https://cursor.com) | `.cursor/skills/` |
+| [GitHub Copilot (VS Code)](https://github.com/features/copilot) | `.github/skills/` |
+| [Codex CLI](https://github.com/openai/codex), Jules, OpenCode | `.agents/skills/` |
+
+Using a tool that does not support skills yet? Select "Unsupported target" in the installer for manual setup instructions.
+
+## Keeping skills updated
+
+The API guidance updates on its own: it lives in `@trigger.dev/sdk` and is read from `node_modules`, so upgrading the SDK in your project upgrades the guidance with it. Re-run `npx trigger.dev@latest skills` (or accept the prompt that `trigger dev` shows when a newer version is available) only to add skills or refresh the installed pointer files. Re-running overwrites them in place without creating duplicates.
+
+## Next steps
+
+<CardGroup cols={2}>
+  <Card title="MCP Server" icon="sparkles" href="/mcp-introduction">
+    Give your AI assistant direct access to Trigger.dev tools and APIs.
+  </Card>
+  <Card title="Building with AI" icon="layer-group" href="/building-with-ai">
+    See how skills and the MCP server compare, plus a copy-paste context snippet.
+  </Card>
+  <Card title="Writing tasks" icon="code" href="/tasks/overview">
+    Learn the task patterns that skills teach your AI assistant.
+  </Card>
+  <Card title="AI agents" icon="robot" href="/ai-chat/overview">
+    Build durable chat agents with chat.agent, the focus of two of the skills.
+  </Card>
+</CardGroup>

package/docs/tags.mdx

@@ -0,0 +1,126 @@
+---
+title: "Tags"
+description: "Tags allow you to easily filter runs in the dashboard and when using the SDK."
+---
+
+## What are tags?
+
+We support up to 10 tags per run. Each one must be a string between 1 and 128 characters long.
+
+We recommend prefixing your tags with their type and then an underscore or colon. For example, `user_123456` or `video:123`.
+
+<Info>
+  Many great APIs, like Stripe, already prefix their IDs with the type and an underscore. Like
+  `cus_123456` for a customer.
+</Info>
+
+We don't enforce prefixes but if you use them you'll find it easier to filter and it will be clearer what the tag represents.
+
+## How to add tags
+
+There are two ways to add tags to a run:
+
+1. When triggering the run.
+2. Inside the `run` function, using `tags.add()`.
+
+### 1. Adding tags when triggering the run
+
+You can add tags when triggering a run using the `tags` option. All the different [trigger](/triggering) methods support this.
+
+<CodeGroup>
+
+```ts trigger
+const handle = await myTask.trigger(
+  { message: "hello world" },
+  { tags: ["user_123456", "org_abcdefg"] }
+);
+```
+
+```ts batchTrigger
+const batch = await myTask.batchTrigger([
+  {
+    payload: { message: "foo" },
+    options: { tags: "product_123456" },
+  },
+  {
+    payload: { message: "bar" },
+    options: { tags: ["user_123456", "product_3456789"] },
+  },
+]);
+```
+
+</CodeGroup>
+
+This will create a run with the tags `user_123456` and `org_abcdefg`. They look like this in the runs table:
+
+![How tags appear in the dashboard](/images/tags-org-user.png)
+
+### 2. Adding tags inside the `run` function
+
+Use the `tags.add()` function to add tags to a run from inside the `run` function. This will add the tag `product_1234567` to the run:
+
+```ts
+import { task, tags } from "@trigger.dev/sdk";
+
+export const myTask = task({
+  id: "my-task",
+  run: async (payload: { message: string }, { ctx }) => {
+    // Get the tags from when the run was triggered using the context
+    // This is not updated if you add tags during the run
+    logger.log("Tags from the run context", { tags: ctx.run.tags });
+
+    // Add tags during the run (a single string or array of strings)
+    await tags.add("product_1234567");
+  },
+});
+```
+
+Reminder: you can only have up to 10 tags per run. If you call `tags.add()` and the total number of tags will be more than 10 we log an error and ignore the new tags. That includes tags from triggering and from inside the run function.
+
+### Propagating tags to child runs
+
+Tags do not propagate to child runs automatically. By default runs have no tags and you have to set them explicitly.
+
+It's easy to propagate tags if you want:
+
+```ts
+export const myTask = task({
+  id: "my-task",
+  run: async (payload: Payload, { ctx }) => {
+    // Pass the tags from ctx into the child run
+    const { id } = await otherTask.trigger(
+      { message: "triggered from myTask" },
+      { tags: ctx.run.tags }
+    );
+  },
+});
+```
+
+## Filtering runs by tags
+
+You can filter runs by tags in the dashboard and in the SDK.
+
+### In the dashboard
+
+On the Runs page open the filter menu, choose "Tags" and then start typing in the name of the tag you want to filter by. You can select it and it will restrict the results to only runs with that tag. You can add multiple tags to filter by more than one.
+
+![Filter by tags](/images/tags-filtering.png)
+
+### Using `runs.list()`
+
+You can provide filters to the `runs.list` SDK function, including an array of tags.
+
+```ts
+import { runs } from "@trigger.dev/sdk";
+
+// Loop through all runs with the tag "user_123456" that have completed
+for await (const run of runs.list({ tag: "user_123456", status: ["COMPLETED"] })) {
+  console.log(run.id, run.taskIdentifier, run.finishedAt, run.tags);
+}
+```
+
+<Tip>
+  To follow runs with a tag as they change, use
+  [`runs.subscribeToRunsWithTag()`](/realtime/backend/subscribe) instead of polling `runs.list()`.
+  See [runs.list() best practices](/runs/list-best-practices).
+</Tip>