feat(runtime): add experimental Node.js 24 and 26 task runtimes (#4085)

## Summary

Adds experimental Node.js 24 and 26 task runtimes through the
`experimental-node-24` and `experimental-node-26` config values.

Existing runtime defaults and the `node`, `node-22`, and `bun` behavior
remain unchanged. The unprefixed `node-24` and `node-26` config values
remain unavailable until the runtimes are ready for general use.

## Design

Experimental config values normalize to canonical runtime identifiers
before build manifests are created, keeping deployment metadata and
execution behavior consistent. Kubernetes task pods also use the
runtime-default seccomp profile so modern Node.js versions fall back
from io_uring to checkpoint-compatible system calls.

Author: carderne

.changeset/experimental-node-runtimes.md

@@ -0,0 +1,6 @@
+---
+"@trigger.dev/core": patch
+"trigger.dev": patch
+---
+
+Add experimental Node.js 24 and 26 task runtimes. Set `runtime` to `experimental-node-24` or `experimental-node-26` in `trigger.config.ts`.

apps/supervisor/src/index.ts

@@ -120,6 +120,7 @@ class ManagedSupervisor {
       snapshotPollIntervalSeconds: env.RUNNER_SNAPSHOT_POLL_INTERVAL_SECONDS,
       additionalEnvVars: env.RUNNER_ADDITIONAL_ENV_VARS,
       dockerAutoremove: env.DOCKER_AUTOREMOVE_EXITED_CONTAINERS,
+      checkpointsEnabled: !!env.TRIGGER_CHECKPOINT_URL,
     } satisfies WorkloadManagerOptions;
 
     this.resourceMonitor = env.RESOURCE_MONITOR_ENABLED
@@ -615,6 +616,7 @@ class ManagedSupervisor {
         projectId: message.project.id,
         deploymentFriendlyId: message.deployment.friendlyId,
         deploymentVersion: message.backgroundWorker.version,
+        runtime: message.backgroundWorker.runtime,
         runId: message.run.id,
         runFriendlyId: message.run.friendlyId,
         version: message.version,

apps/supervisor/src/workloadManager/kubernetes.test.ts

@@ -0,0 +1,40 @@
+import { describe, expect, it } from "vitest";
+import {
+  BLOCK_IO_URING_SECCOMP_PROFILE,
+  withBlockIoUringSeccompProfile,
+} from "./kubernetesPodSpec.js";
+
+const basePodSpec = {
+  restartPolicy: "Never" as const,
+  automountServiceAccountToken: false,
+  securityContext: {
+    runAsNonRoot: true,
+    runAsUser: 1000,
+    fsGroup: 1000,
+  },
+};
+
+describe("withBlockIoUringSeccompProfile", () => {
+  it("adds the Localhost io_uring profile for node-24 and above, preserving pod security defaults", () => {
+    for (const runtime of ["node-24", "node-26", "node-30", "experimental-node-24"]) {
+      const podSpec = withBlockIoUringSeccompProfile(basePodSpec, runtime);
+
+      expect(podSpec).toMatchObject({
+        ...basePodSpec,
+        securityContext: {
+          ...basePodSpec.securityContext,
+          seccompProfile: {
+            type: "Localhost",
+            localhostProfile: BLOCK_IO_URING_SECCOMP_PROFILE,
+          },
+        },
+      });
+    }
+  });
+
+  it("leaves the pod spec unchanged for runtimes that do not create io_uring fds", () => {
+    for (const runtime of ["node", "node-22", "bun", undefined, null, ""]) {
+      expect(withBlockIoUringSeccompProfile(basePodSpec, runtime)).toEqual(basePodSpec);
+    }
+  });
+});

apps/supervisor/src/workloadManager/kubernetes.ts

@@ -14,6 +14,7 @@ import { PlacementTagProcessor } from "@trigger.dev/core/v3/serverOnly";
 import { env } from "../env.js";
 import { type K8sApi, createK8sApi, type k8s } from "../clients/kubernetes.js";
 import { getRunnerId } from "../util.js";
+import { withBlockIoUringSeccompProfile } from "./kubernetesPodSpec.js";
 
 type ResourceQuantities = {
   [K in "cpu" | "memory" | "ephemeral-storage"]?: string;
@@ -105,6 +106,11 @@ export class KubernetesWorkloadManager implements WorkloadManager {
     const runnerId = getRunnerId(opts.runFriendlyId, opts.nextAttemptNumber);
 
     try {
+      const basePodSpec = this.addPlacementTags(this.#defaultPodSpec, opts.placementTags);
+      const podSpec = this.opts.checkpointsEnabled
+        ? withBlockIoUringSeccompProfile(basePodSpec, opts.runtime)
+        : basePodSpec;
+
       await this.k8s.core.createNamespacedPod({
         namespace: this.namespace,
         body: {
@@ -119,7 +125,7 @@ export class KubernetesWorkloadManager implements WorkloadManager {
             },
           },
           spec: {
-            ...this.addPlacementTags(this.#defaultPodSpec, opts.placementTags),
+            ...podSpec,
             affinity: this.#getAffinity(opts),
             tolerations: this.#getScheduleTolerations(this.#isScheduledRun(opts)),
             terminationGracePeriodSeconds: 60 * 60,

apps/supervisor/src/workloadManager/kubernetesPodSpec.ts

@@ -0,0 +1,33 @@
+import type { k8s } from "../clients/kubernetes.js";
+
+/**
+ * Relative path (kubelet seccomp root) of the profile blocking only io_uring
+ * syscalls. Must match the profile deployed to worker nodes.
+ */
+export const BLOCK_IO_URING_SECCOMP_PROFILE = "profiles/block-io-uring.json";
+
+/**
+ * Node >= 24 always creates io_uring fds, which can't be checkpointed. Blocking
+ * io_uring_setup makes libuv fall back to epoll. Other runtimes don't need this,
+ * so the profile is only applied for node-24+. Tolerates an "experimental-" prefix.
+ */
+export function withBlockIoUringSeccompProfile(
+  podSpec: Omit<k8s.V1PodSpec, "containers">,
+  runtime: string | null | undefined
+): Omit<k8s.V1PodSpec, "containers"> {
+  const match = runtime ? /^(?:experimental-)?node-(\d+)$/.exec(runtime) : null;
+  if (!match || Number(match[1]) < 24) {
+    return podSpec;
+  }
+
+  return {
+    ...podSpec,
+    securityContext: {
+      ...podSpec.securityContext,
+      seccompProfile: {
+        type: "Localhost",
+        localhostProfile: BLOCK_IO_URING_SECCOMP_PROFILE,
+      },
+    },
+  };
+}

apps/supervisor/src/workloadManager/types.ts

@@ -16,6 +16,8 @@ export interface WorkloadManagerOptions {
   snapshotPollIntervalSeconds?: number;
   additionalEnvVars?: Record<string, string>;
   dockerAutoremove?: boolean;
+  // Whether CRIU checkpoint/restore is enabled for this deployment
+  checkpointsEnabled?: boolean;
 }
 
 export interface WorkloadManager {
@@ -40,6 +42,8 @@ export interface WorkloadManagerCreateOptions {
   projectId: string;
   deploymentFriendlyId: string;
   deploymentVersion: string;
+  // Canonical runtime identifier (e.g. "node", "node-22", "node-24")
+  runtime?: string;
   runId: string;
   runFriendlyId: string;
   snapshotId: string;

internal-packages/run-engine/src/engine/systems/dequeueSystem.ts

@@ -597,6 +597,7 @@ export class DequeueSystem {
                   id: result.worker.id,
                   friendlyId: result.worker.friendlyId,
                   version: result.worker.version,
+                  runtime: result.worker.runtime ?? undefined,
                 },
                 // TODO: use a discriminated union schema to differentiate between dequeued runs in dev and in deployed environments.
                 // Would help make the typechecking stricter

packages/cli-v3/src/commands/init.ts

@@ -94,7 +94,7 @@ Examples:
       )
       .option(
         "-r, --runtime <runtime>",
-        "Which runtime to use for the project. Currently only supports node and bun",
+        "Which runtime to use for the project. Supported: node, node-22, bun",
         "node"
       )
       .option("--skip-package-install", "Skip installing the @trigger.dev/sdk package")

packages/cli-v3/src/config.test.ts

@@ -0,0 +1,60 @@
+import { mkdtemp, mkdir, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, describe, expect, it } from "vitest";
+import { loadConfig } from "./config.js";
+
+const projectDirs: string[] = [];
+
+afterEach(async () => {
+  await Promise.all(projectDirs.splice(0).map((dir) => rm(dir, { recursive: true, force: true })));
+});
+
+async function createProject(runtime?: string) {
+  const cwd = await mkdtemp(join(tmpdir(), "trigger-runtime-config-"));
+  projectDirs.push(cwd);
+
+  await mkdir(join(cwd, "trigger"));
+  await writeFile(join(cwd, "package.json"), JSON.stringify({ name: "runtime-config-test" }));
+  await writeFile(join(cwd, "pnpm-lock.yaml"), "lockfileVersion: '9.0'\n");
+  await writeFile(
+    join(cwd, "trigger.config.ts"),
+    `export default {
+  project: "proj_runtime_config_test",
+  maxDuration: 60,
+  dirs: ["./trigger"],
+  ${runtime === undefined ? "" : `runtime: ${JSON.stringify(runtime)},`}
+};
+`
+  );
+
+  return cwd;
+}
+
+describe("loadConfig runtime", () => {
+  it.each([
+    ["experimental-node-24", "node-24"],
+    ["experimental-node-26", "node-26"],
+  ] as const)("normalizes %s before returning the resolved config", async (runtime, expected) => {
+    const cwd = await createProject(runtime);
+
+    await expect(loadConfig({ cwd, warn: false })).resolves.toMatchObject({ runtime: expected });
+  });
+
+  it("keeps node as the default", async () => {
+    const cwd = await createProject();
+
+    await expect(loadConfig({ cwd, warn: false })).resolves.toMatchObject({ runtime: "node" });
+  });
+
+  it.each(["node-24", "node-26", "node-23"])(
+    "rejects unsupported public runtime %s while loading config",
+    async (runtime) => {
+      const cwd = await createProject(runtime);
+
+      await expect(loadConfig({ cwd, warn: false })).rejects.toThrowError(
+        new RegExp(`Unsupported runtime "${runtime}" in trigger\\.config`)
+      );
+    }
+  );
+});

packages/cli-v3/src/config.ts

@@ -6,7 +6,11 @@ import type {
   TriggerConfig,
 } from "@trigger.dev/core/v3";
 import type { ResolvedConfig } from "@trigger.dev/core/v3/build";
-import { DEFAULT_RUNTIME } from "@trigger.dev/core/v3/build";
+import {
+  DEFAULT_RUNTIME,
+  isExperimentalConfigRuntime,
+  resolveBuildRuntime,
+} from "@trigger.dev/core/v3/build";
 import * as c12 from "c12";
 import { defu } from "defu";
 import type * as esbuild from "esbuild";
@@ -170,6 +174,24 @@ async function resolveConfig(
     );
   }
 
+  const config =
+    "config" in result.config ? (result.config.config as TriggerConfig) : result.config;
+
+  const features = featuresFromCompatibilityFlags(
+    ["run_engine_v2" as const].concat(config.compatibilityFlags ?? [])
+  );
+  const defaultRuntime: BuildRuntime = features.run_engine_v2 ? "node" : DEFAULT_RUNTIME;
+  const configuredRuntime = overrides?.runtime ?? config.runtime ?? defaultRuntime;
+  const runtime = resolveBuildRuntime(configuredRuntime);
+
+  if (warn && isExperimentalConfigRuntime(configuredRuntime)) {
+    prettyWarning(
+      `The "${configuredRuntime}" runtime is experimental and may change before general availability.`
+    );
+  }
+
+  validateConfig(config, warn);
+
   const packageJsonPath = await resolvePackageJSON(cwd);
   const tsconfigPath = await safeResolveTsConfig(cwd);
   const lockfilePath = await resolveLockfile(cwd);
@@ -181,24 +203,14 @@ async function resolveConfig(
       ? dirname(packageJsonPath)
       : cwd;
 
-  const config =
-    "config" in result.config ? (result.config.config as TriggerConfig) : result.config;
-
-  validateConfig(config, warn);
-
   let dirs = config.dirs ? config.dirs : await autoDetectDirs(workingDir);
 
   dirs = dirs.map((dir) => resolveTriggerDir(dir, workingDir));
 
-  const features = featuresFromCompatibilityFlags(
-    ["run_engine_v2" as const].concat(config.compatibilityFlags ?? [])
-  );
-
-  const defaultRuntime: BuildRuntime = features.run_engine_v2 ? "node" : DEFAULT_RUNTIME;
-
   const mergedConfig = defu(
     {
       workingDir,
+      runtime,
       configFile: result.configFile,
       packageJsonPath,
       tsconfigPath,
@@ -230,7 +242,7 @@ async function resolveConfig(
     ...mergedConfig,
     dirs: Array.from(new Set(dirs)),
     instrumentedPackageNames: getInstrumentedPackageNames(mergedConfig),
-    runtime: mergedConfig.runtime,
+    runtime,
   };
 }