From b55af621de5fe67cf376882308ea6e91585af636 Mon Sep 17 00:00:00 2001 From: Sophia Witt Date: Tue, 4 Aug 2026 16:12:57 -0400 Subject: [PATCH 1/2] docs: make sandboxes getting-started more agent-friendly Two additive changes to reduce first-run friction for developers and coding agents copy-pasting from the quickstart: - Surface authentication as a prerequisite with a Note directly above the quickstarts, so readers who jump straight to the code know they need PORTER_SANDBOX_API_KEY / PORTER_CLUSTER_ID when running outside the cluster (previously only covered in an earlier section that's easy to skip). - Add a Troubleshooting section covering the two predictable first failures - exec against an already-exited sandbox, and auth errors outside the cluster - and linking the Python/TypeScript SDK error references. Co-Authored-By: Claude Opus 4.8 --- sandboxes/getting-started.mdx | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/sandboxes/getting-started.mdx b/sandboxes/getting-started.mdx index f47b4f3c..5ebeb9c7 100644 --- a/sandboxes/getting-started.mdx +++ b/sandboxes/getting-started.mdx @@ -69,6 +69,10 @@ To point the SDK at a specific URL instead, set `PORTER_SANDBOX_BASE_URL` or pas ## Python quickstart + +**Authentication**: when your code runs as a Porter Application in the same cluster where sandboxes are enabled, the SDK authenticates automatically and the quickstarts below work as-is. To run them from anywhere else (a local machine, CI, another cluster), first set `PORTER_SANDBOX_API_KEY` and `PORTER_CLUSTER_ID` as described in [Calling from outside the cluster](#calling-from-outside-the-cluster). + + Install the SDK in your application image: ```bash @@ -317,6 +321,12 @@ sandbox = porter.sandboxes.create( ) ``` +## Troubleshooting + +- **`exec` fails because the sandbox already exited**: a sandbox only accepts `exec` while its main process is running. An image whose default command exits immediately moves to `succeeded` within a few seconds and stops accepting exec calls. Give the sandbox a long-running main process so you can exec into it — see [Keep a sandbox alive for exec](#keep-a-sandbox-alive-for-exec). +- **Authentication errors when running outside the cluster**: make sure `PORTER_SANDBOX_API_KEY` (a Porter API token with developer permissions) and `PORTER_CLUSTER_ID` are set — see [Calling from outside the cluster](#calling-from-outside-the-cluster). +- **Full error reference**: every error class the SDKs raise is documented in the [Python SDK errors](/sandboxes/sdk/python/errors) and [TypeScript SDK errors](/sandboxes/sdk/typescript/errors) pages. + ## Next steps - Use [Sandbox Networking](/sandboxes/networking) to serve sandboxes over HTTPS on your own domains. From 6969d87a269e1459b2d9f725d287acaaa1909ef3 Mon Sep 17 00:00:00 2001 From: Sophia Witt Date: Wed, 5 Aug 2026 16:45:44 -0400 Subject: [PATCH 2/2] docs: use plural "Sandboxes" in Networking and Capacity page titles The sidebar mixed singular and plural: "Sandboxes Overview / Getting Started / CLI" alongside "Sandbox Networking" and "Sandbox Capacity". Make the descriptive guide-page titles consistently plural to match the section name. The "Sandbox SDK" pages keep the singular product name (the package is porter-sandbox). Co-Authored-By: Claude Opus 4.8 --- sandboxes/capacity.mdx | 2 +- sandboxes/networking.mdx | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/sandboxes/capacity.mdx b/sandboxes/capacity.mdx index 256a3d2a..9e9403ea 100644 --- a/sandboxes/capacity.mdx +++ b/sandboxes/capacity.mdx @@ -1,5 +1,5 @@ --- -title: "Sandbox Capacity" +title: "Sandboxes Capacity" description: "Raise the sandbox node group's CPU limit and tune the warm pod pool to run more sandboxes" --- diff --git a/sandboxes/networking.mdx b/sandboxes/networking.mdx index 3fb39589..38783d63 100644 --- a/sandboxes/networking.mdx +++ b/sandboxes/networking.mdx @@ -1,5 +1,5 @@ --- -title: "Sandbox Networking" +title: "Sandboxes Networking" description: "Serve sandboxes over HTTPS on your own domains and restrict their outbound traffic with egress allowlists" ---