Sandboxes SDK for Python
Usage and symbol reference
Render Sandboxes is in public beta.
APIs, defaults, and limits might change during the beta period.
Setup
1. Install the SDK
From your Python project directory:
If you already have the SDK installed, make sure you're using version 1.8.0 or later:
After installing, make sure to add render>=1.8.0 as a dependency in your application's requirements.txt, pyproject.toml, or equivalent.
2. Import the client (sync or async)
The Python SDK provides separate classes for synchronous (Render) and asynchronous (RenderAsync) usage. Both clients support the methods in this reference.
The method examples below use the sync client. With RenderAsync, await each method call except exec, which returns an async iterator to use with async for.
Import sandbox-specific types and errors from render.sandbox.
Render(*, token=None, base_url="https://api.render.com", owner_id=None, region=None)
Initializes a synchronous Render SDK client.
| Parameter | Description |
|---|---|
|
The API key to use for authentication. Defaults to the |
|
The default workspace ID for sandbox operations. Defaults to the |
|
A compatibility parameter that does not affect sandbox placement. The sandbox group determines the region. Currently, sandboxes run in Oregon. |
|
The base URL of the Render API. Defaults to |
RenderAsync(*, token=None, base_url="https://api.render.com", owner_id=None, region=None)
Initializes an asynchronous Render SDK client.
| Parameter | Description |
|---|---|
|
The API key to use for authentication. Defaults to the |
|
The default workspace ID for sandbox operations. Defaults to the |
|
A compatibility parameter that does not affect sandbox placement. The sandbox group determines the region. Currently, sandboxes run in Oregon. |
|
The base URL of the Render API. Defaults to |
Sandbox lifecycle
create(*, owner_id=None, plan=None, timeout_seconds=None, idle_timeout_seconds=None, network_policy=None, region=None, env=None, snapshot_id=None, snapshot_name=None, sandbox_group_id=None, wait=False) -> Sandbox
Creates a sandbox in the specified workspace. By default, this method returns before the sandbox is running. Pass wait=True to wait until it's running.
To restore from a snapshot, provide either snapshot_id or snapshot_name, but not both. Set sandbox_group_id to the snapshot's group ID. Restoring into a different group is not supported. See Restoring from a snapshot.
On success: Returns a Sandbox object. If wait is enabled, the returned sandbox has a status of running.
Raises: SandboxCreateWaitError, SnapshotNotFoundError, SnapshotNotReadyError, SnapshotPlanMismatchError, RateLimitError, ClientError, ServerError, RenderError
| Parameter | Description |
|---|---|
|
The ID of the workspace that owns the sandbox. Defaults to the client configuration. This value must be set here or in the client configuration. |
|
The ID of the sandbox group to create the sandbox in. Defaults to the workspace's default group. See Sandbox groups. |
|
The compute plan to use for the sandbox: Defaults to |
|
The maximum time the sandbox can run continuously, in seconds. The sandbox terminates when this time elapses. If the sandbox is suspended and later resumed, this timeout restarts. If you omit this field:
Set to Automatic idle suspension is configured separately with |
|
The period of inactivity before the sandbox is suspended, in seconds. Executing a command or transferring files resumes it automatically. If you omit this field:
Set to |
|
The sandbox's outbound network policy. Provide a If you omit this field:
To specify allowed destinations, provide a |
|
A compatibility parameter that does not affect sandbox placement. The sandbox group determines the region. Currently, sandboxes run in Oregon. |
|
A dictionary of environment variables to inject into the sandbox at creation, with variable names as keys and string values. See Environment variable limits. The API does not return these values in sandbox details. |
|
The ID of an available snapshot in the same sandbox group to restore from. If you provide this value, do not provide |
|
The name of an available snapshot to restore from (case-sensitive). Resolves to the most recently available snapshot with that name in the sandbox group. If you provide this value, do not provide |
|
Controls how the method waits for the sandbox to become ready before returning. Provide one of the following:
The wait begins after the create request returns. If it fails, this method raises |
|
Supported | |
|
Required. The policy type: |
|
Required for Each
Provide between 1 and 100 rules. Other outbound traffic is blocked. |
|
Supported | |
|
The maximum time to wait, in seconds. Defaults to |
|
The initial delay between status checks, in seconds. The delay doubles with each attempt until reaching at least 2 seconds. Defaults to |
To specify wait settings, import SandboxWaitOptions from render.sandbox:
A failed wait does not terminate the sandbox. Use the sandbox_id on SandboxCreateWaitError to terminate it if needed. For an async create call, use SandboxWaitOptions to bound the wait instead of wrapping the call in asyncio.wait_for, which can cancel it without returning the new sandbox's ID.
wait_until_running(sandbox_id, *, timeout_seconds=60, interval_seconds=0.25, owner_id=None) -> Sandbox
Waits for the sandbox with the specified ID to become ready and returns its details.
To create a sandbox and wait for it in a single call, use create with wait=True.
On success: Returns a Sandbox object with a status of running.
Raises: SandboxNotRunningError, SandboxWaitTimeoutError, SandboxNotFoundError, RateLimitError, ClientError, ServerError, RenderError
| Parameter | Description |
|---|---|
|
Required. The ID of the sandbox. |
|
The maximum time to wait, in seconds. Defaults to |
|
The initial delay between status checks, in seconds. The delay doubles with each attempt until reaching at least 2 seconds. Defaults to |
|
The ID of the workspace that owns the sandbox. Defaults to the client configuration. This value must be set here or in the client configuration. |
Raises SandboxNotRunningError if the sandbox is errored, terminated, suspending, or suspended. A failed wait does not terminate the sandbox.
With the sync client, a status request already in progress can finish after the wait timeout. With the async client, the timeout also bounds in-progress status requests.
from_id(sandbox_id, *, owner_id=None) -> Sandbox
Retrieves the details of the sandbox with the specified ID.
On success: Returns a Sandbox object.
Raises: SandboxNotFoundError, RateLimitError, ClientError, ServerError, RenderError
| Parameter | Description |
|---|---|
|
Required. The ID of the sandbox. |
|
The ID of the workspace that owns the sandbox. Defaults to the client configuration. This value must be set here or in the client configuration. |
list(*, owner_id=None, status=None, cursor=None, limit=None, sandbox_group_id=None) -> SandboxList
Lists sandboxes in the specified workspace, newest first. Terminated sandboxes are excluded by default. Include "terminated" in the status filter to retrieve them.
On success: Returns a SandboxList page.
Raises: RateLimitError, ClientError, ServerError, RenderError
| Parameter | Description |
|---|---|
|
The ID of the workspace that owns the sandbox. Defaults to the client configuration. This value must be set here or in the client configuration. |
|
One status string or a sequence of status strings to filter results by. |
|
A cursor from a previous response. Use this to retrieve the next page of results. |
|
The maximum number of sandboxes to return. The API caps this value at |
|
The ID of a sandbox group to filter results by. Omit to list sandboxes across the workspace. |
To paginate, pass the returned next_cursor as cursor on the next call. Continue until a page contains no sandboxes.
terminate(sandbox_id, *, owner_id=None) -> None
Terminates the sandbox with the specified ID and permanently deletes its filesystem. Terminating an already-terminated sandbox succeeds.
On success: Returns None.
Raises: SandboxNotFoundError, RateLimitError, ClientError, ServerError, RenderError
| Parameter | Description |
|---|---|
|
Required. The ID of the sandbox. |
|
The ID of the workspace that owns the sandbox. Defaults to the client configuration. This value must be set here or in the client configuration. |
Runtime execution
exec(sandbox_id, command, *, owner_id=None) -> Iterator[SandboxExecEvent] | AsyncIterator[SandboxExecEvent]
Executes a shell command in the specified sandbox and streams its output. Commands are executed with bash -c. A suspended sandbox resumes automatically.
A nonzero exit code is reported in the final exit event and does not raise an exception.
On success: Returns an iterator of SandboxExecEvent values: a regular iterator with Render, or an async iterator with RenderAsync.
Raises: SandboxNotFoundError, SandboxExecStreamError, SandboxExecError, RateLimitError, ClientError, ServerError, RenderError
| Parameter | Description |
|---|---|
|
Required. The ID of the sandbox. |
|
Required. The shell command to execute. |
|
The ID of the workspace that owns the sandbox. Defaults to the client configuration. This value must be set here or in the client configuration. |
copy_to(sandbox_id, local_path, remote_path, *, owner_id=None) -> None
Uploads a local file or directory to the specified sandbox. A suspended sandbox resumes automatically.
For directories, the SDK transfers the directory's contents to remote_path. Symlinks are preserved, and sockets, FIFOs, and other special files are skipped.
On success: Returns None.
Raises: SandboxNotFoundError, SandboxFileNotFoundError, RateLimitError, ClientError, ServerError, RenderError
| Parameter | Description |
|---|---|
|
Required. The ID of the sandbox. |
|
Required. The local file or directory to upload, as a string or |
|
Required. The destination path in the sandbox. Relative paths resolve under |
|
The ID of the workspace that owns the sandbox. Defaults to the client configuration. This value must be set here or in the client configuration. |
copy_from(sandbox_id, remote_path, local_path, *, owner_id=None) -> str
Downloads a file or directory from the specified sandbox. A suspended sandbox resumes automatically.
Directories are extracted into local_path. For a file, local_path is the destination filename, or an existing directory in which to save the file.
On success: Returns the local path written.
Raises: SandboxNotFoundError, SandboxFileNotFoundError, SandboxDownloadError, RateLimitError, ClientError, ServerError, RenderError
| Parameter | Description |
|---|---|
|
Required. The ID of the sandbox. |
|
Required. The file or directory path in the sandbox to download. Relative paths resolve under |
|
Required. The local destination path, as a string or |
|
The ID of the workspace that owns the sandbox. Defaults to the client configuration. This value must be set here or in the client configuration. |
Snapshot management
Access snapshot methods through render.sandboxes.snapshots.
snapshots.create(sandbox_id, *, kind=None, name=None, expires_at=None, owner_id=None, wait=False) -> Snapshot
Captures the state of a running sandbox in a snapshot. By default, this method returns before capture completes. Pass wait=True to wait until the snapshot is available.
The source sandbox continues running after capture.
On success: Returns a Snapshot object. If wait is enabled, the returned snapshot has a status of available.
Raises: SnapshotCreateWaitError, SandboxNotFoundError, RateLimitError, ClientError, ServerError, RenderError
| Parameter | Description |
|---|---|
|
Required. The ID of the sandbox. |
|
The snapshot type: Defaults to |
|
A case-sensitive name for the snapshot. Names are scoped to the sandbox group, can be reused, and cannot begin with |
|
A future, timezone-aware |
|
The ID of the workspace that owns the sandbox group. Defaults to the client configuration. If neither is set, the API determines the workspace from the sandbox group. |
|
Controls how the method waits for the snapshot to be available before returning. Provide one of the following:
The wait begins after the create request returns. If it fails, this method raises |
|
Supported | |
|
The maximum time to wait, in seconds. Defaults to |
|
The initial delay between status checks, in seconds. The delay doubles with each attempt until reaching at least 2 seconds. Defaults to |
To specify wait settings, import SandboxWaitOptions from render.sandbox:
A failed wait does not cancel capture. SnapshotCreateWaitError includes the new snapshot's snapshot_id and sandbox_group_id. For an async create call, use SandboxWaitOptions to bound the wait instead of wrapping the call in asyncio.wait_for, which can cancel it without returning the new snapshot's IDs.
snapshots.wait_until_available(*, sandbox_group_id, snapshot_id, timeout_seconds=300, interval_seconds=0.25, owner_id=None) -> Snapshot
Waits for the snapshot with the specified ID to be available and returns its details.
To capture a snapshot and wait for it in a single call, use snapshots.create with wait=True.
On success: Returns a Snapshot object with a status of available.
Raises: SnapshotFailedError, SnapshotWaitTimeoutError, SnapshotNotFoundError, RateLimitError, ClientError, ServerError, RenderError
| Parameter | Description |
|---|---|
|
Required. The ID of the sandbox group. |
|
Required. The ID of the snapshot. |
|
The maximum time to wait, in seconds. Defaults to |
|
The initial delay between status checks, in seconds. The delay doubles with each attempt until reaching at least 2 seconds. Defaults to |
|
The ID of the workspace that owns the sandbox group. Defaults to the client configuration. If neither is set, the API determines the workspace from the sandbox group. |
Raises SnapshotFailedError if capture fails. A failed wait does not cancel capture.
With the sync client, a status request already in progress can finish after the wait timeout. With the async client, the timeout also bounds in-progress status requests.
snapshots.from_id(*, sandbox_group_id, snapshot_id, owner_id=None) -> Snapshot
Retrieves the details of the snapshot with the specified ID.
On success: Returns a Snapshot object.
Raises: SnapshotNotFoundError, RateLimitError, ClientError, ServerError, RenderError
| Parameter | Description |
|---|---|
|
Required. The ID of the sandbox group. |
|
Required. The ID of the snapshot. |
|
The ID of the workspace that owns the sandbox group. Defaults to the client configuration. If neither is set, the API determines the workspace from the sandbox group. |
snapshots.list(*, sandbox_group_id, status=None, cursor=None, limit=None, owner_id=None) -> SnapshotList
Lists snapshots in the specified sandbox group, newest first. Deleted and expired snapshots are excluded.
On success: Returns a SnapshotList page.
Raises: RateLimitError, ClientError, ServerError, RenderError
| Parameter | Description |
|---|---|
|
Required. The ID of the sandbox group. |
|
One status string or a sequence of status strings to filter results by: |
|
A cursor from a previous response. Use this to retrieve the next page of results. |
|
The maximum number of snapshots to return. The API caps this value at |
|
The ID of the workspace that owns the sandbox group. Defaults to the client configuration. This value must be set here or in the client configuration. |
To paginate, pass the returned next_cursor as cursor on the next call. Continue until a page contains no snapshots.
snapshots.delete(*, sandbox_group_id, snapshot_id, owner_id=None) -> None
Deletes the snapshot with the specified ID. Deletion prevents future restores and does not affect sandboxes already restored from it.
You cannot delete a snapshot while its status is creating. Deleting an already-deleted or expired snapshot succeeds.
On success: Returns None.
Raises: SnapshotNotFoundError, SnapshotNotReadyError, RateLimitError, ClientError, ServerError, RenderError
| Parameter | Description |
|---|---|
|
Required. The ID of the sandbox group. |
|
Required. The ID of the snapshot. |
|
The ID of the workspace that owns the sandbox group. Defaults to the client configuration. If neither is set, the API determines the workspace from the sandbox group. |
Sandbox groups
list_groups(*, owner_id=None, cursor=None, limit=None) -> SandboxGroupList
Lists sandbox groups in the specified workspace. Use a group's ID when creating sandboxes or managing snapshots.
On success: Returns a SandboxGroupList page.
Raises: RateLimitError, ClientError, ServerError, RenderError
| Parameter | Description |
|---|---|
|
The ID of the workspace that owns the sandbox. Defaults to the client configuration. This value must be set here or in the client configuration. |
|
A cursor from a previous response. Use this to retrieve the next page of results. |
|
The maximum number of groups to return per page. Defaults to |
To paginate, pass next_cursor as cursor and continue until a page contains no groups.
create_group(name, *, owner_id=None, region=None) -> SandboxGroup
Creates a sandbox group in the specified workspace.
On success: Returns a SandboxGroup object.
Raises: RateLimitError, ClientError, ServerError, RenderError
| Parameter | Description |
|---|---|
|
Required. The name of the sandbox group. |
|
The ID of the workspace that owns the sandbox. Defaults to the client configuration. This value must be set here or in the client configuration. |
|
The region for the sandbox group. Currently, only |
get_group(sandbox_group_id) -> SandboxGroup
Retrieves the details of the sandbox group with the specified ID.
On success: Returns a SandboxGroup object.
Raises: RateLimitError, ClientError, ServerError, RenderError
| Parameter | Description |
|---|---|
|
Required. The ID of the sandbox group. |
update_group(sandbox_group_id, *, concurrency_limit) -> SandboxGroup
Updates the sandbox group's concurrency limit.
On success: Returns a SandboxGroup object with the effective concurrency limit.
Raises: RateLimitError, ClientError, ServerError, RenderError
| Parameter | Description |
|---|---|
|
Required. The ID of the sandbox group. |
|
Required. The maximum number of active sandboxes in the group. Must be at least |
Error types
All SDK-specific errors inherit from RenderError. Import common errors from render.client.errors and sandbox-specific errors from render.sandbox.
The SDK can also raise standard Python exceptions, such as ValueError for invalid parameter values.
Sandbox errors
RenderError(Exception)
The base class for SDK-specific errors.
SandboxNotFoundError(ClientError)
Raised when the sandbox does not exist or is no longer retrievable.
Command execution errors
These errors pertain to executing commands in a sandbox.
SandboxExecStreamError(RenderError)
Raised when the sandbox reports a terminal error in the command event stream. Includes the reported status and message.
SandboxExecError(RenderError)
Raised when the command event stream ends without a final exit event or contains invalid event data.
File transfer errors
These errors pertain to copying files to or from a sandbox.
SandboxFileNotFoundError(ClientError)
Raised when the requested path does not exist in the sandbox.
SandboxDownloadError(RenderError)
Raised when a download cannot be written or extracted safely.
Readiness errors
These errors pertain to waiting for sandboxes and snapshots to be ready.
SandboxNotRunningError(RenderError)
Raised when waiting for a sandbox that is errored, terminated, suspending, or suspended. Includes sandbox_id and sandbox_status.
SnapshotFailedError(RenderError)
Raised when waiting for a snapshot whose capture failed. Includes snapshot_id and snapshot_error, the capture error message if one is available.
SandboxWaitTimeoutError(TimeoutError)
Raised when the sandbox does not reach running before the wait times out. Includes sandbox_id, timeout_seconds, and last_status.
SnapshotWaitTimeoutError(TimeoutError)
Raised when the snapshot does not become available before the wait times out. Includes snapshot_id, timeout_seconds, and last_status.
SandboxCreateWaitError(RenderError)
Raised when create creates a sandbox but the wait for it to become ready fails.
Includes sandbox_id and cause, the underlying error. The sandbox continues to exist. Use terminate to stop it.
SnapshotCreateWaitError(RenderError)
Raised when snapshots.create creates a snapshot but the wait for it to be available fails.
Includes snapshot_id, sandbox_group_id, and cause, the underlying error. Capture is not canceled.
Snapshot errors
These errors pertain to restoring from snapshots and managing snapshots.
SnapshotNotFoundError(ClientError)
Raised when the snapshot cannot be found in the specified group, including after deletion or expiration.
SnapshotNotReadyError(ClientError)
Raised when restoring from a snapshot that is not available, or deleting a snapshot that is still creating.
SnapshotPlanMismatchError(ClientError)
Raised when restoring a sandbox from a runtime snapshot onto a different compute plan.
API errors
These errors pertain to requests to the Render API.
ClientError(RenderError)
Raised when the API returns a 4xx response. Includes code when the API provides an error code. Capturing a sandbox that is not running raises this error with the code sandbox_not_running.
RateLimitError(ClientError)
Raised when the API returns HTTP 429 because of a request rate or concurrency limit. See Sandbox limits.
ServerError(RenderError)
Raised when the API returns a 5xx response.
TimeoutError(RenderError)
Raised when an API request times out. Also the parent class of SandboxWaitTimeoutError and SnapshotWaitTimeoutError. This is the SDK's TimeoutError, imported from render.client.errors.
Additional types
Sandbox
Represents a sandbox returned by a sandbox method or included in a SandboxList.
| Property | Description |
|---|---|
|
The sandbox's ID. |
|
The sandbox's current status: |
|
The sandbox's compute plan. |
|
A |
|
The Render region in which the sandbox runs. |
|
The sandbox's runtime timeout, in seconds. |
|
The period of inactivity before the sandbox is suspended, in seconds. |
|
The ID of the sandbox group that contains the sandbox. |
|
The time when the sandbox was created, as a |
|
The time when the sandbox was terminated, as a |
SandboxList
Represents one page of sandboxes returned by list().
| Property | Description |
|---|---|
|
A list of |
|
The cursor to pass on the next request. |
SandboxGroup
Represents a sandbox group returned by a group method or included in a SandboxGroupList.
| Property | Description |
|---|---|
|
The sandbox group's ID. |
|
The ID of the workspace that owns the sandbox group. |
|
The sandbox group's name. |
|
The Render region that the sandbox group belongs to. |
|
Whether this is the workspace's default sandbox group. |
|
The effective limit on active sandboxes in this group. Suspended sandboxes do not count toward the limit. See Concurrency. |
|
The time when the sandbox group was created, as a |
|
The time when the sandbox group was last updated, as a |
|
The ID of the associated environment, or |
SandboxGroupList
Represents one page of sandbox groups returned by list_groups().
| Property | Description |
|---|---|
|
A list of |
|
The cursor to pass on the next request. |
Snapshot
Represents a snapshot returned by a snapshots method or included in a SnapshotList.
| Property | Description |
|---|---|
|
The snapshot's ID. |
|
The ID of the sandbox group that contains the snapshot. |
|
The ID of the sandbox from which the snapshot was captured. |
|
The optional name assigned when the snapshot was created, or |
|
The snapshot type: |
|
The snapshot's current status: |
|
The compute plan of the source sandbox. |
|
The time when snapshot capture was requested, as a |
|
The time when capture completed, as a |
|
The time when the snapshot expires, as a |
|
The snapshot's size in bytes, or |
|
The capture error message if capture failed, otherwise |
SnapshotList
Represents one page of snapshots returned by snapshots.list().
| Property | Description |
|---|---|
|
A list of |
|
The cursor to pass on the next request. |
SandboxExecOutput
Represents an output event yielded by exec().
| Property | Description |
|---|---|
|
The output stream: |
|
The output text. |
SandboxExecExit
Represents the final event yielded by exec().
| Property | Description |
|---|---|
|
The command's exit code. |
SandboxExecEvent
The SandboxExecEvent type is a SandboxExecOutput or SandboxExecExit object yielded by exec().