Base images

Start isolated work with Node.js, Python, Ruby, and common command-line tools already installed.

Open beta. Sandboxes are available on Pro plans and above. The Sandbox API, image, and limits may change. Use this beta for evaluation and feedback.

Run generated code or inspect a repository without building an image first. The beta Sandbox image includes Node.js, Python, Ruby, and common command-line tools. Check installed versions inside the Sandbox when your task depends on a specific version.

What the beta image includes

New Sandboxes start from this image unless you choose another. A Sandbox cloned from a snapshot starts with the captured image and filesystem changes.

ToolIncluded
Node.jsLatest release as node, npm, and npx; LTS release as node-lts, npm-lts, and npx-lts
PythonPython 3.14
RubyRuby 4.0
Repository and network toolsGit, curl, OpenSSH, and CA certificates
Operating system and utilitiesDebian 13 slim with GNU grep, sed, awk, find, diff, tar, and gzip, plus ripgrep and jq

The image does not currently include Go, Rust, Java, Bun, or Deno. Exact installed versions can change when Inngest rebuilds the image. Check versions in the Sandbox if your task depends on them.

Choose an image v4.25.0+

Pass from to start a Sandbox from an Inngest image or an image published to your workspace. image.inngest() and image.custom() are experimental and exported from inngest/experimental.

import { image } from "inngest/experimental";

await step.sandbox.create("build", {
  name: "build",
  vcpu: 2,
  memoryMb: 2048,
  from: image.inngest("base"),
});

await step.sandbox.create("custom", {
  name: "custom",
  vcpu: 2,
  memoryMb: 2048,
  from: image.custom("my-image:v1"),
});
  • Reference a custom image by name, name:tag, or name@sha256:<hex>. A name without a tag uses latest.
  • The image must already be published to your workspace. Create does not build or upload one.
  • Create resolves the image once. A retry of the same Sandbox keeps its original image, even if the tag has moved; use a new Sandbox name to pick up an update.
  • A Sandbox's imageRef and imageDigest show what it started from.
  • A snapshot clone keeps its source image and cannot select another.
  • inngest.sandboxes.create() takes the same from, or a plain image string such as "my-image:v1".
  • With REST, set "image": "my-image:v1" on POST /v2/sandboxes. To pin an exact artifact, use my-image@sha256:<digest> with its 64-character lowercase hexadecimal digest.

To build and publish your own application code, dependencies, or runtimes, follow Custom images.

Inspect the image

Run commands after the Sandbox reaches RUNNING. This example assumes you already have a Sandbox object from inngest.sandboxes.create():

const result = await sandbox.commands.run(
  "node --version && python3 --version && ruby --version && git --version",
  { timeout: "30s" },
);

console.log(result.stdout);
console.error(result.stderr);
console.log(result.exitCode);

Inside an Inngest function, use the same command through step.sandbox and give the operation a stable step ID:

const result = await sandbox.commands.run(
  "inspect-image",
  "node --version && python3 --version && ruby --version && git --version",
  { timeout: "30s" },
);

A nonzero exit code appears in the result. It does not throw an SDK error.

Add dependencies for a task

Install packages inside a running Sandbox when the task needs them. For example, create a project directory and install a Node package:

await sandbox.commands.run(
  "mkdir -p /tmp/project && cd /tmp/project && npm init -y && npm install lodash",
  { timeout: "5m" },
);

This changes that Sandbox, not the fixed base image. The files remain in the Sandbox across pause and resume. A snapshot captures its disk, so clones start with the installed files. Destroying the Sandbox removes its filesystem. User snapshots expire and are not permanent storage. For files shared across different Sandboxes, use S3-backed persistent filesystem mounts.

Choose a supported size

Fresh Sandboxes accept 1, 2, or 4 vCPU with 1, 2, or 4 GiB of memory per vCPU. memoryMb is measured in MiB:

vcpuAllowed memoryMb values
11024, 2048, 4096
22048, 4096, 8192
44096, 8192, 16384

Other sizes are not available. The API does not accept a size profile name. A snapshot clone inherits the snapshot's CPU and memory. Access or available capacity can still prevent a supported size from starting; missing capacity returns 503 compute_unavailable.