Sandboxes guides

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.

Access-gated beta. 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. A planned step.sandbox.typescript helper will start, run TypeScript, and stop a Sandbox in one call.
• 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.