Machines

The machine configuration controls CPU and memory allocated to a task run. Higher specs cost more but improve performance for CPU/memory-bound tasks.

Machine Presets

Preset	vCPU	RAM	Disk
micro	0.25	0.25 GB	10 GB
small-1x (default)	0.5	0.5 GB	10 GB
small-2x	1	1 GB	10 GB
medium-1x	1	2 GB	10 GB
medium-2x	2	4 GB	10 GB
large-1x	4	8 GB	10 GB
large-2x	8	16 GB	10 GB

View pricing at trigger.dev/pricing.

Setting Machine on a Task

import { task } from "@trigger.dev/sdk";

export const heavyTask = task({
  id: "heavy-task",
  machine: "large-1x",
  run: async (payload, { ctx }) => { /* ... */ },
});

Global Default

Set default machine for all tasks in trigger.config.ts:

import type { TriggerConfig } from "@trigger.dev/sdk";

export const config: TriggerConfig = {
  machine: "small-2x",
};

Overriding at Trigger Time

Useful when specific payloads need more resources:

await tasks.trigger(
  "heavy-task",
  { message: "hello world" },
  { machine: "large-2x" }
);

Out-of-Memory (OOM) Errors

Error message: TASK_PROCESS_OOM_KILLED. Your run was terminated due to exceeding the machine's memory limit.

Auto-detected in:

• Node.js V8 heap limit exceeded
• Process exceeds machine memory limit
• Child process (e.g., ffmpeg) exceeds memory and exits with non-zero code

Throw Explicit OOM Error

import { task, OutOfMemoryError } from "@trigger.dev/sdk";

export const yourTask = task({
  id: "your-task",
  machine: "medium-1x",
  run: async (payload) => {
    // Detect OOM before it happens and throw explicitly
    throw new OutOfMemoryError();
  },
});

Auto-Retry with Larger Machine

export const yourTask = task({
  id: "your-task",
  machine: "medium-1x",
  retry: {
    outOfMemory: {
      machine: "large-1x", // only triggers on OOM, doesn't change default
    },
  },
  run: async (payload) => { /* ... */ },
});

Resource Monitoring

Log memory and CPU at regular intervals:

import { tasks } from "@trigger.dev/sdk";
import { ResourceMonitor } from "../resourceMonitor.js";

tasks.middleware("resource-monitor", async ({ ctx, next }) => {
  const resourceMonitor = new ResourceMonitor({ ctx });
  if (process.env.RESOURCE_MONITOR_ENABLED === "1") {
    resourceMonitor.startMonitoring(1_000); // every 1 second
  }
  await next();
  resourceMonitor.stopMonitoring();
});

Monitor a child process:

const monitor = new ResourceMonitor({ ctx, processName: "ffmpeg" });

Self-Hosting: Machine Overrides

Set MACHINE_PRESETS_OVERRIDE_PATH to a JSON file to customize machine specs:

{
  "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 }
  }
}