From b811384d18ad880e7635c40a8e72ad393b908782 Mon Sep 17 00:00:00 2001 From: Jack Decker <24392469+jackowfish@users.noreply.github.com> Date: Tue, 7 Jul 2026 11:40:22 -0400 Subject: [PATCH 1/2] docs: sandbox SDK auto base url resolution --- sandbox/sdk/python/quickstart.mdx | 2 +- sandbox/sdk/python/reference.mdx | 2 +- sandbox/sdk/typescript/quickstart.mdx | 2 +- sandbox/sdk/typescript/reference.mdx | 2 +- sandboxes/getting-started.mdx | 9 +++++---- 5 files changed, 9 insertions(+), 8 deletions(-) diff --git a/sandbox/sdk/python/quickstart.mdx b/sandbox/sdk/python/quickstart.mdx index e871d09b..51721968 100644 --- a/sandbox/sdk/python/quickstart.mdx +++ b/sandbox/sdk/python/quickstart.mdx @@ -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//clusters/` 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. diff --git a/sandbox/sdk/python/reference.mdx b/sandbox/sdk/python/reference.mdx index 95b8c20b..2c3c7371 100644 --- a/sandbox/sdk/python/reference.mdx +++ b/sandbox/sdk/python/reference.mdx @@ -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//clusters/`. | +| `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` diff --git a/sandbox/sdk/typescript/quickstart.mdx b/sandbox/sdk/typescript/quickstart.mdx index 2ce9fd42..2d440824 100644 --- a/sandbox/sdk/typescript/quickstart.mdx +++ b/sandbox/sdk/typescript/quickstart.mdx @@ -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//clusters/` 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. diff --git a/sandbox/sdk/typescript/reference.mdx b/sandbox/sdk/typescript/reference.mdx index ceed57e2..0bc9b14f 100644 --- a/sandbox/sdk/typescript/reference.mdx +++ b/sandbox/sdk/typescript/reference.mdx @@ -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//clusters/`. | +| `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: diff --git a/sandboxes/getting-started.mdx b/sandboxes/getting-started.mdx index 2b7dd90b..0e7f2e11 100644 --- a/sandboxes/getting-started.mdx +++ b/sandboxes/getting-started.mdx @@ -44,18 +44,19 @@ 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//clusters/" +export PORTER_PROJECT_ID="" +export PORTER_CLUSTER_ID="" export PORTER_SANDBOX_API_KEY="" ``` -Replace `` and `` 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 `` and `` 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), or copy the prefilled snippet from the cluster's Sandbox tab. 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 From e51e46a47bfd84fa27a49a714d5b1a1b551039d4 Mon Sep 17 00:00:00 2001 From: Jack Decker <24392469+jackowfish@users.noreply.github.com> Date: Tue, 7 Jul 2026 11:41:16 -0400 Subject: [PATCH 2/2] docs: show CLI commands for project/cluster ids --- sandboxes/getting-started.mdx | 12 +++++++++++- 1 file changed, 11 insertions(+), 1 deletion(-) diff --git a/sandboxes/getting-started.mdx b/sandboxes/getting-started.mdx index 0e7f2e11..e128c51e 100644 --- a/sandboxes/getting-started.mdx +++ b/sandboxes/getting-started.mdx @@ -52,7 +52,17 @@ export PORTER_CLUSTER_ID="" export PORTER_SANDBOX_API_KEY="" ``` -The SDK then routes through the Porter API at `dashboard.porter.run` automatically. Replace `` and `` 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), or copy the prefilled snippet from the cluster's Sandbox tab. +The SDK then routes through the Porter API at `dashboard.porter.run` automatically. Replace `` and `` 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.