Managed lifecycle

Coordinate Sandbox creation, commands, and cleanup as durable steps in a function run.

Open beta. Sandboxes are available on Pro plans and above. The low-level TypeScript API below follows the Sandbox beta. The one-call step.sandbox.python and step.sandbox.typescript runners are experimental.

Use durable Sandbox steps when isolated code belongs to a longer function run. Inngest records each operation’s result, so a resumed function can continue after completed steps. The API you choose determines which lifecycle and cleanup actions your function must handle.

APIWhat Inngest handlesWhat you handle
step.sandbox.create() and other low-level stepsDurable operation results, safe retries, readiness polling by default, and step failuresWhen to pause, resume, snapshot, clone, and destroy the Sandbox; cleanup after permanent failure
inngest.sandboxesImmediate Sandbox requests and bounded readiness pollingRetries, cancellation, and cleanup in your server process
step.sandbox.python and step.sandbox.typescript (experimental)Creates a Sandbox, runs your code, returns the result, and destroys the Sandbox in one callNothing to clean up; pass input, schema, and tools

Use a Sandbox in a durable function

Add the Sandbox middleware to a TypeScript v4 client. Each step.sandbox operation takes a stable step ID. This example creates a Sandbox, runs a command, and destroys the Sandbox on the successful path.

import { Inngest } from "inngest";
import { sandboxMiddleware } from "inngest/experimental";

const inngest = new Inngest({
  id: "sandbox-lifecycle",
  middleware: [sandboxMiddleware()],
});

export const runInSandbox = inngest.createFunction(
  {
    id: "run-in-sandbox",
    triggers: { event: "sandbox/job.requested" },
  },
  async ({ event, step }) => {
    const sandbox = await step.sandbox.create("create-sandbox", {
      name: `job-${event.data.jobId}`,
      vcpu: 1,
      memoryMb: 1024,
      runningTimeout: "60s",
    });

    const result = await sandbox.commands.run(
      "run-command",
      ["node", "-e", "console.log('done')"],
      { timeout: "30s" },
    );

    await sandbox.destroy("destroy-sandbox");

    return { exitCode: result.exitCode, stdout: result.stdout };
  },
);

Use a stable, Sandbox-safe job ID in the event. A completed step replays its result, including the Sandbox object returned by Create. This avoids creating another Sandbox when the function resumes after a later step. It does not keep the guest process or filesystem alive if the Sandbox itself is lost.

Create waits for RUNNING by default. If readiness times out, the Sandbox may still exist. When cleanup needs an ID even if readiness fails, create with runningTimeout: false, then call sandbox.waitUntilRunning("wait-for-sandbox", { timeout: "60s" }) as a separate step.

Clean up after failure

The example's Destroy step runs only if execution reaches it. If the function fails after all retries, use an onFailure handler or a separate cleanup function that can retrieve the Sandbox ID. Store the ID somewhere that handler can read after Create. The failure handler runs as a separate function; a JavaScript finally block in the main function does not replace this cleanup path.

For immediate server-side calls through inngest.sandboxes, use try/finally and call sandbox?.destroy() in finally. The direct client has no durable step replay.

Destroy removes the Sandbox filesystem, processes, and retained process output. Persist artifacts outside the Sandbox before destroying it. Destroy may first return TERMINATING; teardown continues after the API accepts the request.

Pause, resume, and reuse state

Pause releases the live runtime into a private checkpoint. Resume returns the same Sandbox ID with its filesystem, memory, and remaining runtime. The current beta allows one hour of active runtime per Sandbox; time spent paused does not consume it. Use the returned running Sandbox before making another command, file, log, or process call.

A user snapshot keeps a copy of memory, disk, environment, image, and resource settings while the source Sandbox continues running. Clone creates a new Sandbox ID from a ready snapshot. Snapshot creation and readiness are separate phases. A wait timeout does not cancel the snapshot being created.

The Sandbox filesystem persists through pause and resume, and a snapshot clone receives the captured filesystem. S3-backed persistent filesystem mounts can share a backing path across different Sandboxes, including clones; those mounts are a separate storage choice from the Sandbox’s private filesystem.

Retries and uncertain outcomes

Let unexpected step.sandbox errors escape the function. Inngest retries operations the middleware marks safe and records a failure when retries are exhausted or an operation is unsafe to repeat. An operation_ambiguous error means a command, process start, or signal may have happened without a confirmed response. Inspect the Sandbox or the operation's external effect before deciding whether to repeat it.

A durable step records the operation result; it does not promise that a Sandbox, guest process, or retained output survives a lost runtime. Inspect the current Sandbox state with Get when work resumes after a long wait or external interruption.

Sandbox operations used as durable steps appear with the function's other steps in its run trace.

Run Python or TypeScript in one call v4.25.0+

step.sandbox.python and step.sandbox.typescript create a Sandbox, run your code, and destroy it. A top-level return gives the result back. Each key of input becomes a variable.

const stats = await step.sandbox.python(
  "stats",
  `import statistics
return {"mean": statistics.mean(values)}`,
  {
    input: { values: [1, 2, 3, 4] },
    schema: { output: z.object({ mean: z.number() }) },
  },
);

const total = await step.sandbox.typescript(
  "sum",
  `return numbers.reduce((a: number, b: number) => a + b, 0)`,
  { input: { numbers: [1, 2, 3] } },
);
  • schema.output types the result and fails the step, with the schema's issues, when the result does not match.
  • A non-zero exit fails the step with the error output.
  • Code can be indented to match your source. Top-level await works in TypeScript, which needs Node 22.13 or later in the image.
  • The first argument is a step ID or step options, such as { id: "stats", name: "Compute the mean" }.
  • Pass tools to let the code call your functions, plus any step.sandbox.create() option such as image or secrets.

These runners are experimental.

Scope a Sandbox to a block v4.24.0+

await using destroys the Sandbox when the block exits.

await using sb = await step.sandbox.create("build", {
  name: "build",
  vcpu: 2,
  memoryMb: 2048,
});
await sb.commands.run("test", "npm test");

group.sandbox() (experimental) runs a callback with a fresh Sandbox and destroys it afterwards. The Sandbox's whole lifetime shows as one group in the trace. It is destroyed when the callback ends, even when it throws, so a failure after that is final and is not retried.

await group.sandbox("build", async (sb) => {
  await sb.commands.run("test", "npm test");
});

group comes from the function's arguments, next to step: async ({ event, step, group }) => {}. group.sandbox() uses 2 vCPU and 2048 MiB when you pass only an ID. step.sandbox.create() needs name, vcpu, and memoryMb.

Durations such as runningTimeout and timeout accept compound strings like "4m30s".

This page describes isolated microVM Sandboxes. Deployment preview environments are called branch deploys.