PlatformSandboxes

Sandboxes guides

Run isolated code, preserve work across lifecycle changes, and inspect failures in one durable run.

Start with the TypeScript quick start to run a command in a Sandbox. Then use these guides to preserve files across lifecycle changes, inspect failures in the run trace, and clean up resources after work ends.

Open beta. Sandboxes are available on Pro plans and above. The current TypeScript APIs support Sandbox creation, commands, and cleanup. You can select existing workspace secrets when you create a Sandbox. SSH and S3-backed persistent mounts are planned for launch.

Start and run

  • Run your first Sandbox. Create a Sandbox in a durable TypeScript function, run one command, inspect its result, and destroy it.
  • Run code and commands. Use Managed lifecycle for step.sandbox inside a function. The immediate inngest.sandboxes client supports command inputs, captured output, and timeouts. step.sandbox.python and step.sandbox.typescript start a Sandbox, run code, and clean up in one call. Tools let that code call your functions.
  • Move files and manage processes. The beta APIs support file upload and download, background processes, retained output, and live output. File transfer and live streams currently use the direct server-side client.

Keep or branch your work

  • Pause and resume. Continue the same Sandbox later with its filesystem, memory, and Sandbox ID.
  • Create a snapshot and clone it. Save a prepared state and start a new Sandbox from it. Cloning does not replace the original Sandbox.
  • Share files across Sandboxes. Learn when a Sandbox filesystem survives pause or appears in a snapshot clone, and when to use an S3-backed persistent mount. A clone attaches the same backing path for a shared mount.

Access and inspect

  • Connect over SSH. SSH is planned for launch and will use an uploaded public key and Sandbox address.
  • Use Sandbox secrets. Select existing workspace secrets by exact name when creating a fresh Sandbox. Code throughout that Sandbox can read the injected values, and output is not automatically redacted.
  • Inspect Sandbox steps in a trace. Find the operation, result, error, and retry attempt in the function run.

Recover and clean up

  • Handle retries and uncertain outcomes. Managed lifecycle explains safe step retries and operation_ambiguous. Inspect the current Sandbox or external effect before repeating a command that may already have run.
  • Clean up after success and failure. The beta step.sandbox.create() flow needs an explicit Destroy step and a failure cleanup path when a permanently failed run could leave a Sandbox. Direct inngest.sandboxes calls need application cleanup, such as try/finally.