docs: clarify sandbox queueing and create() return semantics

[mintlify]

Summary

Document the new behavior shipped in the upstream feat: queue sandbox launches change: sandbox create is now non-blocking and capacity misses keep the sandbox in the queued phase instead of rejecting the request.

Changes

• sandboxes/overview.mdx: added a Queueing and capacity section explaining that create returns once the request is durable, that queued sandboxes are launched in creation order as capacity frees up, and that callers should poll until running before calling exec.
• sandbox/sdk/python/reference.mdx: noted that porter.sandboxes.create(...) returns while the sandbox may still be queued or creating, and to refresh() until phase == "running" before exec.
• sandbox/sdk/typescript/reference.mdx: same clarification for the TypeScript SDK.

Context

Upstream PR makes sandbox create record requests as queued and return once the registry write succeeds, so capacity misses no longer reject accepted runs. A 3s reconciler launches queued records in creation order, and the warm pool sizes itself against current queue depth. Docs previously described queued as a phase but did not tell users that create returns before the sandbox is running — these edits close that gap.

cc @jackowfish for review.

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
porter	🟢 Ready	View Preview	Jun 24, 2026, 4:38 PM