docs: document sandbox APIs and SDK

[jakobevangelista]

No description provided.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
website	Ready	Preview	Jul 31, 2026 7:26pm

[gester-bot]

Solid, thorough docs (the two reference pages and the feature guides are internally consistent on limits, error codes, and endpoint shapes). The main issue is docs/sandboxes/research-and-decisions.md: it's an internal working document that leaks a contributor's local filesystem path, private repo names/file layouts (inngest-js-sandbox-middleware, monorepo-sandbox-middleware, simcity-sandbox-runtime), and unresolved internal bugs/decisions (e.g. the process-mutation error-mapping bug, unset pricing/entitlements) into the public inngest/website repo. This should be removed from the PR or moved somewhere internal-only before merging.

---

Re-review (2026-07-29): Only change since the last review is swapping http code fences to text in the REST reference — a cosmetic fix with no functional or content impact. Nothing new to flag; the previously-raised issue about docs/sandboxes/research-and-decisions.md leaking internal paths/details remains open and unaddressed.

---

Re-review (2026-07-29): The only change since the last review is the removal of docs/sandboxes/research-and-decisions.md, which resolves the previously flagged issue about leaking internal paths and unresolved internal details into the public repo. No new issues found.

---

Re-review (2026-07-29): Changes since the last review are a docs-only simplification: removing try/finally around step.sandbox calls in the function example in favor of letting step errors escape (with a pointer to onFailure for cleanup), and trimming a couple of redundant code samples into prose in the errors/retries and TS reference pages. Verified the new onFailure link resolves and the guidance is internally consistent — no issues found.

---

Re-review (2026-07-29): The branch history was squashed/rebased into a single commit; file contents are byte-for-byte equivalent to what was already reviewed (line counts match exactly across all files, and the previously removed internal research doc remains absent). No new content changes to review.

---

Re-review (2026-07-29): Changes since the last review are minor and consistent: the example memoryMb value was changed from 2048 to 512 everywhere it appears, and a new caveat was added (consistently, in the managed-processes guide, limitations page, and REST reference) that includeChildren: true is only reliable with SIGKILL and can otherwise leave a process LOST — all example defaults and the graceful-shutdown example were updated to match. No issues found.

---

Re-review (2026-07-29): Since the last review, the SDK's sandbox.refresh() / process.refresh() methods were replaced by using get() directly, and a new docs/sandboxes/beta-getting-started.md guide was added. Verified the refresh→get rename is applied consistently with no stale references left across the feature guides, the TypeScript reference, and the errors/limitations pages. No issues found.

---

Re-review (2026-07-29): Since the last review, only docs/sandboxes/beta-getting-started.md changed: the "Follow live process output" example previously streamed from worker, which by that point in the guide had already been signalled with SIGKILL and reached the KILLED state in an earlier step — contradicting the text "while the process is still running." This is fixed by having the example start its own streamingWorker process. No new issues found.

---

Re-review (2026-07-29): The only change since the last review is a reformat of docs/sandboxes/beta-getting-started.md: prose paragraphs were unwrapped from hard-wrapped lines into single-line paragraphs (reducing the line count), while all code blocks remain byte-identical to the previously reviewed content. No material change.

---

Re-review (2026-07-29): Since the last review, the only change is a short addition to docs/sandboxes/beta-getting-started.md clarifying that the Sandbox middleware is registered automatically and shouldn't be added manually — consistent with the existing "built-in middleware" description in the TypeScript reference. No issues found.

---

Re-review (2026-07-29): Since the last review, the docs were corrected to show that sandboxMiddleware() from inngest/experimental must be explicitly registered on the Inngest client for step.sandbox to work (reversing the previous claim that it was auto-registered). This is applied consistently across the beta guide, the sandboxes overview, and the TypeScript reference, with no leftover contradicting statements. No issues found.

---

Re-review (2026-07-30): Reviewed only the changes since the last pass (the "import beta types from experimental entrypoint" and "remove unneeded helpers" commits). The removal of the attach()/SandboxRef serializable-references API is incomplete: the sandbox.destroy() type sample in the TypeScript reference still references SandboxRef, which is no longer defined anywhere on that page.

---

Re-review (2026-07-31): This commit adds runningTimeout on Create and a waitUntilRunning() helper, and updates the getting-started guide, spec, limitations, and REST/errors docs consistently — but the TypeScript SDK reference page was not updated to match and now directly contradicts them (see inline comment). The two previously-flagged issues (SandboxRef and the stray "inngest" import) remain unresolved, as noted in the ledger.

[gester-bot]

This file leaks internal implementation details into the public inngest/website repo: a contributor's local home-directory path (/home/jakob/inngest-work/...), the names/layouts of private source repos (inngest-js-sandbox-middleware, monorepo-sandbox-middleware, simcity-sandbox-runtime), and unresolved internal issues such as a real bug in the REST mutation error mapping ("Process mutation error mapping" section) and undecided pricing/entitlement plans. None of this belongs in a public repo's git history. Remove this file from the PR (keep it as an internal design doc elsewhere, e.g. Notion/internal wiki) rather than committing it here.

[gester-bot]

This SandboxDestroyResult sample still types sandbox as SandboxRef, but the "Serializable references" section (which defined interface SandboxRef) was removed earlier in this same diff. SandboxRef is now an undefined type on this page, which will confuse/mislead readers. Replace with the actual resource type (e.g. SandboxResource) or re-add a definition.

[gester-bot]

This example imports Sandbox from "inngest", but every other example in this PR (after the "import beta types from experimental entrypoint" commit) imports it from "inngest/experimental". Update this to match so the guidance is consistent.

[gester-bot]

This contradicts the rest of the PR added in this same commit: the getting-started guide, limitations.mdx, and beta-api-sdk-spec.md all now document Create's runningTimeout option and a waitUntilRunning() facade method for bounded readiness polling. This reference page's create(options) section still lists only name/vcpu/memoryMb and this line still says "The SDK does not poll a STARTING sandbox" — readers following this canonical reference will miss the new option/method entirely, or think it doesn't exist. Update the create(options) table and this section (and add a waitUntilRunning() entry) to match the other docs.