From 2713af1024396f1e8f61732f1e1f60d5dce1697c Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Wed, 24 Jun 2026 15:19:22 +0000 Subject: [PATCH] docs: clarify sandbox queueing and create() return semantics --- sandbox/sdk/python/reference.mdx | 2 +- sandbox/sdk/typescript/reference.mdx | 2 +- sandboxes/overview.mdx | 6 ++++++ 3 files changed, 8 insertions(+), 2 deletions(-) diff --git a/sandbox/sdk/python/reference.mdx b/sandbox/sdk/python/reference.mdx index fd169ce..8eeeb49 100644 --- a/sandbox/sdk/python/reference.mdx +++ b/sandbox/sdk/python/reference.mdx @@ -59,7 +59,7 @@ Arguments: | `tags` | `dict[str, str] \| None` | Key-value labels for finding related sandboxes. | | `volume_mounts` | `dict[str, str] \| None` | Volume IDs keyed by absolute mount path inside the sandbox. | -Returns a `Sandbox` handle. +Returns a `Sandbox` handle. `create` returns once the request is recorded, which is before the container is necessarily running — the sandbox may still be in `queued` (waiting for capacity) or `creating`. Call `sandbox.refresh()` until `sandbox.phase == "running"` before calling `exec`. ### `get` diff --git a/sandbox/sdk/typescript/reference.mdx b/sandbox/sdk/typescript/reference.mdx index 164ee1d..ae6f151 100644 --- a/sandbox/sdk/typescript/reference.mdx +++ b/sandbox/sdk/typescript/reference.mdx @@ -63,7 +63,7 @@ Options: | `tags` | `Record \| undefined` | Key-value labels for finding related sandboxes. | | `volume_mounts` | `Record \| undefined` | Volume IDs keyed by absolute mount path inside the sandbox. | -Returns a `Sandbox` handle. +Returns a `Sandbox` handle. `create` resolves once the request is recorded, which is before the container is necessarily running — the sandbox may still be in `queued` (waiting for capacity) or `creating`. Call `sandbox.refresh()` until `sandbox.phase === "running"` before calling `exec`. ### `get` diff --git a/sandboxes/overview.mdx b/sandboxes/overview.mdx index 8d559e3..8724984 100644 --- a/sandboxes/overview.mdx +++ b/sandboxes/overview.mdx @@ -33,6 +33,12 @@ A sandbox moves through these phases: Only `running` sandboxes accept exec calls. Logs remain available after terminal phases so you can fetch output from completed or terminated sandboxes. +## Queueing and capacity + +Sandbox create returns as soon as the request is durably recorded. If the cluster does not have capacity to launch the sandbox immediately, the sandbox stays in `queued` until capacity becomes available — create no longer fails on a transient capacity miss. Queued sandboxes are launched in creation order as slots free up, and the warm pool sizes itself against the current queue depth so backlogs drain without manual intervention. + +Because create is non-blocking, the returned sandbox may still be in the `queued` or `creating` phase. Poll `refresh()` (SDK) or `porter sandbox status` (CLI) until the phase reaches `running` before calling `exec`. Calling `exec` on a sandbox that is not yet `running` returns a "sandbox is not running" error rather than blocking. + ## Names Names are the canonical way to refer to sandboxes and volumes in the SDK and CLI.