Conversation
✅ Deploy Preview for docsdocker ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
dvdksn
force-pushed
the
codex/sandboxes-api-docs
branch
from
September 23, 2026 08:38
ece79b3 to
5595734
Compare
github-actions
Bot
added
area/subscription
dvdksn
changed the title
github-actions
Bot
added
area/api
Make the Agentic Platform section and its billing plan discoverable while retaining experimental labeling. Add canonical subscription activation and billing guidance for Console, cloud CLI, and API/SDK users so companion documentation can link to one setup flow. Refresh kits, credentials, sandbox lifecycle and platform controls, MCP, policies, and release notes against the Console implementation. Document custom kit size limits and distinguish Console restrictions from private-kit CLI support.
Add an API and SDKs section under Docker Sandboxes with an overview, SDK installation, a TypeScript create/run/delete tutorial, and guidance on API concepts, authentication, errors, and retries. Align the examples with the public REST SDKs and Cloud support constraints. Document separate management and sandbox credentials, resource lifecycle waits, and HTTP retry and concurrency headers. Co-Authored-By: Claude <noreply@anthropic.com>
API and SDK access requires a cloud sandbox subscription, but the draft only mentioned account access. Add activation instructions within the API overview and link them from the quickstart, SDK, and authentication pages. Match the subscription and checkout wording in sibling PR docker#26158 without linking to the hidden Docker Agentic Platform documentation. Scoped Markdown and Vale checks pass.
The first-run tutorial required readers to find an existing account image before they could follow it. Use the public Alpine 3.22 image through imageRef with explicit compute resources and platform, and remove image lookup and its permission requirement. Validated the command in the Alpine image locally, type-checked the example against the published SDK, and passed scoped Markdown and Vale checks.
Subscription setup is documented in the Agentic Platform signup guide. Replace duplicated activation instructions with canonical signup and billing links, and use the shared subscription name across API prerequisites.
Align the draft with merged sbx-api PR 784. Use OAuth sign-in and managed sandbox cleanup in the tutorial, document PAT authentication for automation, and update SDK client and lifecycle guidance.
Match the Agentic Platform experimental treatment with a violet section badge and notices on the overview, installation, and quickstart pages.
Use the shell kit for the first sandbox and explain kit-based creation. Reconcile authentication lifecycle, Cloud capabilities, installation, and retry guidance with sbx-api PR 786. Add compute sizes and quota defaults checked against the Cloud service source while retaining Docs ownership of the prose.
Focus the first-run example on signing in, launching a kit, running a command, and deleting the sandbox. Remove explicit idempotency keys, deadlines, and nested recovery handling following early reviewer feedback; keep recovery guidance linked separately.
The draft described unpublished Go and Python SDKs and an outdated TypeScript package and client. Limit installation and examples to @docker/sandboxes, adopt the Sandboxes client and kit launch defaults, and clarify kits, images, provider credentials, PAT permissions, and recovery behavior. Show the experimental notice across the API section and remove links to the archived internal SDK repository. Validate the examples against the generated public SDK from sbx-api commit 68f214b9, with scoped lint, a full Hugo build, and rendered link checks.
The concepts table implied that all kits come from the bundled catalog and compared a waiting helper with creation-only calls. Describe OCI kit distribution and custom artifact inputs, compare creation-only methods, and explain the bundled helpers and their compute default.
The concepts page conflated independently published kits with authoring a kit and left the kits request shape unexplained. Describe SDK bundling, separate kit content from container images, and use Hermes as an example of consuming a published kit. Link the comparison table to an expanded create request and explain artifact preparation and the lack of an npm registry loader. Validate with scoped lint, public SDK type checking, a Hugo build, and rendered link checks.
Agentic Platform loads registry kits and converts compatible v3 kits to v2 artifacts before submitting them to Cloud. The public Cloud create handler accepts only inline v2 artifacts and rejects v3 descriptors. Clarify the v2 link as an API input format, describe the Console conversion, and identify registry loading as functionality outside the npm SDK. Verified against Agentic Platform and Cloud main and passed scoped Markdown and Vale lint.
The guides mixed introductory concepts with kit artifact preparation, authentication internals, and recovery details. Reorder sections, split dense paragraphs, and replace agent credential setup prose with a focused example. Make clear that running does not guarantee kit setup completion, link the quickstart to bounded readiness-check guidance, and fix the Hub authentication reference for the preview build. Validate with scoped lint, a Hugo build, rendered link checks, and TypeScript checking against the generated public SDK.
Replace the abstract reference to kit setup results with a direct instruction to wait for the files or services the workload needs.
Move the API and SDK guides alongside Docker Sandboxes under AI and agents so application developers have an independent entry point. Add a Manuals card and cross-links between the CLI and SDK sections, retain experimental labeling, and preserve all seven previous URLs with aliases. Validate the move with scoped lint, a full Hugo build, sidebar hierarchy and active-state checks, rendered links and anchors, and both HTML and production redirects.
Import 37 generated TypeScript recipes and the public OpenAPI 3.2 reference from a pinned sbx-api export. Keep overview and setup content in docker/docs, adapt site links and navigation, and render the generated reference with responsive path wrapping. Record source provenance and add a repeatable import command for future release PRs. Preserve upstream examples and spec bytes; generated reference prose is excluded from local editorial lint so corrections remain upstream.
Replace the long grouped cookbook sidebar with a catalog and the active recipe only. Generate a responsive recipe list from upstream page metadata, retain Markdown discovery, and add a return link on recipe pages without modifying vendored content.
Clarify that SDK wait helpers stop at the running state and do not wait for all kit setup to finish. Explain why applications may need workload-specific readiness checks before describing polling and timeouts.
dvdksn
force-pushed
the
codex/sandboxes-api-docs
branch
from
September 24, 2026 11:54
982b053 to
f40be2d
Compare
|
It looks like we need to modify the instructions for "manage network policies". The precise fix: one sentence added to the markdown prose In cookbook/inputs/guides/manage-network-policies.md, in the "Manage a policy's lifetime" section, change: Supply a policy definition and a replacement using your SDK's policy input type. Include the destinations your workload needs. For a deny-by-default policy, allow the agent's model provider and any required package registries explicitly. Set |
Contributor
Author
|
@pnichols-9000 Added the instruction to set Generated by Codex |
|
There's another issue: The Docker REST client times out after 30s by default, which is not enough time to perform OAuth steps unless the user is super fast. Please go through the docs and replace "signal: AbortSignal.timeout(300_000)" with "timeoutMs: 300_000" in every example that constructs an operation/options object this way. |
Contributor
Author
|
@pnichols-9000 Fixed in 1bbb5af: the complete example uses Generated by Codex |
|
I found another issue, this time with the wording on "snapshot-and-fork-a-sandbox". We just need to add a little disclaimer: " deletion is refused while a restored sandbox is still running". |
|
Also, under "keep-a-cloud-sandbox-running", renewTimeout() can only extend, never shorten the TTL. We need to mention this on that page somewhere. |
usha-mandya
approved these changes
Sep 24, 2026
This branch has not been deployed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Description
Add an experimental Sandboxes API and SDK section alongside Docker Sandboxes under AI and agents, at
/ai/sandboxes-api/. Cover installation of@docker/sandboxes, browser and PAT authentication, and a TypeScript walkthrough that launches the shell kit, runs a command, and deletes the sandbox. Explain kits and image choices with examples, along with compute sizes, quotas, permissions, resource lifecycle, errors, and retries. Link subscription setup and billing to the shared Docker Agentic Platform guide. Preserve the previous/ai/sandboxes/api/URLs with redirects.Stacked on #26142. Merge that PR first. The branch includes its commit so cross-references resolve in the preview; this PR targets
mainbecause the parent branch exists only on the fork. Sibling to #26158, which introduces CLI-side Cloud Sandboxes documentation.Include 36 SDK cookbook recipes at
/ai/sandboxes-api/cookbook/and the public REST API reference at/reference/api/sandboxes/. Import the generated export fromdocker/sbx-apicommit60d79c1d(source1a7f4026). Overview and installation remain maintained here. The reference uses the shared API renderer from main, with separate operation and schema pages, streaming and WebSocket details, and a downloadable OpenAPI spec. An API reference link appears in the API/SDK sidebar. A pinned manifest and import script provide the basis for later release automation.Examples are optional in the shared renderer; supplied examples still have to pass schema validation. Requests without body examples use a request-body file with instructions to prepare it. The import copies all selected recipes and the OpenAPI specification byte for byte from the corrected upstream export, without patches or link rewrites. The broken naming recipe remains temporarily excluded.
This remains a draft pending validation against the published npm SDK. The imported cookbook contains the TypeScript-only guidance, five-minute request deadlines, kit-readiness explanation, active-policy status requirement, and snapshot-deletion and lifetime-renewal restrictions.
Validation: scoped Markdown and Vale checks, full Hugo build, rendered navigation, redirects, and internal links, and TypeScript type-checking against the generated public SDK from
docker/sbx-apicommit68f214b9. Import validation also covers all 60 REST operations and 188 schema definitions, 1,198 imported-page links and anchors, desktop/mobile rendering, Markdown output, spec delivery, and a repeat import. The shared renderer tests, strict generation for all five APIs (zero diagnostics), full Hugo build, and verification of 453 HTML/Markdown page pairs and API links pass. No live sandbox execution. The corrected export passes strict generation for all five APIs with zero diagnostics, scoped Markdown/Vale lint, a full Hugo build, and verification of 453 HTML/Markdown page pairs and API links. A repeat import produces identical files. The spec update changes examples only; schemas and operations are unchanged.@netlify /ai/sandboxes-api/
Generated by Codex