diff --git a/sandbox/sdk/python/quickstart.mdx b/sandbox/sdk/python/quickstart.mdx index e871d09b..c4a4b0b2 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_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. diff --git a/sandbox/sdk/python/reference.mdx b/sandbox/sdk/python/reference.mdx index 95b8c20b..c07e2957 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 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` diff --git a/sandbox/sdk/typescript/quickstart.mdx b/sandbox/sdk/typescript/quickstart.mdx index 2ce9fd42..85005c57 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_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. diff --git a/sandbox/sdk/typescript/reference.mdx b/sandbox/sdk/typescript/reference.mdx index ceed57e2..4ea38b3c 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 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: diff --git a/sandboxes/getting-started.mdx b/sandboxes/getting-started.mdx index 29fc18a0..794603dc 100644 --- a/sandboxes/getting-started.mdx +++ b/sandboxes/getting-started.mdx @@ -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//clusters/" export PORTER_SANDBOX_API_KEY="" +export PORTER_CLUSTER_ID="" ``` -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 reads the project from the token and routes through the Porter API at `dashboard.porter.run` automatically. Replace `` 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