Skip to content

docs: make sandboxes getting-started more agent-friendly#446

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
sophiajwitt wants to merge 2 commits into
base:main
Choose a base branch
from
Open

docs: make sandboxes getting-started more agent-friendly #446

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
b55af62
docs: make sandboxes getting-started more agent-friendly
Aug 4, 2026
6969d87
docs: use plural "Sandboxes" in Networking and Capacity page titles
Aug 5, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion sandboxes/capacity.mdx
View file
Open in desktop
Original file line numberDiff line numberDiff line change
@@ -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"
---

Expand Down
10 changes: 10 additions & 0 deletions sandboxes/getting-started.mdx
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -69,6 +69,10 @@ To point the SDK at a specific URL instead, set `PORTER_SANDBOX_BASE_URL` or pas

## Python quickstart

<Note>
**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).
</Note>

Install the SDK in your application image:

```bash
Expand DownExpand Up@@ -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.
Expand Down
2 changes: 1 addition & 1 deletion sandboxes/networking.mdx
View file
Open in desktop
Original file line numberDiff line numberDiff line change
@@ -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"
---

Expand Down