docs: add externalId documentation for sandboxes#616
docs: add externalId documentation for sandboxes#616devin-ai-integration[bot] wants to merge 4 commits into
Conversation
- Add External ID section below Labels in Sandboxes/Overview (creation, retrieval, list filtering, CLI manifest) - Add 'Index sandboxes with external IDs' best practice section (use cases, code examples, guidance) Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
🤖 Devin AI EngineerI'll be helping with this pull request! Here's what you should know: ✅ I will automatically:
Note: I can only respond to comments from users who have write access to this repository. ⚙️ Control Options:
|
![mendral-app[bot]](https://avatars.githubusercontent.com/in/1975249?s=60&v=4){kind=small}
This comment was marked as outdated.
This comment was marked as outdated.
Sorry, something went wrong.
🧪 Testing GuideWhat this PR addressesAdds user-facing documentation for the
Steps to verifySince this is a documentation-only change, there is no bug to reproduce. Instead, verify the following:
What to verify (expected behavior)
Note Posted by PR Testing Guide · Tag @mendral-app with feedback. |
|
✅ Linked to Linear issue ENG-3141 — status already In Progress, assigned to Charles Drappier. Note Posted by Linear Issue Enforcer · Tag @mendral-app with feedback. |
🔍 PR Flow AnalysisThis PR is documentation-only — it adds user-facing docs for the Changes summary:
No architectural interactions to diagram. ✅ Note Posted by PR Sequence Diagram · Tag @mendral-app with feedback. |
Requires @blaxel/core >= 0.2.92 (TypeScript) or blaxel >= 0.2.57 (Python). Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
Ok with all, for the version I think we not do it for other and the way to do it is more : Always saying to use the last one Co-authored-by: vikram-blaxel <vvaswani@blaxel.ai>
|
Devin is archived and cannot be woken up. Please unarchive Devin if you want to continue using it. |
There was a problem hiding this comment.
LGTM
Changes since last review are editorial improvements (version note, link fixes, CLI manifest removal per reviewer feedback). Documentation remains accurate and well-structured. No issues found.
Tag @mendral-app with feedback or questions. View session
![devin-ai-integration[bot]](https://avatars.githubusercontent.com/in/811515?s=60&v=4){kind=small}
| - **One sandbox per user session**: Tag each sandbox with your session ID. When the user returns, call `getByExternalId` to reconnect to the same environment instantly. | ||
| - **Idempotent provisioning**: Before creating a new sandbox, check if one already exists for your workflow ID. This avoids duplicate sandbox creation in retry scenarios. | ||
| - **Multi-tenant isolation**: Tag sandboxes with tenant or user IDs for quick per-tenant enumeration via `list({ externalId })`. | ||
|
|
||
| <CodeGroup> | ||
|
|
||
| ```typescript TypeScript | ||
| // Reconnect to the user's sandbox, or create one if none exists | ||
| let sandbox = await SandboxInstance.getByExternalId(sessionId); | ||
| if (!sandbox) { | ||
| sandbox = await SandboxInstance.create({ | ||
| name: uniqueName(), | ||
| image: "blaxel/base-image:latest", | ||
| externalId: sessionId, | ||
| region: "us-pdx-1" | ||
| }); | ||
| } |
There was a problem hiding this comment.
🚩 TOCTOU gap in the 'idempotent provisioning' example pattern
The best-practices section at Sandboxes/best-practices.mdx:111 lists "Idempotent provisioning" as a common pattern and says it "avoids duplicate sandbox creation in retry scenarios." However, the code example at lines 118-126 uses getByExternalId followed by create() with uniqueName(). This check-then-act pattern has a TOCTOU (time-of-check-time-of-use) gap: two concurrent retries could both see no existing sandbox and both call create() with different unique names, resulting in duplicate sandboxes sharing the same externalId. The note at line 144 even acknowledges that externalId is not unique. This pattern is only idempotent for sequential retries, not concurrent ones. Given that the earlier section at line 116 recommends createIfNotExists() for idempotent creation, the example could be improved to use a deterministic name with createIfNotExists() instead.
Was this helpful? React with 👍 or 👎 to provide feedback.
2 participants
Summary\n\nAdds user-facing documentation for the
externalIdfeature on sandboxes (ENG-3141).\n\nTwo changes:\n\n1.Sandboxes/Overview.mdx— New### External IDsection inserted after Labels. Covers: what it is (indexed caller-owned identifier), rules (64 chars, alphanum+dash, mutable, not unique), SDK examples for create/get/list, and CLI manifest example.\n\n2.Sandboxes/best-practices.mdx— New## Index sandboxes with external IDssection. Explains when to use externalId vs labels (indexed lookup vs client-side filtering), common patterns (session reconnect, idempotent provisioning, multi-tenant), and a practical code example showing the "get or create" pattern."Link to Devin session: https://app.devin.ai/sessions/cdb3ad07a98841f2adb3a327d0915bf7
Requested by: @drappier-charles
Note
Adds
externalIddocumentation for sandboxes: Overview section with SDK examples for create/get/list, and a best-practices section with indexed lookup patterns. Since last review: added SDK version requirement note, removed CLI manifest example, and fixed cross-page links to use absolute paths.Written by Mendral for commit 5a58082.