SandboxClient

class baseten.sandbox.SandboxClient(*, api_key, team_id=None, token_provider=None, base_url_override=None, headers=None, retry=None, http2=None, http_client_override=None, close_http_client_on_close=None, executor=None)

Bases: object

Client for Baseten sandboxes.

Creates, finds, and deletes sandboxes, and gets a Sandbox to work in one. Can be used as a context manager to ensure the underlying HTTP client is closed on exit.

Parameters:

  • api_key (str)

  • team_id (str | None)

  • token_provider (SandboxTokenProvider | None)

  • base_url_override (str | None)

  • headers (Mapping[str, str] | None)

  • retry (SandboxRetryOptions | None)

  • http2 (bool | None)

  • http_client_override (httpx.Client | None)

  • close_http_client_on_close (bool | None)

  • executor (ThreadPoolExecutor | None)

close()

Close the client, optionally closing the underlying HTTP client.

Return type:

None

create(*, name=None, create_if_not_exists=None, image=None, memory=None, region=None, envs=None, labels=None, external_id=None, lifecycle=None, ports=None, network=None, filesystem=None)

Create a sandbox.

Parameters:

  • name (str | None) – Unique name of the sandbox. Assigned by the server when None.

  • create_if_not_exists (bool | None) – When true, return the existing live sandbox with this name, or recreate it if it is failed, terminated, or being deleted. Requires name. Existing configuration is preserved.

  • image (str | None) – Image reference including its tag. Defaults to baseten/base-image:latest.

  • memory (int | None) – Memory in megabytes, which also sets the CPU allocation. Defaults to 4096.

  • region (str | None) – Region to run in. None picks the closest one.

  • envs (Mapping[str, SandboxEnvValue] | None) – Environment variables, by name.

  • labels (Mapping[str, str] | None) – Labels, by key.

  • external_id (str | None) – Caller-owned identifier for external lookups.

  • lifecycle (SandboxLifecycle | None) – When the sandbox is deleted automatically.

  • ports (Sequence[SandboxPort] | None) – Ports the sandbox exposes.

  • network (SandboxNetwork | None) – Network configuration, which cannot be changed after creation.

  • filesystem (SandboxFileSystemOptions | None) – Filesystem configuration, which cannot be changed after creation.

Return type:

SandboxCreateResult

delete(*, name)

Delete a sandbox.

Deletion continues after this returns, so the returned record usually shows it as still deleting.

Parameters:

name (str) – Name of the sandbox.

Return type:

SandboxInfo

get(*, name: str) → Sandbox
get(*, info: SandboxInfo) → Sandbox

Get a Sandbox to work in.

Fetches the sandbox’s record when given a name, and makes no call when given the record.

Parameters:

  • name (str | None) – Name of the sandbox.

  • info (SandboxInfo | None) – The sandbox’s record, already in hand.

Return type:

Sandbox

get_info(*, name, show_secrets=None)

Get a sandbox’s current record.

Parameters:

  • name (str) – Name of the sandbox.

  • show_secrets (bool | None) – Reveal environment variable values for workspace administrators. Defaults to false. Callers without the admin role receive masked values even when true.

Return type:

SandboxInfo

property http_client: Client

The underlying HTTP client.

property images: ImageClient

Images that sandboxes are created from.

list(*, query=None, statuses=None, external_id=None, page_size=None)

List sandboxes, fetching further pages as iteration reaches them.

Parameters:

  • query (str | None) – Searches sandbox names and labels.

  • statuses (Sequence[Literal['DEPLOYING', 'DEPLOYED', 'FAILED', 'DEACTIVATING', 'DEACTIVATED', 'DELETING', 'TERMINATED', 'ARCHIVING', 'ARCHIVED', 'UNARCHIVING', 'BUILDING', 'UPLOADING'] | str] | None) – Only sandboxes with one of these statuses. Cannot be combined with external_id.

  • external_id (str | None) – Only the sandbox with this external identifier. Cannot be combined with statuses.

  • page_size (int | None) – How many sandboxes to fetch per underlying request.

Return type:

Iterator[SandboxInfo]

property options: SandboxClientOptions

Client options.

property raw_api: ApiClient

The generated management API client, authenticated for sandboxes.

For operations this SDK does not wrap. The generated API surface is not covered by stability guarantees and may change between versions.

sandbox_from_url(*, url)

Get a Sandbox for a sandbox’s execution API URL, making no call.

Its Sandbox.name is empty.

Parameters:

url (str) – Base URL of the sandbox’s execution API, as reported in SandboxInfo.url.

Return type:

Sandbox

update(*, name, lifecycle=None, envs=None, external_id=None, labels=None)

Update a sandbox’s configuration, returning its record after the change.

Arguments left None stay unchanged, and set ones replace their previous values, including every entry of envs, labels, and the lifecycle’s expiration policies. Other lifecycle fields change only when set. At least one argument besides name must be set. Other settings cannot be changed after creation.

Parameters:

  • name (str) – Name of the sandbox.

  • lifecycle (SandboxLifecycle | None) – When the sandbox is deleted automatically.

  • envs (Mapping[str, SandboxEnvValue] | None) – Environment variables, by name.

  • external_id (str | None) – Caller-owned identifier for external lookups.

  • labels (Mapping[str, str] | None) – Labels, by key.

Return type:

SandboxInfo