Skip to content

docs: update sandbox external access for SDK auto URL resolution #408

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

Merged
sophiajwitt merged 1 commit into from
Jul 9, 2026
Merged

docs: update sandbox external access for SDK auto URL resolution #408

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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 sandbox/sdk/python/quickstart.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -45,7 +45,7 @@ with Porter() as porter:

The SDK connects to the in-cluster Sandbox API automatically when this code runs as a Porter Application in the same cluster where sandboxes are enabled.

If you need to invoke sandboxes from outside that cluster, set `PORTER_SANDBOX_BASE_URL` to `https://dashboard.porter.run/api/v2/alpha/projects/<project-id>/clusters/<cluster-id>` and `PORTER_SANDBOX_API_KEY` to a Porter API token. See [calling from outside the cluster](/sandboxes/getting-started#calling-from-outside-the-cluster) for details.
If you need to invoke sandboxes from outside that cluster, set `PORTER_SANDBOX_API_KEY` to a Porter API token and `PORTER_CLUSTER_ID` to the target cluster. The SDK reads the project from the token and builds the external Porter API URL automatically; see [calling from outside the cluster](/sandboxes/getting-started#calling-from-outside-the-cluster) for details.

Use sandbox names when you need to fetch, inspect, exec into, or terminate a sandbox later. Sandbox names must be unique within a cluster and currently cannot be reused, even after the sandbox is terminated.

Expand Down
2 changes: 1 addition & 1 deletion sandbox/sdk/python/reference.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -28,7 +28,7 @@ Constructor options:
| Option | Type | Description |
| ------ | ---- | ----------- |
| `api_key` | `str \| None` | Optional API key. Falls back to the `PORTER_SANDBOX_API_KEY` environment variable. Only required when invoking the Sandbox API from outside the sandbox-enabled cluster. Create one from **Settings > API tokens** in the Porter Dashboard. Creating API tokens requires admin permissions. |
| `base_url` | `str \| None` | Optional API base URL override. Falls back to the `PORTER_SANDBOX_BASE_URL` environment variable, then the in-cluster Sandbox API URL. To call from outside the cluster, set it to `https://dashboard.porter.run/api/v2/alpha/projects/<project-id>/clusters/<cluster-id>`. |
| `base_url` | `str \| None` | Optional API base URL override. Falls back to the `PORTER_SANDBOX_BASE_URL` environment variable. If neither is set, the SDK builds the external Porter API URL from the API token's project and `PORTER_CLUSTER_ID`, then falls back to the in-cluster Sandbox API URL when running in a Kubernetes cluster, and otherwise raises an error explaining what to set. |
| `timeout` | `float \| None` | Request timeout in seconds. Defaults to 30 seconds. |

## `porter.sandboxes`
Expand Down
2 changes: 1 addition & 1 deletion sandbox/sdk/typescript/quickstart.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -43,7 +43,7 @@ try {

The SDK connects to the in-cluster Sandbox API automatically when this code runs as a Porter Application in the same cluster where sandboxes are enabled.

If you need to invoke sandboxes from outside that cluster, set `PORTER_SANDBOX_BASE_URL` to `https://dashboard.porter.run/api/v2/alpha/projects/<project-id>/clusters/<cluster-id>` and `PORTER_SANDBOX_API_KEY` to a Porter API token. See [calling from outside the cluster](/sandboxes/getting-started#calling-from-outside-the-cluster) for details.
If you need to invoke sandboxes from outside that cluster, set `PORTER_SANDBOX_API_KEY` to a Porter API token and `PORTER_CLUSTER_ID` to the target cluster. The SDK reads the project from the token and builds the external Porter API URL automatically; see [calling from outside the cluster](/sandboxes/getting-started#calling-from-outside-the-cluster) for details.

Use sandbox names when you need to fetch, inspect, exec into, or terminate a sandbox later. Sandbox names must be unique within a cluster and currently cannot be reused, even after the sandbox is terminated.

Expand Down
2 changes: 1 addition & 1 deletion sandbox/sdk/typescript/reference.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -26,7 +26,7 @@ Constructor options:
| Option | Type | Description |
| ------ | ---- | ----------- |
| `apiKey` | `string \| undefined` | Optional API key. Falls back to the `PORTER_SANDBOX_API_KEY` environment variable. Only required when invoking the Sandbox API from outside the sandbox-enabled cluster. Create one from **Settings > API tokens** in the Porter Dashboard. Creating API tokens requires admin permissions. |
| `baseUrl` | `string \| undefined` | Optional API base URL override. Falls back to the `PORTER_SANDBOX_BASE_URL` environment variable, then the in-cluster Sandbox API URL. To call from outside the cluster, set it to `https://dashboard.porter.run/api/v2/alpha/projects/<project-id>/clusters/<cluster-id>`. |
| `baseUrl` | `string \| undefined` | Optional API base URL override. Falls back to the `PORTER_SANDBOX_BASE_URL` environment variable. If neither is set, the SDK builds the external Porter API URL from the API token's project and `PORTER_CLUSTER_ID`, then falls back to the in-cluster Sandbox API URL when running in a Kubernetes cluster, and otherwise throws an error explaining what to set. |
| `timeoutMs` | `number \| undefined` | Request timeout in milliseconds. Defaults to 30 seconds. |

Close the client when your process is done:
Expand Down
14 changes: 10 additions & 4 deletions sandboxes/getting-started.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -48,18 +48,24 @@ A dedicated cluster is not required, it's a defense-in-depth recommendation. San

The SDK connects to the in-cluster Sandbox API automatically when your application runs as a Porter Application in the same cluster where sandboxes are enabled.

To invoke sandboxes from anywhere else, point the SDK at the Porter API and authenticate with a Porter API token:
To invoke sandboxes from anywhere else, authenticate with a Porter API token and tell the SDK which cluster to target:

```bash
export PORTER_SANDBOX_BASE_URL="https://dashboard.porter.run/api/v2/alpha/projects/<project-id>/clusters/<cluster-id>"
export PORTER_SANDBOX_API_KEY="<porter-api-token>"
export PORTER_CLUSTER_ID="<cluster-id>"
```

Replace `<project-id>` and `<cluster-id>` with the project and cluster where sandboxes are enabled. You can find both by running `porter project list` and `porter cluster list` with the [Porter CLI](/cli/basic-usage).
The SDK reads the project from the token and routes through the Porter API at `dashboard.porter.run` automatically. Replace `<cluster-id>` with the cluster where sandboxes are enabled. You can copy the prefilled snippet from the cluster's Sandbox tab, or look up the ID with the [Porter CLI](/cli/basic-usage):

```bash
$ porter cluster list
ID NAME RESOURCE_NAME SERVER
2 my-sandbox-cluster ...
```

You can create an API token from **Settings > API tokens** in the Porter Dashboard. Creating API tokens requires admin permissions.

Both SDKs read these environment variables automatically. You can also pass the same values directly to the client constructor (`base_url` and `api_key` in Python, `baseUrl` and `apiKey` in TypeScript).
To point the SDK at a specific URL instead, set `PORTER_SANDBOX_BASE_URL` or pass `base_url` (Python) / `baseUrl` (TypeScript) to the client constructor. These take precedence over everything above.

## Python quickstart

Expand Down