Skip to content

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

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

Closed
jackowfish wants to merge 2 commits into from
Closed

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

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
b811384
docs: sandbox SDK auto base url resolution
jackowfish Jul 7, 2026
e51e46a
docs: show CLI commands for project/cluster ids
jackowfish Jul 7, 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 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_PROJECT_ID` and `PORTER_CLUSTER_ID` to the target project and cluster, and `PORTER_SANDBOX_API_KEY` to a Porter API token. The SDK builds the external Porter API URL from these 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 `PORTER_PROJECT_ID` 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_PROJECT_ID` and `PORTER_CLUSTER_ID` to the target project and cluster, and `PORTER_SANDBOX_API_KEY` to a Porter API token. The SDK builds the external Porter API URL from these 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 `PORTER_PROJECT_ID` 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
19 changes: 15 additions & 4 deletions sandboxes/getting-started.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -44,18 +44,29 @@ Sandboxes are in a private beta. Please reach out to us at support@porter.run or

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, tell the SDK which project and cluster to target and authenticate with a Porter API token:

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

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 then routes through the Porter API at `dashboard.porter.run` automatically. Replace `<project-id>` and `<cluster-id>` with the project and cluster where sandboxes are enabled. You can copy the prefilled snippet from the cluster's Sandbox tab, or look up the IDs with the [Porter CLI](/cli/basic-usage):

```bash
$ porter project list
ID NAME
1 my-project (current project)

$ 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