TypeScript Sandbox SDK reference

Import the top-level client from porter-sandbox:

import { Porter } from "porter-sandbox";

`Porter`

Porter is the top-level client. It exposes resource namespaces for sandboxes, volumes, health, and readiness.

const porter = new Porter();
const sandbox = await porter.sandboxes.create({
  image: "python:3.12-slim",
  name: "my-sandbox",
});

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, and the token must have developer permissions to authenticate with the Sandbox API.
`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:

porter.close();

`porter.sandboxes`

`create`

const sandbox = await porter.sandboxes.create({
  image: "python:3.12-slim",
  name: "my-sandbox",
  command: undefined,
  args: undefined,
  env: undefined,
  tags: { workflow: "demo" },
  volume_mounts: undefined,
});

Options:

Option	Type	Description
`image`	`string`	Container image to run, referenced by tag or digest.
`name`	`string \| undefined`	Optional cluster-unique sandbox name. Use lowercase letters, numbers, and hyphens; start and end with a letter or number. Names currently cannot be reused, even after termination.
`command`	`string[] \| undefined`	Optional entrypoint override.
`args`	`string[] \| undefined`	Optional arguments passed to the command.
`env`	`Record<string, string> \| undefined`	Environment variables to set in the sandbox.
`env_groups`	`string[] \| undefined`	Names of environment groups on the cluster whose variables are injected into the sandbox, resolved to their latest version at create time. On a key conflict a later group wins over an earlier one, and an explicit `env` entry wins over any group value.
`tags`	`Record<string, string> \| undefined`	Key-value labels for finding related sandboxes.
`volume_mounts`	`Record<string, string> \| undefined`	Volume IDs keyed by absolute mount path inside the sandbox.
`networking`	`SandboxNetworkingSpec[] \| undefined`	Port to expose and, optionally, the domain and visibility to serve it on. Omit to expose nothing. See Sandbox Networking.
`egress`	`SandboxEgressSpec \| undefined`	Restricts the sandbox’s outbound traffic to a list of allowed destinations (hostnames, wildcards, IP literals, CIDR ranges, or in-cluster Service DNS names). Omit to leave internet access unrestricted. See Restrict egress with an allowlist.
`resources`	`SandboxResourcesSpec \| undefined`	CPU and memory for the sandbox (`{ cpu: "2", memory: "4Gi" }`). CPU is in cores, with an `m` suffix for a fraction; memory takes a `Gi` or `Mi` suffix. Omit a field to keep the cluster’s default sandbox size for that resource. See custom sandbox sizes.
`ttl_seconds`	`number \| undefined`	Maximum lifetime in seconds, counted from creation. The sandbox is terminated once it elapses. Omit for no limit. See sandbox lifetime.

Returns a Sandbox handle.

`get`

const sandbox = await porter.sandboxes.get("my-sandbox");

Looks up a sandbox by name and returns a Sandbox handle. Use names as the canonical reference for sandboxes you need to operate on later.

`list`

const sandboxes = await porter.sandboxes.list({
  tags: { workflow: "demo" },
  page: 1,
});

Lists sandboxes, optionally filtered by tags and page.

`Sandbox`

Sandbox is the handle returned by porter.sandboxes. Properties:

Property	Type	Description
`id`	`string`	Sandbox identifier.
`phase`	`StatusResponsePhase \| null`	Last-known lifecycle phase.
`tags`	`Record<string, string> \| null`	Last-known tags.

Methods:

const status = await sandbox.refresh();
const result = await sandbox.exec(["python", "-c", "print('hi')"]);
const logs = await sandbox.logs({ limit: 100 });
await sandbox.terminate();

Method	Description
`refresh()`	Refetches status and updates `phase` and `tags`.
`exec(command, requestOptions?)`	Runs a command in the sandbox and returns stdout, stderr, and exit code.
`logs(options?)`	Fetches structured log lines.
`terminate()`	Terminates the sandbox.

`exec` timeouts

exec is long-running: the client sends no timeout by default, so the call waits for the command to exit. Pass requestOptions.timeoutMs to cap how long the client waits. When the timeout elapses, the SDK throws SandboxTimeoutError and does not retry, since the command may still be running server-side.

import { SandboxTimeoutError } from "porter-sandbox";

try {
  const result = await sandbox.exec(["sleep", "120"], { timeoutMs: 30_000 });
} catch (error) {
  if (error instanceof SandboxTimeoutError) {
    console.error("exec exceeded 30s; the command may still be running in the sandbox");
  } else {
    throw error;
  }
}

The client-wide timeoutMs on Porter still applies to every other request (30 seconds by default).

Volumes

Volumes are persistent storage that can be mounted into sandboxes.

const volume = await porter.volumes.create({ name: "my-data" });

const sandbox = await porter.sandboxes.create({
  image: "python:3.12-slim",
  volume_mounts: { "/mnt/data": volume.id },
});

Sandbox and volume names may contain lowercase letters, numbers, and hyphens, and must start and end with a letter or number. Sandbox names currently cannot be reused, even after termination. Volume names must be unique for the lifetime of the volume and can be reused after deletion. Volume methods:

Method	Description
`porter.volumes.list()`	Lists volumes as handles.
`porter.volumes.create(body)`	Creates a volume and returns its handle. A body with `type: "object"` and `object` makes an object volume; the default is a disk volume.
`porter.volumes.get(name)`	Fetches a volume handle by name.
`porter.volumes.delete(name)`	Deletes a volume by name.

create, get, and list return Volume | ObjectVolume; the type getter discriminates the union. A Volume (disk) has id, name, type, phase, path, attachedTo, and createdAt, plus:

Method	Description
`volume.listdir(path)`	Entries directly inside a directory.
`volume.iterdir(path)`	Async iterator over the whole tree below a directory.
`volume.search(query, { path })`	Entries whose name contains a substring.
`volume.readFile(path, { offset, length })`	File contents as bytes, optionally a byte range.
`volume.readText(path, { offset, length })`	File contents as a string.
`volume.stream(path, { chunkSize })`	Async iterator over a file in chunks, for files too large to hold in memory.
`volume.writeFile(path, content)`	Writes bytes to a file, creating parent directories and replacing any existing file. Atomic.
`volume.writeText(path, content)`	Writes a string to a file. See `writeFile`.
`volume.moveFile(from, to)`	Moves or renames a file or directory; `to` is the full new path. Fails if the destination is occupied.
`volume.refresh()`	Refetches the underlying volume record.
`volume.delete()`	Deletes this volume.

An ObjectVolume shares id, name, type, phase, attachedTo, createdAt, refresh(), and delete(), and adds object (the bucket, key prefix, and access mode). It has no file methods: an object volume’s contents live in its bucket.

Low-level client

The top-level client exposes generated low-level clients through .raw:

const rawClient = porter.raw;
const rawSandboxes = porter.sandboxes.raw;

Use these only when you need an endpoint that is not wrapped by the ergonomic SDK surface yet.

Documentation

TypeScript Sandbox SDK reference

`Porter`

`porter.sandboxes`

`create`

`get`

`list`

`Sandbox`

`exec` timeouts

Volumes

Low-level client

Next steps

​Porter

​porter.sandboxes

​create

​get

​list

​Sandbox

​exec timeouts

​Volumes

​Low-level client

​Next steps

`Porter`

`porter.sandboxes`

`create`

`get`

`list`

`Sandbox`

`exec` timeouts

Volumes

Low-level client

Next steps