# Render Sandboxes — Documentation bundle

Generated on: 2026-11-18
Obtain latest version from: https://render.com/docs/sandboxes/all

Bundles documentation specific to Render Sandboxes. Other shared references are linked from the articles below.
Each article includes its source URL. Links and fragments resolve to the original articles.

## Included articles

- [Intro to Render Sandboxes][a]
- [Limits and Pricing for Render Sandboxes][b]
- [Creating and Configuring Sandboxes][c]
- [Executing Commands in Sandboxes][d]
- [Uploading and Downloading Sandbox Files][e]
- [Managing Sandbox Snapshots][f]
- [Claude Managed Agents with Render Sandboxes](https://render.com/docs/sandboxes-claude-managed-agents.md)
- [Cursor Cloud Agents with Render Sandboxes](https://render.com/docs/sandboxes-cursor-cloud-agents.md)
- [OpenAI Agents API with Render Sandboxes](https://render.com/docs/sandboxes-openai-agents-api.md)
- [Sandboxes SDK for TypeScript][g]
- [Sandboxes SDK for Python][h]
- [Render Sandboxes CLI Reference][i]

# Intro to Render Sandboxes
Source: https://render.com/docs/sandboxes


> *Render Sandboxes is in public beta.*
>
> APIs, defaults, and limits might change during the beta period.

*Render Sandboxes* provides managed, ephemeral environments for executing untrusted code. Use sandboxes for AI agents, code interpreters, builds, tests, and other workloads that need an isolated OS environment.

## At a glance

1. You [create a sandbox][c] with the Render CLI or SDK.
2. Inside the sandbox, you (and your agents) can [execute commands][d] and [manage files][e].
3. When you're finished with the sandbox, [terminate it][j].
    - A sandbox also terminates automatically when its configured [runtime timeout][k] expires.
    - You can disable a sandbox's [timeouts][l] so it runs indefinitely.

Termination permanently deletes the sandbox's local filesystem. Before terminating, you can [download any files you need][m] or [capture a snapshot][f] to reuse state in a new sandbox.

## Core features

- Isolated execution: [Execute commands][d] and agent-generated code in a contained environment with its own filesystem.
- Reusable snapshots: [Capture sandbox state][f] to reuse a prepared filesystem or resume a process in a new sandbox.
- File transfers: [Upload any code and files][e], then download the output your sandbox produces.
- Automatic idle suspension: Sandboxes can [suspend when idle][n] and resume automatically when you next interact.
- Configurable compute: Choose a [compute plan][o] with the CPU and RAM each workload needs.
- Network controls: [Configure access][p] to allow outbound traffic to a specific set of destinations (or none at all).

## Quickstart

### 1. Install the CLI or SDK

**Tab: CLI**

Requires Render CLI version *2.34.0 or later*.

Use any of the following methods to install the Render CLI or upgrade to the latest version:

**Subtab: Homebrew**

##### Homebrew installation

Run the following commands:

```shell
brew update
brew install render
```

**Subtab: WinGet**

##### WinGet installation

Run the following command:

```shell
winget install render.cli
```

**Subtab: curl**

##### Installing with `curl`

Run the following command:

```shell
curl -fsSL https://raw.githubusercontent.com/render-oss/cli/refs/heads/main/bin/install.sh | sh
```

**Subtab: Direct download**

##### Direct download

1. Open the CLI's [GitHub releases page](https://github.com/render-oss/cli/releases/).
2. Download the executable that corresponds to your system's architecture.

If you use an architecture besides those provided, you can build from source instead.

**Subtab: Build from source**

##### Building from source

> We recommend building from source only if no other installation method works for your system.

1. [Install the Go programming language](https://golang.org/doc/install) if you haven't already.

2. Clone and build the CLI project with the following commands:

   ```shell
   git clone git@github.com:render-oss/cli.git
   cd cli
   go build -o render
   ```

After installation completes, open a new terminal tab and run `render` with no arguments to confirm.

**Tab: TypeScript**

From your TypeScript project directory:

```shell
npm install @renderinc/sdk@latest
```

(Or `pnpm install`, `bun add`, etc.)

*If you already have the SDK installed,* make sure you're using version `1.9.0` or later:

```shell
npm install @renderinc/sdk@latest
```

After installing, make sure `@renderinc/sdk` is listed as a dependency in your `package.json` file at version `^1.9.0` or later.

**Tab: Python**

From your Python project directory:

```shell
pip install render
```

*If you already have the SDK installed,* make sure you're using version `1.9.0` or later:

```shell
pip install --upgrade render
```

After installing, make sure to add `render>=1.9.0` as a dependency in your application's `requirements.txt`, `pyproject.toml`, or equivalent.

Version 1.9.0 and later of the Python SDK require Python 3.11 or later.

### 2. Set up credentials

1. Create an API key from your [Account Settings page][q] in the Render Dashboard.

2. Set the following environment variables wherever the CLI or SDK will run, replacing values as indicated:

    ```shell
    export RENDER_API_KEY='rnd_abc123'
    export RENDER_WORKSPACE_ID='tea-def456'
    ```

    - Replace `rnd_abc123` with your API key.
    - Replace `tea-def456` with your workspace's ID, available at the top of its *Settings* page in the [Render Dashboard][r].

3. For the CLI, also set your active workspace:

    ```shell
    render workspace set tea-def456
    ```

    - Replace `tea-def456` with your workspace's ID.

### 3. Create a sandbox and execute a command

The following example creates a sandbox with a five-minute runtime timeout, waits until it's running, executes a basic `echo` command, then terminates the sandbox:

**Tab: CLI**

```shell
# Create a sandbox and wait until it's running.
render sandboxes create --timeout=300 --wait

# Replace sbx-abc123 with the ID returned by create.
render sandboxes exec sbx-abc123 -- echo hello from Render

# Terminate the sandbox.
render sandboxes stop sbx-abc123 --confirm
```

**Tab: TypeScript**

```typescript
import { Render } from '@renderinc/sdk'

const sandboxes = new Render().sandboxes
const sandbox = await sandboxes.create({ timeoutSeconds: 300, wait: true })

try {
  const events = await sandboxes.exec(sandbox.id, 'echo hello from Render')

  for await (const event of events) {
    if (event.type === 'output') {
      const stream = event.stream === 'stderr' ? process.stderr : process.stdout
      stream.write(event.data)
    } else if (event.type === 'exit') {
      console.log(`Exit code: ${event.exit_code}`)
    }
  }
} finally {
  await sandboxes.terminate(sandbox.id)
}
```

**Tab: Python (sync)**

```python
import sys
from render import Render
from render.sandbox import SandboxExecExit, SandboxExecOutput

sandboxes = Render().sandboxes
sandbox = sandboxes.create(timeout_seconds=300, wait=True)

try:
    for event in sandboxes.exec(sandbox.id, "echo hello from Render"):
        if isinstance(event, SandboxExecOutput):
            stream = sys.stderr if event.stream == "stderr" else sys.stdout
            print(event.data, end="", file=stream, flush=True)
        elif isinstance(event, SandboxExecExit):
            print(f"Exit code: {event.exit_code}")
finally:
    sandboxes.terminate(sandbox.id)
```

**Tab: Python (async)**

```python
import asyncio
import sys
from render import RenderAsync
from render.sandbox import SandboxExecExit, SandboxExecOutput

async def main():
    sandboxes = RenderAsync().sandboxes
    sandbox = await sandboxes.create(timeout_seconds=300, wait=True)

    try:
        async for event in sandboxes.exec(sandbox.id, "echo hello from Render"):
            if isinstance(event, SandboxExecOutput):
                stream = sys.stderr if event.stream == "stderr" else sys.stdout
                print(event.data, end="", file=stream, flush=True)
            elif isinstance(event, SandboxExecExit):
                print(f"Exit code: {event.exit_code}")
    finally:
        await sandboxes.terminate(sandbox.id)

asyncio.run(main())
```

## Next steps

After creating your first sandbox, explore how to:

- [Execute commands][d], process their output, and handle command failures.
- [Upload and download files][e], including entire directories.
- [Capture snapshots and restore from them][f] to reuse files, installed packages, and running processes in new sandboxes.
- [Configure sandbox behavior][s], including compute, timeouts, environment variables, and network access.
- [Manage sandbox groups][t] to organize workloads and set separate concurrency limits.

## References

For detailed command and SDK reference material, see:

- [Sandboxes CLI reference](<https://render.com/docs/cli-reference.md#sandboxes>)
- [Sandboxes SDK for TypeScript][g]
- [Sandboxes SDK for Python][h]

## Limits

For available compute plans, sandbox runtime timeouts, concurrency, and API rate limits, see [Limits for Render Sandboxes][b].

## Beta limitations

We'll address these limitations during the beta period:

- Sandboxes do not yet support private networking to connect to your other Render services and datastores.
- Sandboxes do not yet provide public URLs for accessing applications running inside them.
- Credential brokering is not yet generally available.

> *Interested in early access to some of these additions?*
>
> Reach out with details about your use case:



# Limits and Pricing for Render Sandboxes
Source: https://render.com/docs/sandboxes-limits


> *Render Sandboxes is in public beta.*
>
> APIs, defaults, and limits might change during the beta period.

The following limits and pricing apply to Render Sandboxes. Limit and pricing details are subject to change during the beta period.

## Compute plans and billing

Each sandbox uses one of the following compute plans, which determines its specs and pricing. You specify which plan to use when you [create a sandbox][o].

| Plan | Specs | Price |
| --- | --- | --- |
| `1c-2g` (default) | 1 CPU 2 GB RAM | $0.12 / CPU-hour + $0.038 / hour ($0.00200000 / CPU-minute + $0.00063333 / minute, $0.00003333 / CPU-second + $0.00001056 / second) |
| `2c-4g` | 2 CPU 4 GB RAM | $0.12 / CPU-hour + $0.076 / hour ($0.00200000 / CPU-minute + $0.00126667 / minute, $0.00003333 / CPU-second + $0.00002111 / second) |
| `4c-8g` | 4 CPU 8 GB RAM | $0.12 / CPU-hour + $0.152 / hour ($0.00200000 / CPU-minute + $0.00253333 / minute, $0.00003333 / CPU-second + $0.00004222 / second) |
| `8c-16g` | 8 CPU 16 GB RAM | $0.12 / CPU-hour + $0.304 / hour ($0.00200000 / CPU-minute + $0.00506667 / minute, $0.00003333 / CPU-second + $0.00008444 / second) |

### How billing works

Sandboxes are billed differently for CPU and memory usage:

------

##### CPU

Billed at $0.12 per CPU-hour, based on the total amount of CPU your sandbox _actually uses_:

- If a sandbox on the `1c-2g` plan constantly uses its full 1 CPU for one hour, Render bills $0.12 for CPU usage.
- If the same sandbox uses only 0.5 CPU for one hour, Render bills $0.06 for CPU usage.

##### Memory

Billed at $0.019 per GB-hour according to your sandbox's _total_ provisioned memory (regardless of actual usage).

------

A sandbox is _not_ billed for CPU or memory usage while [suspended][n].

## General limits

------

##### Writable filesystem storage per sandbox

40 GB

##### Maximum runtime timeout

- If you set a runtime timeout, the maximum allowed value is 30 days.
- You can also _disable_ this timeout entirely to prevent automatic termination.

Learn more about [sandbox timeouts][u].

##### Maximum idle timeout

- If you set an idle timeout, the maximum allowed value is 24 hours.
- You can also _disable_ this timeout entirely to prevent automatic suspension.

Learn more about [sandbox timeouts][u].

##### Suspended sandbox resumability period

30 days

##### Sandbox groups per workspace

10

##### Concurrent sandboxes per sandbox group

Default: 1,000 for *Pro* workspaces and above, 100 for *Hobby* workspaces

You can request an increase to 5,000 for a *Pro* workspace or 10,000 for a *Scale* workspace.

[See details below.][v]

##### Environment variables per sandbox

100 variables, with a combined size of 256 KB across names and values

##### Supported regions

1 (Oregon)

------

> *Need to increase any of these sandbox limits?*
>
> Reach out with details about your use case:

### Concurrency per group

By default, each sandbox group in a *Pro* workspace or above can have up to 1,000 concurrent sandboxes, and each sandbox group in a *Hobby* workspace can have up to 100 concurrent sandboxes.

- In some cases, Render might enforce a temporarily reduced concurrency limit for newly created workspaces with minimal billing history.
- You can request a limit increase to 5,000 for a *Pro* workspace or 10,000 for a *Scale* workspace. To request an increase, please [contact Render](<https://render.com/contact>).
- [Suspended][n] sandboxes do not count toward concurrency limits.
  - To resume a suspended sandbox, its group must be under its concurrency limit.
- You can [reduce the concurrency limit](<https://render.com/docs/sandboxes-creating.md#setting-group-concurrency>) for an individual group.

- While a group is at its concurrency limit, requests to create or resume a sandbox fail with HTTP code `429`.
    - To reclaim capacity, [terminate][j] sandboxes you no longer need.

## API rate limits

Sandbox API operations have separate default rate limits. These limits apply per user, shared across that user's API keys. Requests that exceed a rate limit fail with HTTP code `429`.

| Operation | Requests per minute |
| --- | --- |
| *[Create a sandbox][c]* | 100 |
| *[Terminate a sandbox][j]* | 1,000 |
| *Execute a [command][d]* | 1,000 |
| *[Upload or download][e] a file or directory* | 1,000 |
| *Read sandbox and sandbox group resources* | 400 |
| *Write sandbox group resources* | 100 |
| *Capture a [snapshot][f]* | 10 |



# Creating and Configuring Sandboxes
Source: https://render.com/docs/sandboxes-creating


> *Render Sandboxes is in public beta.*
>
> APIs, defaults, and limits might change during the beta period.

You can create [sandboxes][a] from your own apps and agents with the Render CLI or SDK. This article describes how to create a sandbox and configure its compute plan, timeouts, network access, and more.

Before you begin, [install the CLI or SDK and set up your credentials](<https://render.com/docs/sandboxes.md#quickstart>).

## Basic example

The following example creates a sandbox and waits until it's running:

**Tab: CLI**

#### Render CLI

```shell
render sandboxes create --timeout=300 --wait
```

Run [`render sandboxes create`][w] with flags for the sandbox's configuration options.

**Tab: TypeScript**

#### TypeScript SDK

```typescript
import { Render } from '@renderinc/sdk'

const sandboxes = new Render().sandboxes

const sandbox = await sandboxes.create({
  timeoutSeconds: 300,
  wait: true
})

console.log(sandbox.id, sandbox.status)
```

Call [`sandboxes.create`][x] with an object containing the sandbox's configuration options.

**Tab: Python (sync)**

#### Python SDK (sync)

```python
from render import Render

sandboxes = Render().sandboxes

sandbox = sandboxes.create(
    timeout_seconds=300,
    wait=True,
)

print(sandbox.id, sandbox.status)
```

Call [`sandboxes.create`][y] with the sandbox's configuration options as keyword parameters.

**Tab: Python (async)**

#### Python SDK (async)

```python
import asyncio
from render import RenderAsync

async def main():
    sandboxes = RenderAsync().sandboxes

    sandbox = await sandboxes.create(
        timeout_seconds=300,
        wait=True,
    )

    print(sandbox.id, sandbox.status)

asyncio.run(main())
```

Call [`sandboxes.create`][y] with the sandbox's configuration options as keyword parameters.

This example sets a five-minute [runtime timeout][k] and waits up to the default timeout of 60 seconds for the sandbox to become ready. After creation succeeds, you can [execute commands][d] and [manage files][e] inside it.

*If you don't provide the `wait` option, the command returns without waiting.* Note that if the wait times out, the sandbox is not automatically terminated, and it might still be in the process of starting up.

## Configuring sandbox behavior

Provide configuration options when you create a sandbox.

### Compute plan

By default, a sandbox uses the *`1c-2g`* compute plan, which provides 1 CPU and 2 GB RAM. You can specify a different compute plan with the following syntax:

**Tab: CLI**

#### Render CLI

```shell
render sandboxes create \
  --wait \
  --plan=2c-4g # highlight-line
```

**Tab: TypeScript**

#### TypeScript SDK

```typescript
const sandbox = await sandboxes.create({
  plan: '2c-4g', // highlight-line
  wait: true
})
```

**Tab: Python (sync)**

#### Python SDK (sync)

```python
sandbox = sandboxes.create(
    plan="2c-4g", # highlight-line
    wait=True,
)
```

**Tab: Python (async)**

#### Python SDK (async)

```python
sandbox = await sandboxes.create(
    plan="2c-4g", # highlight-line
    wait=True,
)
```

For a list of available plans and their specs, see [Sandbox compute plans][z].

When [restoring from a snapshot][f], the new sandbox's plan defaults to matching the original sandbox's plan. Restoring from a runtime snapshot _requires_ the same plan, whereas restoring from a filesystem snapshot supports choosing a different plan.

### Timeouts

A sandbox has two different timeouts that you can [set independently][l].

*To run a sandbox indefinitely, set both of these timeouts to `0`.*

------

##### Runtime timeout

The maximum amount of time a sandbox can run _continuously_ before it automatically terminates, in seconds. Whenever a sandbox is resumed after being suspended, this timeout restarts.

- For a new sandbox, defaults to `86400` (24 hours)
- For a sandbox restored from a [snapshot][f], defaults to the source sandbox's runtime timeout
- Supported range: `60` (1 minute) to `2592000` (30 days), inclusive
- Can be disabled entirely by setting to `0`

*When a sandbox terminates, its local filesystem is permanently lost.* To preserve its state for future sandboxes, [capture a snapshot][f] before it terminates.

##### Idle timeout

The maximum amount of time a sandbox can be idle before it's automatically suspended, in seconds. A sandbox is considered idle if no [command execution][d] or [file transfer][e] is in progress.

- For a new sandbox, defaults to `900` (15 minutes)
- For a sandbox restored from a [snapshot][f], defaults to the source sandbox's idle timeout
- Supported range: `300` (5 minutes) to `86400` (24 hours), inclusive
- Can be disabled entirely by setting to `0`

Executing a command or transferring files restarts this timeout. These actions also automatically resume a suspended sandbox, _if_ that sandbox was suspended within the last 30 days. A suspended sandbox preserves its filesystem and retains its [network policy][p] when it resumes.

Background processes do _not_ keep a sandbox active after the command that started them finishes.

------

#### Setting timeouts

The following examples demonstrate creating a sandbox with a [runtime timeout][k] of one hour and an [idle timeout][n] of 30 minutes.

*To run a sandbox indefinitely, instead set both of these timeouts to `0`.*

**Tab: CLI**

#### Render CLI

When creating a sandbox with [`sandboxes create`][w], set runtime timeout with `--timeout` and idle timeout with `--idle-timeout`:

```shell
render sandboxes create --timeout=3600 --idle-timeout=1800 --wait
```

**Tab: TypeScript**

#### TypeScript SDK

When creating a sandbox with [`sandboxes.create`][x], set runtime timeout with `timeoutSeconds` and idle timeout with `idleTimeoutSeconds`:

```typescript
const sandbox = await sandboxes.create({
  timeoutSeconds: 3600, // Runtime timeout: one hour
  idleTimeoutSeconds: 1800, // Idle timeout: 30 minutes
  wait: true
})
```

**Tab: Python (sync)**

#### Python SDK (sync)

When creating a sandbox with [`sandboxes.create`][y], set runtime timeout with `timeout_seconds` and idle timeout with `idle_timeout_seconds`:

```python
sandbox = sandboxes.create(
    timeout_seconds=3600, # Runtime timeout: one hour
    idle_timeout_seconds=1800, # Idle timeout: 30 minutes
    wait=True,
)
```

**Tab: Python (async)**

#### Python SDK (async)

When creating a sandbox with [`sandboxes.create`][y], set runtime timeout with `timeout_seconds` and idle timeout with `idle_timeout_seconds`:

```python
sandbox = await sandboxes.create(
    timeout_seconds=3600, # Runtime timeout: one hour
    idle_timeout_seconds=1800, # Idle timeout: 30 minutes
    wait=True,
)
```

### Environment variables

While creating a sandbox, you can set environment variables that are available to all commands executed in it:

**Tab: CLI**

#### Render CLI

```shell
render sandboxes create \
  --env-var LOG_LEVEL=debug \
  --env-var API_BASE_URL=https://api.example.com \
  --wait
```

You can also load variables from an environment file:

```shell
render sandboxes create --env-file .env --env-var LOG_LEVEL=debug --wait
```

Repeat `--env-file` to load multiple files. Later files override earlier ones, and `--env-var` values override values loaded from files.

**Tab: TypeScript**

#### TypeScript SDK

```typescript
const sandbox = await sandboxes.create({
  env: {
    LOG_LEVEL: 'debug',
    API_BASE_URL: 'https://api.example.com'
  },
  wait: true
})
```

**Tab: Python (sync)**

#### Python SDK (sync)

```python
sandbox = sandboxes.create(
    env={
        "LOG_LEVEL": "debug",
        "API_BASE_URL": "https://api.example.com",
    },
    wait=True,
)
```

**Tab: Python (async)**

#### Python SDK (async)

```python
sandbox = await sandboxes.create(
    env={
        "LOG_LEVEL": "debug",
        "API_BASE_URL": "https://api.example.com",
    },
    wait=True,
)
```

See [General limits][0] for details on the maximum number and size of environment variables you can provide.

### Network access

By default, a new sandbox allows outbound network traffic to any destination using any protocol. Sandboxes restored from a [snapshot][f] inherit the source sandbox's network policy unless you override it.

You can define an allowlist to restrict your sandbox's outbound traffic to specific HTTPS destinations:

**Tab: CLI**

#### Render CLI

```shell
render sandboxes create \
  --allow-egress-https api.github.com \
  --allow-egress-https '*.pypi.org' \
  --wait
```

To block all outbound traffic, pass `--network-policy=deny-all` instead of the `--allow-egress-https` flags.

**Tab: TypeScript**

#### TypeScript SDK

```typescript
const sandbox = await sandboxes.create({
  networkPolicy: {
    type: 'allow-list',
    rules: [
      { domain: 'api.github.com' },
      { domain: '*.pypi.org' }
    ]
  },
  wait: true
})
```

To block all outbound traffic, provide `networkPolicy: { type: 'deny-all' }` instead.

**Tab: Python (sync)**

#### Python SDK (sync)

```python
from render.sandbox import EgressRule, NetworkPolicy

sandbox = sandboxes.create(
    network_policy=NetworkPolicy(
        type="allow-list",
        rules=[
            EgressRule(domain="api.github.com"),
            EgressRule(domain="*.pypi.org"),
        ],
    ),
    wait=True,
)
```

To block all outbound traffic, provide `network_policy="deny-all"` instead.

**Tab: Python (async)**

#### Python SDK (async)

```python
from render.sandbox import EgressRule, NetworkPolicy

sandbox = await sandboxes.create(
    network_policy=NetworkPolicy(
        type="allow-list",
        rules=[
            EgressRule(domain="api.github.com"),
            EgressRule(domain="*.pypi.org"),
        ],
    ),
    wait=True,
)
```

To block all outbound traffic, provide `network_policy="deny-all"` instead.

- An allowlist supports up to 100 rules.
- Each rule specifies a lowercase hostname, without a scheme, port, or path.
- An exact hostname (such as `example.com`) does not include its subdomains.
  - Use a wildcard such as `*.example.com` to allow subdomains.

If you define an allowlist, Render blocks all traffic to disallowed destinations, _and_ all traffic using a protocol besides HTTPS (regardless of destination).

## Sandbox groups

Every sandbox belongs to a *sandbox group* in your workspace. The sandbox group determines the following:

- The sandbox's region
- The [snapshots][f] available to restore from when creating a sandbox in the group
- The sandbox's [concurrency limit][v]

When you create a sandbox without specifying a group, Render uses your workspace's default group. The first sandbox group created in a workspace is the default. If you create your first sandbox before creating any groups, Render automatically creates a default group for you.

You can create additional groups to organize separate workloads and set a concurrency limit for each.

### Finding groups

List your workspace's groups to find their IDs and identify the default group:

**Tab: CLI**

#### Render CLI

```shell
render sandbox-groups list
```

For the full group details, including the default-group indicator, use JSON output:

```shell
render sandbox-groups list --output json
```

**Tab: TypeScript**

#### TypeScript SDK

```typescript
const entries = await sandboxes.listGroups()

for (const { sandboxGroup } of entries) {
  console.log(sandboxGroup.id, sandboxGroup.name, sandboxGroup.isDefault)
}
```

**Tab: Python (sync)**

#### Python SDK (sync)

```python
result = sandboxes.list_groups()

for group in result.groups:
    print(group.id, group.name, group.is_default)
```

**Tab: Python (async)**

#### Python SDK (async)

```python
result = await sandboxes.list_groups()

for group in result.groups:
    print(group.id, group.name, group.is_default)
```

These examples return up to 20 groups. To retrieve additional groups, use the pagination options in the [TypeScript](<https://render.com/docs/sandboxes-sdk-typescript.md#listgroups>) or [Python](<https://render.com/docs/sandboxes-sdk-python.md#list-groups>) SDK reference.

Group IDs start with `sbg-`. A sandbox's group ID is also returned in its details as `sandboxGroupId` (TypeScript) or `sandbox_group_id` (Python).

### Creating a group

The following example creates a group named `agents`. Group names must be unique within your workspace:

**Tab: CLI**

#### Render CLI

```shell
render sandbox-groups create --name agents
```

**Tab: TypeScript**

#### TypeScript SDK

```typescript
const group = await sandboxes.createGroup({ name: 'agents' })
console.log(group.id)
```

**Tab: Python (sync)**

#### Python SDK (sync)

```python
group = sandboxes.create_group("agents")
print(group.id)
```

**Tab: Python (async)**

#### Python SDK (async)

```python
group = await sandboxes.create_group("agents")
print(group.id)
```

You can also create groups from the *+ New > Sandbox Group* menu in the [Render Dashboard][r]. In the Dashboard, you can optionally place a group in a project environment.

### Choosing a sandbox's group

Provide the group's ID when creating a sandbox. Replace `sbg-abc123` with your group ID:

**Tab: CLI**

#### Render CLI

```shell
render sandboxes create --group=sbg-abc123 --timeout=300 --wait
```

**Tab: TypeScript**

#### TypeScript SDK

```typescript
const sandbox = await sandboxes.create({
  sandboxGroupId: 'sbg-abc123',
  timeoutSeconds: 300,
  wait: true
})
```

**Tab: Python (sync)**

#### Python SDK (sync)

```python
sandbox = sandboxes.create(
    sandbox_group_id="sbg-abc123",
    timeout_seconds=300,
    wait=True,
)
```

**Tab: Python (async)**

#### Python SDK (async)

```python
sandbox = await sandboxes.create(
    sandbox_group_id="sbg-abc123",
    timeout_seconds=300,
    wait=True,
)
```

When creating a sandbox from a [snapshot][f], the snapshot must belong to the selected group.

### Setting group concurrency

Use the SDK to set the maximum number of active sandboxes in a group. The following example sets a limit of 10:

**Tab: TypeScript**

#### TypeScript SDK

```typescript
const group = await sandboxes.updateGroup('sbg-abc123', 10)
console.log(group.concurrencyLimit)
```

**Tab: Python (sync)**

#### Python SDK (sync)

```python
group = sandboxes.update_group("sbg-abc123", concurrency_limit=10)
print(group.concurrency_limit)
```

**Tab: Python (async)**

#### Python SDK (async)

```python
group = await sandboxes.update_group("sbg-abc123", concurrency_limit=10)
print(group.concurrency_limit)
```

This limit must be at least `1` and is capped at your workspace's [per-group concurrency limit][v] (even if you provide a higher value).

## Finding existing sandboxes

You can list sandboxes in your workspace to find their IDs and statuses:

**Tab: CLI**

#### Render CLI

```shell
render sandboxes list --status running
```

To include terminated sandboxes, pass `--all` instead of `--status running`.

**Tab: TypeScript**

#### TypeScript SDK

```typescript
const entries = await sandboxes.list({ status: ['running'] })

for (const { sandbox } of entries) {
  console.log(sandbox.id, sandbox.status)
}
```

To retrieve a single sandbox's details, call `await sandboxes.get('sbx-abc123')`.

**Tab: Python (sync)**

#### Python SDK (sync)

```python
page = sandboxes.list(status="running")

for sandbox in page.sandboxes:
    print(sandbox.id, sandbox.status)
```

To retrieve a single sandbox's details, call `sandboxes.from_id("sbx-abc123")`.

**Tab: Python (async)**

#### Python SDK (async)

```python
page = await sandboxes.list(status="running")

for sandbox in page.sandboxes:
    print(sandbox.id, sandbox.status)
```

To retrieve a single sandbox's details, call `await sandboxes.from_id("sbx-abc123")`.

Without a status filter, sandbox lists exclude terminated sandboxes by default.

The SDKs return one "page" of results at a time. For pagination options, see the [TypeScript](<https://render.com/docs/sandboxes-sdk-typescript.md#list>) and [Python](<https://render.com/docs/sandboxes-sdk-python.md#list>) references.

## Terminating a sandbox

Terminate a sandbox when you no longer need it:

**Tab: CLI**

#### Render CLI

```shell
render sandboxes stop sbx-abc123 --confirm
```

Without `--confirm`, the command previews the operation and leaves the sandbox running.

**Tab: TypeScript**

#### TypeScript SDK

```typescript
await sandboxes.terminate(sandbox.id)
```

**Tab: Python (sync)**

#### Python SDK (sync)

```python
sandboxes.terminate(sandbox.id)
```

**Tab: Python (async)**

#### Python SDK (async)

```python
await sandboxes.terminate(sandbox.id)
```

*Termination is permanent.* You can no longer run commands in the sandbox or retrieve its files.


# Executing Commands in Sandboxes
Source: https://render.com/docs/sandboxes-executing


> *Render Sandboxes is in public beta.*
>
> APIs, defaults, and limits might change during the beta period.

After you [create a sandbox][c], you can start executing commands inside it with the Render CLI or SDK. Commands execute in the sandbox's isolated environment and stream their output back to your client.

- Each command starts in a new shell in your sandbox's home directory.
- Each command inherits the [environment variables](<https://render.com/docs/sandboxes-creating.md#environment-variables>) provided when the sandbox was created.
- Changes to the working directory or shell variables are not preserved across commands.

## Basic example

The following example executes `echo hello` and displays its output and exit code:

**Tab: CLI**

```shell
render sandboxes exec sbx-abc123 -- echo hello
```

Provide the command after the `--` separator so its flags are passed to the command instead of the Render CLI. For example:

```shell
render sandboxes exec sbx-abc123 -- ls -la
```

The CLI streams output directly to your terminal and exits with the command's exit code. To display that code in your shell, use `echo $?` immediately after the command.

**Tab: TypeScript**

```typescript
import { Render } from '@renderinc/sdk'

const sandboxes = new Render().sandboxes
const sandboxId = 'sbx-abc123'

const events = await sandboxes.exec(sandboxId, 'echo hello')

for await (const event of events) {
  if (event.type === 'output') {
    const stream = event.stream === 'stderr' ? process.stderr : process.stdout
    stream.write(event.data)
  } else if (event.type === 'exit') {
    console.log(`Exit code: ${event.exit_code}`)
  }
}
```

Call [`sandboxes.exec`](<https://render.com/docs/sandboxes-sdk-typescript.md#exec>) with the sandbox's ID and a command string. Await the method to obtain an async iterator, then use `for await` to read events as they arrive.

**Tab: Python (sync)**

```python
import sys
from render import Render
from render.sandbox import SandboxExecExit, SandboxExecOutput

sandboxes = Render().sandboxes
sandbox_id = "sbx-abc123"

for event in sandboxes.exec(sandbox_id, "echo hello"):
    if isinstance(event, SandboxExecOutput):
        stream = sys.stderr if event.stream == "stderr" else sys.stdout
        print(event.data, end="", file=stream, flush=True)
    elif isinstance(event, SandboxExecExit):
        print(f"Exit code: {event.exit_code}")
```

Call [`sandboxes.exec`][1] with the sandbox's ID and a command string. Use a `for` loop to read events as they arrive.

**Tab: Python (async)**

```python
import asyncio
import sys
from render import RenderAsync
from render.sandbox import SandboxExecExit, SandboxExecOutput

async def main():
    sandboxes = RenderAsync().sandboxes
    sandbox_id = "sbx-abc123"

    async for event in sandboxes.exec(sandbox_id, "echo hello"):
        if isinstance(event, SandboxExecOutput):
            stream = sys.stderr if event.stream == "stderr" else sys.stdout
            print(event.data, end="", file=stream, flush=True)
        elif isinstance(event, SandboxExecExit):
            print(f"Exit code: {event.exit_code}")

asyncio.run(main())
```

Call [`sandboxes.exec`][1] with the sandbox's ID and a command string. Use `async for` to read events as they arrive. The method returns an async iterator directly, so you don't `await` the method call.

## Streaming events

When you execute a command with either SDK, the `exec` method provides a stream of events that you read in a loop, as shown above:

**Tab: TypeScript**

An *output event* contains a chunk of text in `data`. Its `stream` is either `stdout` or `stderr`:

```json
{
  "type": "output",
  "stream": "stdout",
  "data": "hello\n"
}
```

An *exit event* arrives when the command finishes and contains its exit code:

```json
{
  "type": "exit",
  "exit_code": 0
}
```

**Tab: Python**

An *output event* is a `SandboxExecOutput` object containing a chunk of text in `data`. Its `stream` is either `stdout` or `stderr`:

```python
SandboxExecOutput(stream="stdout", data="hello\n")
```

An *exit event* arrives when the command finishes. It is a `SandboxExecExit` object containing the command's exit code:

```python
SandboxExecExit(exit_code=0)
```

Output arrives in chunks that can contain part of a line or multiple lines. Write each chunk as received to preserve the original output.

## Checking for command failure

An exit event's `exit_code` matches the exit code of the executed command. By convention, `0` indicates success and a nonzero value indicates failure.

*In the Render SDK, a nonzero exit code does not throw or raise an error.* Check the exit event and handle it in your own code:

**Tab: CLI**

```shell
render sandboxes exec sbx-abc123 -- sh -c 'exit 3'
echo $? # 3
```

The CLI's exit code lets scripts and CI jobs check whether the command succeeded.

**Tab: TypeScript**

```typescript
const events = await sandboxes.exec(sandboxId, 'exit 3')

for await (const event of events) {
  if (event.type === 'output') {
    const stream = event.stream === 'stderr' ? process.stderr : process.stdout
    stream.write(event.data)
  } else if (event.type === 'exit' && event.exit_code !== 0) {
    throw new Error(`Command failed with exit code ${event.exit_code}`)
  }
}
```

**Tab: Python (sync)**

```python
for event in sandboxes.exec(sandbox_id, "exit 3"):
    if isinstance(event, SandboxExecOutput):
        stream = sys.stderr if event.stream == "stderr" else sys.stdout
        print(event.data, end="", file=stream, flush=True)
    elif isinstance(event, SandboxExecExit) and event.exit_code != 0:
        raise RuntimeError(f"Command failed with exit code {event.exit_code}")
```

**Tab: Python (async)**

```python
async for event in sandboxes.exec(sandbox_id, "exit 3"):
    if isinstance(event, SandboxExecOutput):
        stream = sys.stderr if event.stream == "stderr" else sys.stdout
        print(event.data, end="", file=stream, flush=True)
    elif isinstance(event, SandboxExecExit) and event.exit_code != 0:
        raise RuntimeError(f"Command failed with exit code {event.exit_code}")
```

Errors connecting to the sandbox or reading its output are reported separately. For all error types, see the [TypeScript](<https://render.com/docs/sandboxes-sdk-typescript.md#error-types>) and [Python](<https://render.com/docs/sandboxes-sdk-python.md#error-types>) SDK references.

## Executing a sequence of commands

To execute a sequence in the same shell, combine commands with `&&`. Each command executes only if the previous one succeeds:

**Tab: CLI**

```shell
render sandboxes exec sbx-abc123 -- sh -c \
  'mkdir -p /tmp/example && cd /tmp/example && echo hello > message.txt && cat message.txt'
```

Use `sh -c` to interpret operators such as `&&`, pipes, and redirection inside the sandbox. The surrounding single quotes prevent your local shell from interpreting them.

**Tab: TypeScript**

```typescript
const events = await sandboxes.exec(
  sandboxId,
  'mkdir -p /tmp/example && cd /tmp/example && echo hello > message.txt && cat message.txt'
)

for await (const event of events) {
  console.log(event)
}
```

**Tab: Python (sync)**

```python
events = sandboxes.exec(
    sandbox_id,
    "mkdir -p /tmp/example && cd /tmp/example && echo hello > message.txt && cat message.txt",
)

for event in events:
    print(event)
```

**Tab: Python (async)**

```python
events = sandboxes.exec(
    sandbox_id,
    "mkdir -p /tmp/example && cd /tmp/example && echo hello > message.txt && cat message.txt",
)

async for event in events:
    print(event)
```

This example creates a directory, changes into it, writes a file, and displays the file's contents. For transferring files between your client and a sandbox, see [Uploading and Downloading Sandbox Files][e].

## Stopping execution

*Disconnecting your client does not stop an executing command inside the sandbox.* This includes interrupting the CLI or canceling a [stream request](<https://render.com/docs/sandboxes-executing.md#streaming-events>).

To stop all processes and permanently remove the sandbox's local filesystem, [terminate the sandbox][j].

Completing or otherwise stopping a command does not terminate the sandbox. It remains available until one of the following occurs:

- You [terminate the sandbox][j].
- The sandbox's [runtime timeout][k] expires.
    - You can disable a sandbox's [timeouts][l] to let it run indefinitely.


# Uploading and Downloading Sandbox Files
Source: https://render.com/docs/sandboxes-files


> *Render Sandboxes is in public beta.*
>
> APIs, defaults, and limits might change during the beta period.

After you [create a sandbox][c], you can upload files and directories to it and download files it produces. Use these operations to provide code and input data, then retrieve results after [executing commands][d].

## Sandbox paths

When specifying a path inside a sandbox:

- *Relative paths* resolve from the sandbox's home directory. For example, `main.py` refers to a file in that directory.
- *Absolute paths* resolve from the sandbox's filesystem root. For example, `/tmp/output.json` refers to a file in `/tmp`.

Commands also start in the sandbox's home directory, so a file uploaded to `main.py` is available to a command like `python main.py`.

## Uploading a file

The following example uploads a local file named `main.py` to the sandbox's home directory:

**Tab: CLI**

```shell
render sandboxes copy ./main.py sbx-abc123:main.py
```

Call [`render sandboxes copy`][2] with the source and destination paths. Prefix the sandbox path with the sandbox's ID and a colon (`:`). You can also use `cp` as an alias for `copy`.

**Tab: TypeScript**

```typescript
import { readFile } from 'node:fs/promises'
import { Render } from '@renderinc/sdk'

const sandboxes = new Render().sandboxes
const sandboxId = 'sbx-abc123'

const data = await readFile('./main.py')
await sandboxes.upload(sandboxId, 'main.py', data)
```

Call [`sandboxes.upload`][3] with the sandbox's ID, the destination path, and the file's contents. The contents can be a string, a `Buffer`, a `Uint8Array`, or a readable stream.

To copy a local file without reading it into memory, call [`sandboxes.copyTo`](<https://render.com/docs/sandboxes-sdk-typescript.md#copyto>):

```typescript
await sandboxes.copyTo(sandboxId, {
  localPath: './main.py',
  remotePath: 'main.py'
})
```

**Tab: Python (sync)**

```python
from render import Render

sandboxes = Render().sandboxes
sandbox_id = "sbx-abc123"

sandboxes.copy_to(sandbox_id, "./main.py", "main.py")
```

Call [`sandboxes.copy_to`][4] with the sandbox's ID, the local source path, and the destination path inside the sandbox.

**Tab: Python (async)**

```python
import asyncio
from render import RenderAsync

async def main():
    sandboxes = RenderAsync().sandboxes
    sandbox_id = "sbx-abc123"

    await sandboxes.copy_to(sandbox_id, "./main.py", "main.py")

asyncio.run(main())
```

Call [`sandboxes.copy_to`][4] with the sandbox's ID, the local source path, and the destination path inside the sandbox.

For a single file, provide the full destination path, including the filename. Uploading to an existing file replaces its contents.

## Downloading a file

The following example downloads a file named `output.json` from the sandbox's home directory:

**Tab: CLI**

```shell
render sandboxes copy sbx-abc123:output.json ./output.json
```

Reverse the source and destination order to download a file. If the local destination is an existing directory, the file is saved inside it with its original filename.

**Tab: TypeScript**

```typescript
import { writeFile } from 'node:fs/promises'

const download = await sandboxes.download(sandboxId, 'output.json')
await writeFile('./output.json', download.data)
```

Call [`sandboxes.download`][5] with the sandbox's ID and the source path. The method returns an object with these fields:

| Field | Description |
| --- | --- |
| `data` | The file's contents as a `Buffer`. |
| `size` | The number of downloaded bytes. |
| `contentType` | The response's content type, if provided. |

The SDK enforces a default file size limit of *256 MB*. If the download exceeds this limit, the SDK stops reading and throws a `SandboxDownloadTooLargeError`. Use `writeFile` to save the returned buffer to your local filesystem.

You can customize this file size limit. For details, see the [SDK reference][5].

To save a file to a local path without holding it in memory, call [`sandboxes.copyFrom`][6]. This method has no size limit by default:

```typescript
await sandboxes.copyFrom(sandboxId, {
  remotePath: 'output.json',
  localPath: './output.json'
})
```

**Tab: Python (sync)**

```python
local_path = sandboxes.copy_from(sandbox_id, "output.json", "./output.json")
print(local_path)
```

Call [`sandboxes.copy_from`][7] with the sandbox's ID, the source path inside the sandbox, and the local destination path. The method saves the file and returns the local path it wrote.

If the local destination is an existing directory, the file is saved inside it with its original filename.

**Tab: Python (async)**

```python
local_path = await sandboxes.copy_from(sandbox_id, "output.json", "./output.json")
print(local_path)
```

Call [`sandboxes.copy_from`][7] with the sandbox's ID, the source path inside the sandbox, and the local destination path. The method saves the file and returns the local path it wrote.

If the local destination is an existing directory, the file is saved inside it with its original filename.

## Transferring directories

You can transfer an entire directory, including its subdirectories. The directory's contents are placed directly inside the destination directory.

For example, if you upload the local directory `./src` to your sandbox's `./app` directory, a local file at `./src/main.py` is uploaded to `./app/main.py` inside the sandbox (not `./app/src/main.py`).

### Uploading a directory

The following example uploads the contents of a local `src` directory to a `src` directory inside the sandbox:

**Tab: CLI**

```shell
render sandboxes copy ./src sbx-abc123:src
```

Provide a local directory as the source path. The CLI transfers its contents automatically. No recursive flag is required.

**Tab: TypeScript**

First, create a tar archive of the directory's contents on your local machine:

```shell
tar -cf src.tar -C ./src .
```

Then upload the archive with `contentType` set to `application/x-tar`. The sandbox extracts its contents into the destination directory:

```typescript
import { createReadStream } from 'node:fs'

await sandboxes.upload(
  sandboxId,
  'src',
  createReadStream('./src.tar'),
  undefined,
  { contentType: 'application/x-tar' }
)
```

The `undefined` parameter leaves the optional workspace ID unset so you can provide the upload options as the fifth parameter.

**Tab: Python (sync)**

```python
sandboxes.copy_to(sandbox_id, "./src", "src")
```

Provide a local directory as the source path. The SDK archives its contents and extracts them into the destination directory automatically.

**Tab: Python (async)**

```python
await sandboxes.copy_to(sandbox_id, "./src", "src")
```

Provide a local directory as the source path. The SDK archives its contents and extracts them into the destination directory automatically.

### Downloading a directory

The following example downloads the contents of an `output` directory from the sandbox:

**Tab: CLI**

```shell
render sandboxes copy sbx-abc123:output ./output
```

The CLI creates the local destination directory if needed and extracts the downloaded contents into it.

**Tab: TypeScript**

Downloading a directory returns its contents as a tar archive. Save the archive to your local filesystem:

```typescript
const download = await sandboxes.download(sandboxId, 'output')
await writeFile('./output.tar', download.data)
```

The same [download size limit][m] applies to the entire tar archive.

Then extract it on your local machine:

```shell
mkdir -p ./output
tar -xf output.tar -C ./output
```

**Tab: Python (sync)**

```python
local_path = sandboxes.copy_from(sandbox_id, "output", "./output")
print(local_path)
```

The SDK creates the local destination directory if needed and extracts the downloaded contents into it.

**Tab: Python (async)**

```python
local_path = await sandboxes.copy_from(sandbox_id, "output", "./output")
print(local_path)
```

The SDK creates the local destination directory if needed and extracts the downloaded contents into it.

## Preserving files

> *Shared filesystems are in early access.*
>
> Use shared filesystems to give sandboxes access to storage that persists beyond their lifecycle. Attach a shared filesystem to multiple sandboxes so agents can work on the same data in parallel and preserve state across runs.

A sandbox keeps its files between commands and while suspended. When the sandbox terminates, its local filesystem is deleted.

Download any files you need before termination. To reuse the sandbox's local filesystem in new sandboxes, [capture a snapshot][f].

Snapshots have a default TTL of 30 days. For details, see [Snapshot retention][8].


# Managing Sandbox Snapshots
Source: https://render.com/docs/sandboxes-snapshots


> *Render Sandboxes is in public beta.*
>
> APIs, defaults, and limits might change during the beta period.

After you [create a sandbox][c], you can capture its state in a *snapshot*. You can restore from a snapshot to create new sandboxes with the same prepared filesystem or resume a process from a saved state.

Snapshots are useful for reusing installed packages, preparing environments for agents, and saving progress before a sandbox terminates.

A sandbox must be actively running to capture a snapshot. Creating a snapshot does not terminate the sandbox.

## Kinds of snapshots

Render supports two kinds of sandbox snapshots:

| Kind | Description |
| --- | --- |
| *Runtime snapshot* | Captures the writable filesystem, along with memory and CPU state. Use this to resume running processes from their captured state in a new sandbox. Restoring from a runtime snapshot requires the exact same compute plan as the source sandbox. |
| *Filesystem snapshot* | Captures the writable filesystem only. Use this to reuse files and installed packages in a new sandbox, without preserving running processes. Restoring from a filesystem snapshot supports any compute plan. |

## Capturing a snapshot

The following example captures a filesystem snapshot and waits until it's available. Replace `sbx-abc123` with your sandbox's ID:

**Tab: CLI**

```shell
render sandboxes snapshots create sbx-abc123 --kind filesystem --wait
```

The command prints the snapshot's ID and details after capture completes.

**Tab: TypeScript**

```typescript
import { Render } from '@renderinc/sdk'

const sandboxes = new Render().sandboxes

const snapshot = await sandboxes.snapshots.create({
  sandboxId: 'sbx-abc123',
  kind: 'filesystem',
  wait: true
})

console.log(snapshot.id, snapshot.status)
```

Call [`snapshots.create`][9] with the source sandbox's ID and the snapshot options.

**Tab: Python (sync)**

```python
from render import Render

sandboxes = Render().sandboxes

snapshot = sandboxes.snapshots.create(
    "sbx-abc123",
    kind="filesystem",
    wait=True,
)

print(snapshot.id, snapshot.status)
```

Call [`snapshots.create`][aa] with the source sandbox's ID and the snapshot options as keyword parameters.

**Tab: Python (async)**

```python
import asyncio
from render import RenderAsync

async def main():
    sandboxes = RenderAsync().sandboxes

    snapshot = await sandboxes.snapshots.create(
        "sbx-abc123",
        kind="filesystem",
        wait=True,
    )

    print(snapshot.id, snapshot.status)

asyncio.run(main())
```

Call [`snapshots.create`][aa] with the source sandbox's ID and the snapshot options as keyword parameters.

To capture a runtime snapshot instead, set the kind to `runtime` or omit the kind option.

The wait option waits up to *five minutes* for capture to complete. If you omit it, creation returns before the snapshot is available. If the wait times out, capture continues. Check the snapshot's [current status][ab] before starting another capture.

## Restoring from a snapshot

Restore from a snapshot by providing its ID when you create a sandbox. Each restore creates a new sandbox, preserving the snapshot for reuse.

Snapshots always belong to the same [sandbox group][t] as their source sandbox. Provide that group's ID when restoring. You can restore from a snapshot only into another sandbox in the same group.

**Tab: CLI**

Replace `snp-abc123` with the ID returned by snapshot creation and `sbg-abc123` with its sandbox group ID. You can find group IDs with `render sandbox-groups list`:

```shell
render sandboxes create --snapshot-id snp-abc123 \
  --group sbg-abc123 --timeout=300 --wait
```

**Tab: TypeScript**

```typescript
const restored = await sandboxes.create({
  snapshotId: snapshot.id,
  sandboxGroupId: snapshot.sandboxGroupId,
  timeoutSeconds: 300,
  wait: true
})

console.log(restored.id, restored.status)
```

**Tab: Python (sync)**

```python
restored = sandboxes.create(
    snapshot_id=snapshot.id,
    sandbox_group_id=snapshot.sandbox_group_id,
    timeout_seconds=300,
    wait=True,
)

print(restored.id, restored.status)
```

**Tab: Python (async)**

```python
restored = await sandboxes.create(
    snapshot_id=snapshot.id,
    sandbox_group_id=snapshot.sandbox_group_id,
    timeout_seconds=300,
    wait=True,
)

print(restored.id, restored.status)
```

These examples wait until the restored sandbox is running and set a five-minute runtime timeout. You can then [execute commands][d] or [manage files][e] inside it.

### Restored state and configuration

Restoring from a snapshot preserves most characteristics of the source sandbox by default. Where indicated below, you can override certain defaults when restoring:

------

##### Filesystem

Preserved.

##### Running processes

Preserved by runtime snapshots.

_Not_ preserved by filesystem snapshots.

##### Compute plan

Preserved by default.

- Filesystem snapshots support specifying a different plan when restoring.
- Runtime snapshots do not.

##### Network policy

Preserved by default (including any allowlist rules).

Override by providing a network policy when restoring.

##### Environment variables

- _New_ commands use the environment variables you provide when restoring.
- Processes resumed from a runtime snapshot retain their original environment.
    - These processes do _not_ have access to the new environment variables you provide when restoring.

##### Runtime timeout

Preserved by default. Restarts in the restored sandbox.

Override by providing a runtime timeout when restoring.

##### Idle timeout

Preserved by default. Restarts in the restored sandbox.

Override by providing an idle timeout when restoring.

------

### Restoring by name

You can name a snapshot when you capture it, then restore from it by name instead of ID:

**Tab: CLI**

Replace `sbg-abc123` with the group ID of the source sandbox (`sbx-abc123`):

```shell
render sandboxes snapshots create sbx-abc123 \
  --kind filesystem --name prepared-env --wait

render sandboxes create --from prepared-env --group sbg-abc123 --wait
```

The `--from` flag accepts either a snapshot name or ID. Do not combine it with `--snapshot-id`.

**Tab: TypeScript**

```typescript
const snapshot = await sandboxes.snapshots.create({
  sandboxId: 'sbx-abc123',
  kind: 'filesystem',
  name: 'prepared-env',
  wait: true
})

const restored = await sandboxes.create({
  snapshotName: 'prepared-env',
  sandboxGroupId: snapshot.sandboxGroupId,
  wait: true
})
```

**Tab: Python (sync)**

```python
snapshot = sandboxes.snapshots.create(
    "sbx-abc123",
    kind="filesystem",
    name="prepared-env",
    wait=True,
)

restored = sandboxes.create(
    snapshot_name="prepared-env",
    sandbox_group_id=snapshot.sandbox_group_id,
    wait=True,
)
```

**Tab: Python (async)**

```python
snapshot = await sandboxes.snapshots.create(
    "sbx-abc123",
    kind="filesystem",
    name="prepared-env",
    wait=True,
)

restored = await sandboxes.create(
    snapshot_name="prepared-env",
    sandbox_group_id=snapshot.sandbox_group_id,
    wait=True,
)
```

Names are case-sensitive and scoped to a sandbox group. If you reuse a name, restoring by that name uses the most recently available snapshot with that name in the selected sandbox group.

A snapshot's name has a maximum of 64 characters and cannot begin with `snp-`.

## Retrieving snapshot details

### Listing snapshots

List snapshots in a sandbox group to find their IDs and statuses. The following example lists snapshots that are available to restore from:

**Tab: CLI**

```shell
render sandboxes snapshots list --group sbg-abc123 --status available
```

**Tab: TypeScript**

```typescript
const entries = await sandboxes.snapshots.list({
  sandboxGroupId: snapshot.sandboxGroupId,
  status: ['available']
})

for (const { snapshot } of entries) {
  console.log(snapshot.id, snapshot.name, snapshot.status)
}
```

**Tab: Python (sync)**

```python
page = sandboxes.snapshots.list(
    sandbox_group_id=snapshot.sandbox_group_id,
    status="available",
)

for listed_snapshot in page.snapshots:
    print(listed_snapshot.id, listed_snapshot.name, listed_snapshot.status)
```

**Tab: Python (async)**

```python
page = await sandboxes.snapshots.list(
    sandbox_group_id=snapshot.sandbox_group_id,
    status="available",
)

for listed_snapshot in page.snapshots:
    print(listed_snapshot.id, listed_snapshot.name, listed_snapshot.status)
```

Results are ordered newest first. Omit the status filter to include snapshots with any status. Deleted and expired snapshots are excluded.

The SDKs return one page at a time. Use the cursor from the last entry (TypeScript) or `next_cursor` (Python) to retrieve additional pages. For pagination options, see the [TypeScript](<https://render.com/docs/sandboxes-sdk-typescript.md#snapshots-list>) and [Python](<https://render.com/docs/sandboxes-sdk-python.md#snapshots-list>) references.

### Retrieving a snapshot

You can retrieve a snapshot to check its status, capture error, expiration time, and other details:

**Tab: CLI**

```shell
render sandboxes snapshots get snp-abc123 --group sbg-abc123
```

**Tab: TypeScript**

```typescript
const currentSnapshot = await sandboxes.snapshots.get({
  sandboxGroupId: snapshot.sandboxGroupId,
  snapshotId: snapshot.id
})

console.log(currentSnapshot.status, currentSnapshot.error)
```

**Tab: Python (sync)**

```python
current_snapshot = sandboxes.snapshots.from_id(
    sandbox_group_id=snapshot.sandbox_group_id,
    snapshot_id=snapshot.id,
)

print(current_snapshot.status, current_snapshot.error)
```

**Tab: Python (async)**

```python
current_snapshot = await sandboxes.snapshots.from_id(
    sandbox_group_id=snapshot.sandbox_group_id,
    snapshot_id=snapshot.id,
)

print(current_snapshot.status, current_snapshot.error)
```

Lookup, listing, and deletion methods all require the snapshot's sandbox group ID.

### Snapshot status

A snapshot has one of the following statuses:

| Status | Description |
| --- | --- |
| *`creating`* | *Capture is in progress.* New sandboxes cannot yet be restored from the snapshot. |
| *`available`* | *Capture succeeded.* New sandboxes can now be restored from the snapshot. |
| *`failed`* | *Capture failed.* Check the snapshot's `error` field for details. |

### Waiting for an existing snapshot

If you [captured a snapshot][ac] without waiting, you can wait for it to become available with the following approaches:

**Tab: CLI**

Use `render sandboxes snapshots get` to check the snapshot's status:

```shell
render sandboxes snapshots get snp-abc123 --group sbg-abc123
```

To wait in a script, call this command in a polling loop while the status is `creating`, pausing between checks. Stop when the status is `available` or `failed`. Add `--output json` to read the status programmatically.

**Tab: TypeScript**

```typescript
const availableSnapshot = await sandboxes.snapshots.waitUntilAvailable({
  sandboxGroupId: snapshot.sandboxGroupId,
  snapshotId: snapshot.id
})
```

**Tab: Python (sync)**

```python
available_snapshot = sandboxes.snapshots.wait_until_available(
    sandbox_group_id=snapshot.sandbox_group_id,
    snapshot_id=snapshot.id,
)
```

**Tab: Python (async)**

```python
available_snapshot = await sandboxes.snapshots.wait_until_available(
    sandbox_group_id=snapshot.sandbox_group_id,
    snapshot_id=snapshot.id,
)
```

The SDK methods wait up to five minutes by default and raise an error if capture fails or the wait times out.

## Snapshot retention

Snapshots have a default time-to-live (TTL) of 30 days, after which they are [deleted](<https://render.com/docs/sandboxes-snapshots.md#snapshot-deletion>). This TTL refreshes each time you [restore from a snapshot][ad].

You can customize or disable a snapshot's TTL during [capture][ac]. The examples below demonstrate setting a TTL of 24 hours.

*To disable automatic deletion, set the TTL to `0`.*

**Tab: TypeScript**

```typescript
const snapshot = await sandboxes.snapshots.create({
  sandboxId: 'sbx-abc123',
  kind: 'filesystem',
  ttlSeconds: 24 * 60 * 60, // highlight-line
  wait: true
})
```

> *The [`ttlSeconds`](<https://render.com/docs/sandboxes-sdk-typescript.md#ttlseconds>) option replaced the `expiresAt` option in SDK version 1.9.0.*
>
> Upgrading from an earlier SDK version requires updating your code to use the new option.

**Tab: Python (sync)**

```python
snapshot = sandboxes.snapshots.create(
    "sbx-abc123",
    kind="filesystem",
    ttl_seconds=24 * 60 * 60, # highlight-line
    wait=True,
)
```

> *The [`ttl_seconds`][ae] option replaced the `expires_at` option in SDK version 1.9.0.*
>
> Upgrading from an earlier SDK version requires updating your code to use the new option.

**Tab: Python (async)**

```python
snapshot = await sandboxes.snapshots.create(
    "sbx-abc123",
    kind="filesystem",
    ttl_seconds=24 * 60 * 60, # highlight-line
    wait=True,
)
```

> *The [`ttl_seconds`][ae] option replaced the `expires_at` option in SDK version 1.9.0.*
>
> Upgrading from an earlier SDK version requires updating your code to use the new option.

To check a snapshot's current expiration time, [retrieve the snapshot][ab] and read the `expiresAt` (TypeScript) or `expires_at` (Python) property. The CLI also shows this value in snapshot details.

## Snapshot deletion

> *You can't retrieve or restore from a deleted snapshot.*
>
> Existing sandboxes restored from a deleted snapshot are unaffected.

Delete a snapshot when you no longer need to restore from it. You cannot delete a snapshot while its status is `creating`.

**Tab: CLI**

```shell
render sandboxes snapshots delete snp-abc123 --group sbg-abc123 --confirm
```

Without `--confirm`, the command previews the deletion and makes no changes.

**Tab: TypeScript**

```typescript
await sandboxes.snapshots.delete({
  sandboxGroupId: snapshot.sandboxGroupId,
  snapshotId: snapshot.id
})
```

**Tab: Python (sync)**

```python
sandboxes.snapshots.delete(
    sandbox_group_id=snapshot.sandbox_group_id,
    snapshot_id=snapshot.id,
)
```

**Tab: Python (async)**

```python
await sandboxes.snapshots.delete(
    sandbox_group_id=snapshot.sandbox_group_id,
    snapshot_id=snapshot.id,
)
```

Render also automatically deletes a snapshot when its [TTL expires][8].


# Claude Managed Agents with Render Sandboxes
Source: https://render.com/docs/sandboxes-claude-managed-agents


> *Render Sandboxes is in public beta.*
>
> APIs, defaults, and limits might change during the beta period.

You can use [Render Sandboxes][a] with [Claude Managed Agents](https://platform.claude.com/docs/en/managed-agents/overview) to integrate Claude's core agent loop with isolated, self-hosted code execution in your Render workspace. Anthropic hosts the loop as usual, while the sandbox executes Claude's commands and file edits.

*This tutorial walks through running a basic coding agent that:*

1. Accepts a user prompt and sends it to Claude,
2. Executes Claude-generated commands in a [Render sandbox][a], and
3. Copies the resulting output files to the user's machine.

For details, see [How the agent runs](<https://render.com/docs/sandboxes-claude-managed-agents.md#how-the-agent-runs>).

## Prerequisites

Before you start, make sure you have all of the following:

*Render*

- A Render [API key][q]
- Your Render workspace ID
    - Obtain this from the top of your workspace's *Settings* page in the [Render Dashboard][r].

*Anthropic*

- An [Anthropic API key][af]
- Access to the [Claude Managed Agents beta](https://platform.claude.com/docs/en/managed-agents/overview#beta-access)
- An existing Managed Agents agent and a dedicated `self_hosted` environment, with an environment key generated in the Claude Console
    - The Anthropic API can create an environment, but it can't generate the environment's key.

*Installed tooling*

- Git
- Node.js 22 or later

## Setup

### 1. Clone the template

> *The template code for this tutorial is available on [GitHub](https://github.com/render-examples/claude-managed-agents-sandbox).*

Clone the template and install its dependencies:

```shell
git clone https://github.com/render-examples/claude-managed-agents-sandbox
cd claude-managed-agents-sandbox
npm ci
```

### 2. Configure credentials

1. Copy the example environment file to `.env`:

    ```shell
    cp .env.example .env
    ```

    The file looks like this:

      ```bash
      # Render
      RENDER_API_KEY=
      RENDER_WORKSPACE_ID=

      # Anthropic
      ANTHROPIC_API_KEY=
      ANTHROPIC_AGENT_ID=
      ANTHROPIC_ENVIRONMENT_ID=
      ANTHROPIC_ENVIRONMENT_KEY=
      ```

2. Populate the values for these environment variables according to the table below:

    | Environment variable | Description |
    | --- | --- |
    | `RENDER_API_KEY` | Your Render [API key][q]. Starts with `rnd_` |
    | `RENDER_WORKSPACE_ID` | Your Render workspace's ID, available at the top of its *Settings* page in the [Render Dashboard][r]. Starts with `tea-` |
    | `ANTHROPIC_API_KEY` | Your [Anthropic API key][af]. Starts with `sk-ant-api03-` The template uses this key locally to manage your Claude Managed Agents session. It is _not_ passed into the sandbox. |
    | `ANTHROPIC_AGENT_ID` | The ID of your Managed Agents agent. Starts with `agent_` |
    | `ANTHROPIC_ENVIRONMENT_ID` | The ID of your dedicated `self_hosted` environment. Starts with `env_` |
    | `ANTHROPIC_ENVIRONMENT_KEY` | The key generated for your self-hosted environment in the Claude Console. Starts with `sk-ant-oat01-` |

### 3. Perform your first agent run

This example handles one prompt per run and does not support follow-up messages. Provide a task Claude can complete without additional input.

Run the agent with a prompt:

```shell
npm run agent -- "Create a hello world HTTP server in /workspace/output. Test it before you finish."
```

Claude's activity streams to your terminal, resembling the following:

```
preflight     passed
policy        default-deny allow-list: api.anthropic.com and pinned ant release download hosts
credential    materialized restricted Anthropic Environment key; application API key excluded
provision     sbx-...
worker        polling
session       sesn_...
session       submitted
session       running
tool          write
tool          bash
agent         I created /workspace/output/server.js and confirmed it responds with "Hello, world!".
result        task completed
outputs       copied 1 file to runs/run_.../output
cleanup       session deleted; sandbox terminated
```

In this example:

1. Claude created a web server and tested it inside the sandbox.
2. The runner copied the server to your machine.
3. The runner deleted the session and terminated the sandbox to clean up.

### 4. Customize agent capabilities (optional)

> *These customization methods are specific to this template.*
>
> For general-purpose customization of Render Sandboxes, see [Configuring sandbox behavior][s].

| Customization | Description |
| --- | --- |
| *Toolchain* | You can install additional command-line tools for Claude to use inside the sandbox. Add installation commands to `scripts/install-executor.sh`, and add their download hosts to `INSTALL_DESTINATIONS` in `src/policy.ts`. The template uploads this script to each new sandbox and executes it there before starting Anthropic's `ant` CLI. |
| *Network access* | You can customize the sandbox's [network access][p] to allow outbound traffic to additional HTTPS destinations. Add the desired hostnames to `RUNTIME_DESTINATIONS` in `src/policy.ts` to include them in the sandbox's allowlist. |
| *Run timeout* | You can set a time limit for the overall agent run, including sandbox setup, task execution, and output collection. Pass `--timeout <seconds>` (the default is `600`). The runner also derives a separate sandbox runtime timeout from this value in `src/agent.ts`. |
| *Outputs* | You can choose where generated output files are saved on your machine. Pass `--output <path>` to specify a local destination directory. The default is `runs/<run_id>/output`. To change which files the template collects from the sandbox, edit `src/outputs.ts`. |

To change Claude's system prompt or available tools, update your [Managed Agents agent configuration](https://platform.claude.com/docs/en/managed-agents/agent-setup). The template uses the agent specified by `ANTHROPIC_AGENT_ID`.

## How the agent runs

The template runs on your local machine. Its [`src/agent.ts`](https://github.com/render-examples/claude-managed-agents-sandbox/blob/main/src/agent.ts) coordinates each run through the following stages:

------

##### Sandbox creation

The template checks that your agent and self-hosted environment exist and that no other process is waiting to receive sessions for your Anthropic environment. It then creates a Render sandbox and waits until it's running.

It passes the environment ID and environment key into the sandbox, as defined in [`src/policy.ts`](https://github.com/render-examples/claude-managed-agents-sandbox/blob/main/src/policy.ts).

##### Anthropic CLI startup

The template installs a pinned release of Anthropic's `ant` CLI inside the sandbox with [`scripts/install-executor.sh`](https://github.com/render-examples/claude-managed-agents-sandbox/blob/main/scripts/install-executor.sh), verifying its checksum.

It then starts `ant` to check Anthropic for queued sessions, and waits until Anthropic reports that the process is ready before creating a session.

##### Session start

From your local machine, the template calls the Anthropic API to create a session for your configured agent and environment. The same local process opens the session's event stream, starts reading events, and submits your prompt.

##### Task execution

Claude runs the agent loop on Anthropic infrastructure. When Claude requests a command or file edit, the `ant` process executes it inside the sandbox and sends the result back to Anthropic.

The template streams session events and Claude's response to your terminal.

##### File collection and cleanup

When Claude finishes its turn, the template downloads regular files from `/workspace/output` in the sandbox to `runs/<run_id>/output` on your machine. It then deletes the session and terminates the sandbox, keeping your shared agent and environment for future runs.

Cleanup also runs after a failure, a timeout, `Ctrl+C`, or `SIGTERM`. If cleanup fails, follow the instructions under [Troubleshooting](<https://render.com/docs/sandboxes-claude-managed-agents.md#troubleshooting>).

Each run also saves the following files under `runs/<run_id>/`:

- `run.json`: Resource IDs, network policy, and cleanup status, without credentials.
- `events.jsonl`: Session events.
- `result.txt`: Claude's final response.

------

## Security considerations

- *Your Anthropic API key never enters the sandbox.*

    Any code that Claude executes in the sandbox can read the sandbox's environment variables. Make sure that any values you set are safe to expose.

    Do not reuse your Managed Agents `self_hosted` environment for purposes other than this agent's sandboxes. Otherwise, another process connected to the same environment could receive your session and execute its commands outside the intended sandbox.

- *Credential brokering for Render Sandboxes is [not yet generally available][ag].*

    The template currently sets the environment key as an environment variable during sandbox creation. This behavior is defined entirely in `src/policy.ts`.

- *Sandbox [network access][p] is managed via allowlist.*

    The only hosts required by this template are `api.anthropic.com` and the GitHub release hosts for the `ant` CLI. The GitHub hosts remain allowed throughout the run, even after installation finishes.

    Tool inputs and outputs pass through Anthropic, because Anthropic hosts the agent loop.

## Troubleshooting

###### Preflight fails.

Confirm your Managed Agents beta access, your Anthropic API key's permissions, and your agent and environment IDs. The environment must be `self_hosted`.

###### Preflight reports a polling worker.

Another process is waiting to receive sessions for your Anthropic environment and could claim this run. Stop that process, or use a dedicated environment.

Anthropic can also report the template's previous `ant` process for about a minute after a run ends. Wait a minute, then run the agent again.

###### The worker never starts polling.

Check the `[worker:stderr]` lines for authentication errors. Confirm that the environment key belongs to the configured environment.

###### The agent produces no output files.

Inspect `runs/<run_id>/events.jsonl` and `result.txt`. Output files are optional, so prompts that need files should ask Claude to write them under `/workspace/output`.

###### Cleanup is incomplete.

If a cleanup step fails, the runner prints the command that finishes it, with the resource ID filled in. Delete the per-run session and terminate the sandbox, but keep the shared agent and environment.

The commands read your credentials from your shell, so load `.env` from the template directory before you run them:

```shell
set -a && source .env && set +a
```

The command that terminates a sandbox requires version 2.33.0 or later of the [Render CLI][ah].

If session creation fails without a clear answer from the API, the runner also prints a `reconcile` command that lists recent sessions, so you can find and delete one that might have been created.



# Cursor Cloud Agents with Render Sandboxes
Source: https://render.com/docs/sandboxes-cursor-cloud-agents


> *Render Sandboxes is in public beta.*
>
> APIs, defaults, and limits might change during the beta period.

You can use [Render Sandboxes][a] with [Cursor Cloud Agents](https://cursor.com/docs/cloud-agent/self-hosted/pool) to integrate Cursor's core agent loop with isolated, self-hosted code execution in your Render workspace. Cursor hosts the loop as usual, while the sandbox executes the agent's commands and file edits.

*This tutorial walks through running a basic coding agent that:*

1. Accepts a user prompt and sends it to Cursor,
2. Executes the agent's commands in a [Render sandbox][a], and
3. Copies the resulting output files to the user's machine.

For details, see [How the agent runs](<https://render.com/docs/sandboxes-cursor-cloud-agents.md#how-the-agent-runs>).

## Prerequisites

Before you start, make sure you have all of the following:

*Render*

- A Render [API key][q]
- Your Render workspace ID
    - Obtain this from the top of your workspace's *Settings* page in the [Render Dashboard][r].

*Cursor*

- A Cursor Enterprise plan with [Self-Hosted Machines enabled](https://cursor.com/docs/cloud-agent/self-hosted/pool#prerequisites)
- A [service account API key][ai] with agent scope
- An existing, named [any-repository Team Pool][aj]

*Installed tooling*

- Git
- Node.js 22 or later

## Setup

### 1. Clone the template

> *The template code for this tutorial is available on [GitHub](https://github.com/render-examples/cursor-cloud-agent-sandbox).*

Clone the template and install its dependencies:

```shell
git clone https://github.com/render-examples/cursor-cloud-agent-sandbox
cd cursor-cloud-agent-sandbox
npm ci
```

### 2. Configure credentials

1. Copy the example environment file to `.env`:

    ```shell
    cp .env.example .env
    ```

    The file includes the following required environment variables:

    ```bash
    # Render
    RENDER_API_KEY=
    RENDER_WORKSPACE_ID=

    # Cursor
    CURSOR_API_KEY=
    CURSOR_POOL=
    ```

2. Populate the values for these environment variables according to the table below:

    | Environment variable | Description |
    | --- | --- |
    | `RENDER_API_KEY` | Your Render [API key][q]. Starts with `rnd_` |
    | `RENDER_WORKSPACE_ID` | Your Render workspace's ID, available at the top of its *Settings* page in the [Render Dashboard][r]. Starts with `tea-` |
    | `CURSOR_API_KEY` | Your Cursor [service account API key][ai] with agent scope. The template uses this key locally to manage your Cloud Agent and its pool claim. It is _not_ passed into the sandbox. |
    | `CURSOR_POOL` | The name of your [any-repository Team Pool][aj], such as `my-pool`. |

### 3. Perform your first agent run

This example handles one prompt per run and does not support follow-up messages. Provide a task the agent can complete without additional input.

Make sure no other process can claim work from your pool, then run the agent with a prompt:

```shell
npm run agent -- "Create a hello world HTTP server in /workspace/output. Test it before you finish."
```

The agent's activity streams to your terminal, resembling the following:

```
preflight     passed
agent         bc-...
claim         bc-... → pw_render_...
provision     sbx-...
worker        connected
cursor:status RUNNING
cursor:tool   edit_file completed
cursor:tool   run_terminal_cmd completed
cursor:result FINISHED
agent         I created /workspace/output/server.js and confirmed it responds with "Hello, world!".
result        FINISHED (stream)
outputs       copied 1 file to runs/run_.../output
cleanup       Cloud Agent deleted; claim released; sandbox terminated; Team Pool retained
run           runs/run_...
```

In this example:

1. The agent created a web server and tested it inside the sandbox.
2. The runner copied the server to your machine.
3. The runner released the claim, deleted the Cloud Agent, and terminated the sandbox to clean up.

### 4. Customize agent capabilities (optional)

> *These customization methods are specific to this template.*
>
> For general-purpose customization of Render Sandboxes, see [Configuring sandbox behavior][s].

| Customization | Description |
| --- | --- |
| *Toolchain* | You can install additional command-line tools for the agent to use inside the sandbox. Add installation commands to `scripts/install-executor.sh`, and add their download hosts to `INSTALL_DESTINATIONS` in `src/launch-policy.ts`. The template uploads this script to each new sandbox and executes it there before starting Cursor's `agent worker` process. |
| *Network access* | You can customize the sandbox's [network access][p] to allow outbound traffic to additional HTTPS destinations. Add the desired hostnames to `RUNTIME_DESTINATIONS` in `src/launch-policy.ts` to include them in the sandbox's allowlist. |
| *Run timeout* | You can set a time limit for the overall agent run, including sandbox setup, task execution, and output collection. Pass `--timeout <seconds>` or set `AGENT_TIMEOUT_SECONDS` (the default is `600`). The runner also derives a separate sandbox runtime timeout from this value in `src/agent.ts`. |
| *Outputs* | You can choose where generated output files are saved on your machine. Pass `--output <path>` to specify a local destination directory. The default is `runs/<run_id>/output`. To change which files the template collects from the sandbox, edit `src/outputs.ts`. |

## How the agent runs

The template runs on your local machine. Its [`src/agent.ts`](https://github.com/render-examples/cursor-cloud-agent-sandbox/blob/main/src/agent.ts) coordinates each run through the following stages:

------

##### Agent creation and claim

From your local machine, the template checks that the configured Team Pool exists and isn't tied to a repository. It then calls the Cursor API to create a Cloud Agent with your prompt, targeting that pool.

The template [claims the agent's queued work](https://cursor.com/docs/cloud-agent/api/endpoints#claim-a-pending-request) for this run's sandbox, reserving it so another process can't take it. Cursor returns a session token that can serve only that claim.

##### Sandbox creation

The template creates a Render sandbox and waits until it's running. Its network policy and environment variables are defined in [`src/launch-policy.ts`](https://github.com/render-examples/cursor-cloud-agent-sandbox/blob/main/src/launch-policy.ts).

##### Cursor CLI startup

The template installs a pinned release of Cursor's `agent` CLI inside the sandbox with [`scripts/install-executor.sh`](https://github.com/render-examples/cursor-cloud-agent-sandbox/blob/main/scripts/install-executor.sh), verifying its checksum.

It then writes the session token to a file in the sandbox and starts `agent worker` for that claim. The template confirms that the process is ready and connected to the expected Cloud Agent.

##### Task execution

Cursor runs the agent loop on its infrastructure. When the agent requests a command or file edit, the `agent worker` process executes it inside the sandbox and sends the result back to Cursor.

The template streams run events and the agent's response to your terminal.

##### File collection and cleanup

When the run finishes successfully, the template downloads regular files from `/workspace/output` in the sandbox to `runs/<run_id>/output` on your machine. It then releases the claim, deletes the Cloud Agent, and terminates the sandbox, keeping your shared Team Pool for future runs.

Cleanup also runs after a failure, a timeout, `Ctrl+C`, or `SIGTERM`. If cleanup fails, follow the instructions under [Troubleshooting](<https://render.com/docs/sandboxes-cursor-cloud-agents.md#troubleshooting>).

Each run also saves the following files under `runs/<run_id>/`:

- `run.json`: Resource IDs, network policy, and cleanup status, without credentials.
- `events.jsonl`: Run events.
- `result.txt`: The agent's final response.

------

## Security considerations

- *Your Cursor API key never enters the sandbox.*

    Any code that the agent executes in the sandbox can read the session token and any other credentials you place there. Make sure that any values you set are safe to expose.

    Use a dedicated Team Pool with no other processes waiting to claim work. Otherwise, another process could receive your run and execute its commands outside the intended sandbox.

- *Credential brokering for Render Sandboxes is [not yet generally available][ag].*

    The template currently writes the session token to a file in the sandbox. This behavior is defined entirely in `src/launch-policy.ts`.

- *Sandbox [network access][p] is managed via allowlist.*

    The template allows HTTPS traffic to Cursor's [session and artifact hosts](https://cursor.com/docs/cloud-agent/self-hosted/pool#networking), `cursor.com`, and `downloads.cursor.com`. The download host remains allowed throughout the run, even after installation finishes.

    Tool inputs and outputs pass through Cursor, because Cursor hosts the agent loop.

## Troubleshooting

###### Preflight fails.

Confirm that Self-Hosted Machines is enabled, that the pool name is correct, that the pool is an any-repository pool, and that the service account key has agent scope.

###### The pool request is never claimed.

Confirm that the request targets the configured pool and that another process hasn't claimed it first.

###### The worker never becomes ready.

Check the `[worker:stderr]` lines, the session token, and the sandbox's network access. The process must report ready at `/readyz`, and Cursor must show it connected to the expected Cloud Agent.

###### The agent produces no output files.

Inspect `runs/<run_id>/events.jsonl` and `result.txt`. Output files are optional, so prompts that need files should ask the agent to write them under `/workspace/output`.

###### Cleanup is incomplete.

If a cleanup step fails, the runner prints the commands that finish it, with the resource IDs filled in. Release the claim, delete the per-run Cloud Agent, and terminate the sandbox, but keep the shared Team Pool.

The commands read your credentials from your shell, so load `.env` from the template directory before you run them:

```shell
set -a && source .env && set +a
```

The command that terminates a sandbox requires version 2.33.0 or later of the [Render CLI][ah].

If Cloud Agent creation fails without a clear answer from the API, the runner also prints a `reconcile` command that lists recent Cloud Agents, so you can find and permanently delete one that might have been created.



# OpenAI Agents API with Render Sandboxes
Source: https://render.com/docs/sandboxes-openai-agents-api


> *Render Sandboxes is in public beta.*
>
> APIs, defaults, and limits might change during the beta period.

You can use [Render Sandboxes][a] with the [OpenAI Agents API](https://developers.openai.com/api/docs/guides/agents-api/environments/self-hosted) to integrate the Codex agent loop with isolated, self-hosted code execution in your Render workspace. OpenAI hosts the loop as usual, while the sandbox executes Codex's commands and file edits.

*This tutorial walks through running a basic coding agent that:*

1. Accepts a user prompt and sends it to Codex,
2. Executes Codex-generated commands in a [Render sandbox][a], and
3. Copies the resulting output files to the user's machine.

For details, see [How the agent runs](<https://render.com/docs/sandboxes-openai-agents-api.md#how-the-agent-runs>).

## Prerequisites

Before you start, make sure you have all of the following:

*Render*

- A Render [API key][q]
- Your Render workspace ID
    - Obtain this from the top of your workspace's *Settings* page in the [Render Dashboard][r].

*OpenAI*

- Access to the [OpenAI Agents API](https://developers.openai.com/api/docs/guides/agents-api/overview)
- An [OpenAI API key][ak] with permission to manage Agents API sessions and run model inference
- A separate [environment key][al], created on the *Agents* tab

*Installed tooling*

- Git
- Node.js 22 or later

## Setup

### 1. Clone the template

> *The template code for this tutorial is available on [GitHub](https://github.com/render-examples/openai-agents-api-sandbox).*

Clone the template and install its dependencies:

```shell
git clone https://github.com/render-examples/openai-agents-api-sandbox
cd openai-agents-api-sandbox
npm ci
```

### 2. Configure credentials

1. Copy the example environment file to `.env`:

    ```shell
    cp .env.example .env
    ```

    The file includes the following required environment variables:

    ```bash
    # Render
    RENDER_API_KEY=
    RENDER_WORKSPACE_ID=

    # OpenAI
    OPENAI_API_KEY=
    OPENAI_EXECUTOR_API_KEY=
    ```

2. Populate the values for these environment variables according to the table below:

    | Environment variable | Description |
    | --- | --- |
    | `RENDER_API_KEY` | Your Render [API key][q]. Starts with `rnd_` |
    | `RENDER_WORKSPACE_ID` | Your Render workspace's ID, available at the top of its *Settings* page in the [Render Dashboard][r]. Starts with `tea-` |
    | `OPENAI_API_KEY` | Your [OpenAI API key][ak], with [permissions to manage sessions and run model inference][am]. The template uses this key locally to manage your OpenAI Agents API session. It is _not_ passed into the sandbox. |
    | `OPENAI_EXECUTOR_API_KEY` | Your [OpenAI environment key][al]. Create it on the *Agents* tab in the same organization and project, and under the same user or service account, as your application API key. The template passes this key into the sandbox as `CODEX_API_KEY`. A regular API key can't be used in its place. |

### 3. Perform your first agent run

This example handles one prompt per run and does not support follow-up messages. Provide a task Codex can complete without additional input.

Run the agent with a prompt:

```shell
npm run agent -- "Create a hello world HTTP server in /workspace/output. Test it before you finish."
```

Codex's activity streams to your terminal, resembling the following:

```
provider      openai
preflight     passed
provision     sbx-...
environment   connected
prompt        submitted
progress      reasoning
progress      command_execution
progress      command_execution
agent         I created /workspace/output/server.js and confirmed it responds with "Hello, world!".
progress      message
result        task completed
outputs       copied 1 file to runs/run_.../output
cleanup       session deleted; sandbox terminated
```

In this example:

1. Codex created a web server and tested it inside the sandbox.
2. The runner copied the server to your machine.
3. The runner deleted the session and terminated the sandbox to clean up.

### 4. Customize agent capabilities (optional)

> *These customization methods are specific to this template.*
>
> For general-purpose customization of Render Sandboxes, see [Configuring sandbox behavior][s].

| Customization | Description |
| --- | --- |
| *Toolchain* | You can install additional command-line tools for Codex to use inside the sandbox. Add installation commands to `scripts/install-executor.sh`, and add their download hosts to `INSTALL_DESTINATIONS` in `src/launch-policy.ts`. The template uploads this script to each new sandbox and executes it there before starting `codex exec-server`. |
| *Network access* | You can customize the sandbox's [network access][p] to allow outbound traffic to additional HTTPS destinations. Add the desired hostnames to `RUNTIME_DESTINATIONS` in `src/launch-policy.ts` to include them in the sandbox's allowlist. |
| *Run timeout* | You can set a time limit for the overall agent run, including sandbox setup, task execution, and output collection. Pass `--timeout <seconds>` or set `AGENT_TIMEOUT_SECONDS` (the default is `600`). The runner also derives a separate sandbox runtime timeout from this value in `src/agent.ts`. |
| *Outputs* | You can choose where generated output files are saved on your machine. Pass `--output <path>` to specify a local destination directory. The default is `runs/<run_id>/output`. To change which files the template collects from the sandbox, edit `src/outputs.ts`. |

To change Codex's [instructions](https://developers.openai.com/api/docs/guides/agents-api/configuration), edit `createSession()` in [`src/openai.ts`](https://github.com/render-examples/openai-agents-api-sandbox/blob/main/src/openai.ts). To use a different model, set `OPENAI_MODEL` in `.env`.

## How the agent runs

The template runs on your local machine. Its [`src/agent.ts`](https://github.com/render-examples/openai-agents-api-sandbox/blob/main/src/agent.ts) coordinates each run through the following stages:

------

##### Session creation

From your local machine, the template checks your Agents API access and calls the OpenAI API to create a session with a `self_hosted` environment.

OpenAI returns the environment ID and remote URL that the template will use to connect the sandbox to the session.

##### Sandbox creation

The template creates a Render sandbox and waits until it's running. It passes the environment key into the sandbox as `CODEX_API_KEY`, as defined in [`src/launch-policy.ts`](https://github.com/render-examples/openai-agents-api-sandbox/blob/main/src/launch-policy.ts).

##### Codex CLI startup

The template installs a pinned release of the Codex CLI inside the sandbox with [`scripts/install-executor.sh`](https://github.com/render-examples/openai-agents-api-sandbox/blob/main/scripts/install-executor.sh), verifying its npm integrity hash.

It opens the session's event stream on your local machine, then starts `codex exec-server` inside the sandbox to connect it to the session.

##### Task execution

After OpenAI reports that the environment is connected, the template submits your prompt from your local machine.

OpenAI runs the agent loop on its infrastructure. When Codex requests a command or file edit, the `codex exec-server` process executes it inside the sandbox and sends the result back to OpenAI.

The template streams session events and Codex's response to your terminal.

##### File collection and cleanup

When Codex finishes its turn, the template downloads regular files from `/workspace/output` in the sandbox to `runs/<run_id>/output` on your machine. It then deletes the session and terminates the sandbox.

Cleanup also runs after a failure, a timeout, `Ctrl+C`, or `SIGTERM`. Session deletion and sandbox termination are attempted independently. If cleanup fails, follow the instructions under [Troubleshooting](<https://render.com/docs/sandboxes-openai-agents-api.md#troubleshooting>).

Each run also saves the following files under `runs/<run_id>/`:

- `run.json`: Resource IDs, network policy, and cleanup status, without credentials.
- `events.jsonl`: Session events.
- `executor.log`: Sandbox setup and executor logs.
- `result.txt`: Codex's final response.

------

## Security considerations

- *Your OpenAI application API key never enters the sandbox.*

    Any code that Codex executes in the sandbox can read the sandbox's environment variables, including the environment key. Make sure that any values you set are safe to expose.

    The environment key only permits connecting environments. Keep other permissions disabled, as described in [OpenAI's authentication guidance][am].

- *Credential brokering for Render Sandboxes is [not yet generally available][ag].*

    The template currently sets the environment key as an environment variable during sandbox creation. This behavior is defined entirely in `src/launch-policy.ts`.

- *Sandbox [network access][p] is managed via allowlist.*

    The template allows access to `api.openai.com`, `codex-cloud-environments.chatgpt.com`, and `registry.npmjs.org`. The npm registry host remains allowed throughout the run, even after installation finishes.

    Tool inputs and outputs pass through OpenAI, because OpenAI hosts the agent loop.

## Troubleshooting

###### Preflight fails.

Confirm your Agents API access and that your OpenAI API key can manage sessions.

###### The environment never connects.

Check the `[executor:stderr]` lines and `runs/<run_id>/executor.log`. If they show `403 Forbidden: missing required scope api.agents.environments.connect`, replace the executor key with an environment key from the [Agents tab][al]. Make sure it belongs to the same organization, project, and user or service account as your application API key.

###### The run fails with "Your account is not active".

The environment connected, but OpenAI refused the first model request. Check your organization's [billing settings](https://platform.openai.com/settings/organization/billing/), then run the agent again.

###### The task never starts.

Open `runs/<run_id>/events.jsonl` and confirm that the `agent.session.environment.connected` event arrived before the prompt was submitted.

###### The agent produces no output files.

Inspect `runs/<run_id>/events.jsonl` and `result.txt`. Output files are optional, so prompts that need files should ask Codex to write them under `/workspace/output`.

###### Cleanup is incomplete.

If a cleanup step fails, the runner prints the commands that finish it, with the resource IDs filled in. Delete the session and terminate the sandbox independently.

The commands read your credentials from your shell, so load `.env` from the template directory before you run them:

```shell
set -a && source .env && set +a
```

The command that terminates a sandbox requires version 2.33.0 or later of the [Render CLI][ah].

If session or sandbox creation fails without a clear answer from the API, the runner also prints a `reconcile` command that lists recent resources, so you can find and delete one that might have been created.



# Sandboxes SDK for TypeScript
Source: https://render.com/docs/sandboxes-sdk-typescript


> *Render Sandboxes is in public beta.*
>
> APIs, defaults, and limits might change during the beta period.

## Setup

### 1. Install the SDK

From your TypeScript project directory:

```shell
npm install @renderinc/sdk@latest
```

(Or `pnpm install`, `bun add`, etc.)

*If you already have the SDK installed,* make sure you're using version `1.9.0` or later:

```shell
npm install @renderinc/sdk@latest
```

After installing, make sure `@renderinc/sdk` is listed as a dependency in your `package.json` file at version `^1.9.0` or later.

### 2. Import the client

The TypeScript SDK uses the asynchronous `Render` client. All sandbox methods return Promises.

```typescript
import { Render } from '@renderinc/sdk'

const sandboxes = new Render().sandboxes
const sandbox = await sandboxes.create({ wait: true })

const events = await sandboxes.exec(sandbox.id, 'echo hello')
for await (const event of events) {
  console.log(event)
}
```

The `Render` client constructor accepts an optional configuration object:

###### `Render(options?)`

Initializes a Render SDK client.

*Throws:* [`RenderError`][an] if no API key is provided.

| Option | Description |
| --- | --- |
| `token` | The API key to use for authentication. Defaults to the `RENDER_API_KEY` environment variable. You must provide an API key here or in that environment variable. |
| `ownerId` | The default workspace ID for sandbox operations. Defaults to the `RENDER_WORKSPACE_ID` environment variable. |
| `region` | The default region to use when creating sandbox groups. Currently, only `oregon` is supported. This value does not affect the placement of sandboxes created in an existing group. Defaults to the `RENDER_REGION` environment variable. |
| `baseUrl` | The base URL of the Render API. Defaults to `https://api.render.com`. |

## Sandbox lifecycle

###### `create(input)`

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 `snapshotId` or `snapshotName`, but not both. Set `sandboxGroupId` to the snapshot's group ID. Restoring into a different group is not supported. See [Restoring from a snapshot][ad].

*On success:* Returns a [`Sandbox`][ao] object. If `wait` is enabled, the returned sandbox has a status of `running`.

*Throws:* [`SandboxCreateWaitError`][ap], [`AbortError`][aq], [`SandboxSnapshotNotFoundError`][ar], [`SandboxSnapshotNotReadyError`][as], [`SandboxSnapshotPlanMismatchError`](<https://render.com/docs/sandboxes-sdk-typescript.md#sandboxsnapshotplanmismatcherror>), [`ClientError`][at], [`ServerError`][au], [`RenderError`][an]

```typescript
const sandbox = await sandboxes.create({
  plan: '2c-4g',
  idleTimeoutSeconds: 1800,
  wait: true
})
```

Supported fields on `input` include:

------

###### Field

`ownerId`

###### Description

The ID of the workspace that owns the sandbox.

Defaults to the client configuration.

If this value is not set here, it _must_ be set in the [client configuration][av]. Otherwise, this method throws `RenderError`.

---

###### Field

`sandboxGroupId`

###### Description

The ID of the sandbox group to create the sandbox in. Defaults to the workspace's default group. See [Sandbox groups][t].

---

###### Field

`plan`

###### Description

The compute plan to use for the sandbox: `1c-2g`, `2c-4g`, `4c-8g`, or `8c-16g`. See [Compute plans][z].

Defaults to `1c-2g`. When restoring from a snapshot, defaults to the source sandbox's plan. A runtime snapshot requires the same plan. When restoring from a filesystem snapshot, you can choose a different plan.

The SDK also accepts other plan strings supported by the API.

---

###### Field

`timeoutSeconds`

###### Description

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:*

- If restoring from a snapshot, the sandbox inherits the source sandbox's runtime timeout, including if disabled. The runtime timeout restarts when the sandbox is restored.
- Otherwise, the sandbox defaults to `86400` (24 hours).

Set to `0` to disable the runtime timeout and let the sandbox run indefinitely. Other values must be between `60` and `2592000` (30 days).

Automatic idle suspension is configured separately with `idleTimeoutSeconds`.

---

###### Field

`idleTimeoutSeconds`

###### Description

The number of seconds of inactivity before the sandbox is automatically suspended. See [Idle suspension][n].

*If you omit this field:*

- If restoring from a snapshot, the sandbox inherits the source sandbox's idle timeout, including if disabled.
- Otherwise, the sandbox defaults to `900` (15 minutes).

Set to `0` to disable automatic idle suspension. Other values must be between `300` (five minutes) and `86400` (24 hours).

---

###### Field

`networkPolicy`

###### Description

An object specifying the sandbox's outbound network policy. See all supported options below.

*If you omit this field:*

- If restoring from a snapshot, the sandbox inherits the source sandbox's network policy.
- Otherwise, the sandbox defaults to `{ type: 'allow-all' }`.

---

###### Field

`region`

###### Description

*Deprecated.* This field does not affect sandbox placement. The sandbox group determines the region. Currently, sandboxes run in Oregon.

---

###### Field

`env`

###### Description

An object of environment variables to inject into the sandbox at creation, with variable names as keys and string values.

See [Environment variable limits][0]. The API does not return these values in sandbox details.

---

###### Field

`snapshotId`

###### Description

The ID of an available snapshot in the same sandbox group to restore from.

If you provide this value, do not provide `snapshotName`.

---

###### Field

`snapshotName`

###### Description

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 `snapshotId`.

---

###### Field

`wait`

###### Description

Controls how the method waits for the sandbox to become ready before returning.

Provide one of the following:

- An object containing wait settings. See all supported options below.
- `true` to wait with the default settings listed below.
- `false` (default) to return without waiting.

The wait begins after the create request returns. If it fails, this method throws [`SandboxCreateWaitError`][ap], which includes the new sandbox's ID.

---

###### *Supported `networkPolicy` options*

---

###### Field

`type`

###### Description

*Required.* The outbound network policy: `allow-all`, `deny-all`, or `allow-list`.

---

###### Field

`rules`

###### Description

*Required for `allow-list`.* An array of destinations the sandbox can access over HTTPS. Do not provide this field for `allow-all` or `deny-all`.

Each entry is an object with these fields:

- `domain` (*required*): A lowercase hostname such as `api.example.com`, or a wildcard such as `*.example.com`. Do not include a scheme, port, or path. An exact hostname does not include its subdomains.
- `protocol`: Must be `https` if provided. Defaults to `https`.

Provide between 1 and 100 rules. Other outbound traffic is blocked.

---

###### *Supported `wait` options*

---

###### Field

`timeoutMs`

###### Description

The maximum time to wait, in milliseconds, including status requests.

Defaults to `60000` (60 seconds).

---

###### Field

`intervalMs`

###### Description

The initial delay between status checks, in milliseconds. The delay doubles with each attempt until reaching at least 2000 milliseconds.

Defaults to `250`. Must be greater than `0`.

---

###### Field

`signal`

###### Description

An optional `AbortSignal` used to cancel the wait.

------

###### `waitUntilRunning(sandboxId, options)`

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`][x] with `wait: true`.

*On success:* Returns a [`Sandbox`][ao] object with a status of `running`.

*Throws:* [`SandboxNotRunningError`](<https://render.com/docs/sandboxes-sdk-typescript.md#sandboxnotrunningerror>), [`SandboxWaitTimeoutError`](<https://render.com/docs/sandboxes-sdk-typescript.md#sandboxwaittimeouterror>), [`AbortError`][aq], [`ClientError`][at], [`ServerError`][au], [`RenderError`][an]

```typescript
const sandbox = await sandboxes.waitUntilRunning('sbx-abc123')
console.log(sandbox.status)
```

------

###### Parameter

`sandboxId`

###### Description

*Required.* The ID of the sandbox to wait for.

---

###### Parameter

`options`

###### Description

An optional object containing wait settings. See all supported options below.

---

###### *Supported `options`*

---

###### Parameter

`timeoutMs`

###### Description

The maximum time to wait, in milliseconds, including status requests.

Defaults to `60000` (60 seconds).

---

###### Parameter

`intervalMs`

###### Description

The initial delay between status checks, in milliseconds. The delay doubles with each attempt until reaching at least 2000 milliseconds.

Defaults to `250`. Must be greater than `0`.

---

###### Parameter

`signal`

###### Description

An optional `AbortSignal` used to cancel the wait.

---

###### Parameter

`ownerId`

###### Description

The ID of the workspace that owns the sandbox. Defaults to the [client configuration][av].

This value must be set here or in the client configuration.

------

Throws `SandboxNotRunningError` if the sandbox is `errored`, `terminated`, `suspending`, or `suspended`. If the wait times out or is canceled, the sandbox continues to exist. Use [`terminate`][aw] to stop it.

###### `get(sandboxId, ownerId, signal)`

Retrieves the details of the sandbox with the specified ID, including whether it's terminated.

To wait until a sandbox is running, use [`waitUntilRunning`][ax].

*On success:* Returns a [`Sandbox`][ao] object.

*Throws:* [`ClientError`][at], [`ServerError`][au], [`RenderError`][an]

| Parameter | Description |
| --- | --- |
| `sandboxId` | *Required.* The ID of the sandbox to retrieve. |
| `ownerId` | The ID of the workspace that owns the sandbox. Defaults to the client configuration. If this value is not set here, it _must_ be set in the [client configuration][av]. Otherwise, this method throws `RenderError`. |
| `signal` | An optional `AbortSignal` used to cancel the request. |

###### `list(options)`

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 an array of objects with `sandbox` and `cursor` fields. Each `sandbox` is a [`Sandbox`][ao] object.

*Throws:* [`ClientError`][at], [`ServerError`][au], [`RenderError`][an]

Supported fields on `options` include:

| Option | Description |
| --- | --- |
| `ownerId` | The ID of the workspace whose sandboxes to list. Defaults to the client configuration. If this value is not set here, it _must_ be set in the [client configuration][av]. Otherwise, this method throws `RenderError`. |
| `status` | An array of statuses to filter results by: `creating`, `running`, `suspending`, `suspended`, `resuming`, `errored`, or `terminated`. |
| `cursor` | The cursor from the last entry in a previous response. Use this to retrieve the next page of results. |
| `limit` | The maximum number of sandboxes to return per page. Defaults to `20`. Must be between `1` and `100`. |
| `sandboxGroupId` | The ID of a sandbox group to filter results by. Omit to list sandboxes across the workspace. |

###### `terminate(sandboxId, ownerId)`

Terminates the sandbox with the specified ID and releases its compute resources. Terminating an already-terminated sandbox succeeds.

*On success:* Returns `void`.

*Throws:* [`ClientError`][at], [`ServerError`][au], [`RenderError`][an]

| Parameter | Description |
| --- | --- |
| `sandboxId` | *Required.* The ID of the sandbox to terminate. |
| `ownerId` | The ID of the workspace that owns the sandbox. Defaults to the client configuration. If this value is not set here, it _must_ be set in the [client configuration][av]. Otherwise, this method throws `RenderError`. |

## Runtime execution

###### `exec(sandboxId, command, ownerId, signal)`

Runs the specified command in a sandbox and streams its output. Commands run through `bash -c`.

Output events identify the stream (`stdout` or `stderr`) and include a chunk of output. The final event includes the command's exit code. A nonzero exit code does not throw an error.

If the sandbox is suspended, this operation resumes it before running the command.

*On success:* Returns an async generator of [`SandboxExecEvent`](<https://render.com/docs/sandboxes-sdk-typescript.md#sandboxexecevent>) values.

*Throws:* [`SandboxEndedError`][ay], [`SandboxExecStreamError`](<https://render.com/docs/sandboxes-sdk-typescript.md#sandboxexecstreamerror>), [`AbortError`][aq], [`ClientError`][at], [`ServerError`][au], [`RenderError`][an]

| Parameter | Description |
| --- | --- |
| `sandboxId` | *Required.* The ID of the sandbox in which to run the command. |
| `command` | *Required.* The command to run through `bash -c`. |
| `ownerId` | The ID of the workspace that owns the sandbox. Defaults to the client configuration. If this value is not set here, it _must_ be set in the [client configuration][av]. Otherwise, this method throws `RenderError`. |
| `signal` | An optional `AbortSignal` used to cancel the request or stream. |

###### `upload(sandboxId, path, data, ownerId, options)`

Uploads data to the specified path in a sandbox.

To upload a directory, provide a tar archive and set `options.contentType` to `application/x-tar`. The sandbox extracts the archive at the specified path.

If the sandbox is suspended, this operation resumes it before transferring data.

*On success:* Returns `void`.

*Throws:* [`SandboxEndedError`][ay], [`AbortError`][aq], [`ClientError`][at], [`ServerError`][au], [`RenderError`][an]

------

###### Parameter

`sandboxId`

###### Description

*Required.* The ID of the destination sandbox.

---

###### Parameter

`path`

###### Description

*Required.* The destination path in the sandbox. Relative paths resolve from the sandbox's home directory. Absolute paths resolve from its filesystem root.

---

###### Parameter

`data`

###### Description

*Required.* The data to upload: a `Buffer`, `Uint8Array`, string, or Node.js `Readable` stream.

---

###### Parameter

`ownerId`

###### Description

The ID of the workspace that owns the sandbox.

Defaults to the client configuration.

If this value is not set here, it _must_ be set in the [client configuration][av]. Otherwise, this method throws `RenderError`.

---

###### Parameter

`options`

###### Description

An optional object containing upload settings. See all supported options below.

---

###### *Supported `options`*

---

###### Parameter

`contentType`

###### Description

The content type of the uploaded data: `application/octet-stream` (default) or `application/x-tar`.

---

###### Parameter

`signal`

###### Description

An optional `AbortSignal` used to cancel the upload.

------

###### `download(sandboxId, path, ownerId, options)`

Fetches a file or directory from the specified path in a sandbox and returns it as a [`SandboxDownload`][az] object. The file's raw bytes are provided in the object's `data` field. A directory download is returned as a tar archive.

This method does not write the returned file to disk. To save a file to a local path without holding it in memory, use [`copyFrom`][6].

By default, a downloaded file's size cannot exceed *256 MB*:

- When downloading a directory, this limit applies to the entire tar archive.
- If a download exceeds this limit, the method stops reading and throws `SandboxDownloadTooLargeError` without returning a partial result.
- You can customize this limit by providing the [`maxSizeBytes`](<https://render.com/docs/sandboxes-sdk-typescript.md#maxsizebytes>) option.

If the sandbox is suspended, this operation resumes it before initiating the download.

*On success:* Returns a [`SandboxDownload`][az] object containing the downloaded bytes and metadata.

*Throws:* [`SandboxDownloadTooLargeError`][a0], `RangeError` (invalid `maxSizeBytes`), [`SandboxEndedError`][ay], [`AbortError`][aq], [`ClientError`][at], [`ServerError`][au], [`RenderError`][an]

------

###### Parameter

`sandboxId`

###### Description

*Required.* The ID of the source sandbox.

---

###### Parameter

`path`

###### Description

*Required.* The path of the file or directory to download. Relative paths resolve from the sandbox's home directory. Absolute paths resolve from its filesystem root.

---

###### Parameter

`ownerId`

###### Description

The ID of the workspace that owns the sandbox.

Defaults to the client configuration.

If this value is not set here, it _must_ be set in the [client configuration][av]. Otherwise, this method throws `RenderError`.

---

###### Parameter

`options`

###### Description

An optional object containing download settings. See all supported options below.

---

###### *Supported `options`*

---

###### Parameter

`maxSizeBytes`

###### Description

The maximum download size in bytes, as a positive integer. Defaults to `268435456`.

A download that exceeds this limit throws [`SandboxDownloadTooLargeError`][a0].

---

###### Parameter

`signal`

###### Description

An optional `AbortSignal` used to cancel the download.

------

###### `copyTo(sandboxId, options)`

Copies a local file to the specified path in a sandbox. The method streams the file, so it does not hold the file in memory. This method cannot copy a directory. To upload a directory, use [`upload`][3] with a tar archive.

If the sandbox is suspended, this operation resumes it before transferring data.

*On success:* Returns `void`.

*Throws:* [`SandboxEndedError`][ay], [`AbortError`][aq], [`ClientError`][at], [`ServerError`][au], [`RenderError`][an]

```typescript
await sandboxes.copyTo('sbx-abc123', {
  localPath: './main.py',
  remotePath: 'main.py'
})
```

| Parameter | Description |
| --- | --- |
| `sandboxId` | *Required.* The ID of the destination sandbox. |
| `options.localPath` | *Required.* The path of the local file to copy. |
| `options.remotePath` | *Required.* The destination path in the sandbox. Relative paths resolve under `/home/render`. Absolute paths resolve from the filesystem root. |
| `options.ownerId` | The ID of the workspace that owns the sandbox. Defaults to the client configuration. |
| `options.signal` | An optional `AbortSignal` used to cancel the copy. |

###### `copyFrom(sandboxId, options)`

Copies a file from the specified path in a sandbox to a local path. The method streams the file, so it does not hold the file in memory. It replaces an existing local file. This method cannot copy a directory. To download a directory, use [`download`][5].

This method has no size limit by default. Provide `options.maxSizeBytes` to set one.

If the sandbox is suspended, this operation resumes it before initiating the copy.

*On success:* Returns an object with the `localPath`, the `size` in bytes, and the `contentType` if the response provides one.

*Throws:* [`SandboxDownloadError`](<https://render.com/docs/sandboxes-sdk-typescript.md#sandboxdownloaderror>), [`SandboxDownloadTooLargeError`][a0], `RangeError` (invalid `maxSizeBytes`), [`SandboxEndedError`][ay], [`AbortError`][aq], [`ClientError`][at], [`ServerError`][au], [`RenderError`][an]

```typescript
const result = await sandboxes.copyFrom('sbx-abc123', {
  remotePath: 'output.json',
  localPath: './output.json'
})
console.log(result.size)
```

| Parameter | Description |
| --- | --- |
| `sandboxId` | *Required.* The ID of the source sandbox. |
| `options.remotePath` | *Required.* The path of the file in the sandbox. Relative paths resolve under `/home/render`. Absolute paths resolve from the filesystem root. |
| `options.localPath` | *Required.* The local destination path. |
| `options.ownerId` | The ID of the workspace that owns the sandbox. Defaults to the client configuration. |
| `options.maxSizeBytes` | The largest file to copy, in bytes. If the file is larger, the method throws `SandboxDownloadTooLargeError`. |
| `options.signal` | An optional `AbortSignal` used to cancel the copy. |

## Snapshot management

Access snapshot methods through `render.sandboxes.snapshots`.

Snapshot results include the snapshot ID, optional name, source sandbox ID, sandbox group ID, kind, status, plan, capture and expiration times, size in bytes, and any capture error.

Deleting a snapshot prevents future restores but does not affect sandboxes already restored from it. After a snapshot expires, you can no longer retrieve it or restore from it, and snapshot lists omit it.

###### `snapshots.create(input)`

Creates a snapshot of the specified running sandbox. By default, this method returns before capture completes. Pass `wait: true` to wait until the snapshot is available. The source sandbox keeps running after capture.

*On success:* Returns a [`SandboxSnapshot`][a1] object. If `wait` is enabled, the returned snapshot has a status of `available`.

*Throws:* [`SandboxSnapshotCreateWaitError`][a2], [`AbortError`][aq], [`SandboxSnapshotNotReadyError`][as], [`ClientError`][at], [`ServerError`][au]

```typescript
const snapshot = await sandboxes.snapshots.create({
  sandboxId: 'sbx-abc123',
  name: 'python-ready',
  wait: true
})
```

Supported fields on `input` include:

------

###### Option

`sandboxId`

###### Description

*Required.* The ID of the running sandbox to capture.

---

###### Option

`kind`

###### Description

The snapshot type: `filesystem` to capture the writable filesystem, or `runtime` to also capture memory and CPU state.

Defaults to `runtime`.

---

###### Option

`name`

###### Description

An optional, case-sensitive name for the snapshot, with a maximum of 64 characters. Names are scoped to the sandbox group, can be reused, and cannot begin with `snp-`.

---

###### Option

`ttlSeconds`

###### Description

The snapshot's time-to-live (TTL), in seconds. When the TTL expires, the snapshot is deleted.

Each time you restore from the snapshot, its TTL refreshes. Set to `0` to retain the snapshot indefinitely until you [delete it](<https://render.com/docs/sandboxes-sdk-typescript.md#snapshots-delete>).

Defaults to 30 days.

This option replaced the `expiresAt` option in SDK version 1.9.0.

For details, see [Snapshot retention][8].

---

###### Option

`ownerId`

###### Description

The ID of the workspace that owns the source sandbox. Defaults to the client configuration. If neither is set, the API determines the workspace from the source sandbox.

---

###### Option

`wait`

###### Description

Controls how the method waits for the snapshot to be available before returning.

Provide one of the following:

- An object containing wait settings. See all supported options below.
- `true` to wait with the default settings listed below.
- `false` (default) to return without waiting.

If the wait fails, this method throws [`SandboxSnapshotCreateWaitError`][a2], which includes the new snapshot's ID and sandbox group ID.

---

###### *Supported `wait` options*

---

###### Option

`timeoutMs`

###### Description

The maximum time to wait, in milliseconds, including status requests.

Defaults to `300000` (five minutes).

---

###### Option

`intervalMs`

###### Description

The initial delay between status checks, in milliseconds. The delay doubles with each attempt until reaching at least 2000 milliseconds.

Defaults to `250`. Must be greater than `0`.

---

###### Option

`signal`

###### Description

An optional `AbortSignal` used to cancel the wait.

------

###### `snapshots.waitUntilAvailable(input, options)`

Waits for the specified snapshot to be available and returns its details.

To create a snapshot and wait for it in a single call, use [`snapshots.create`][9] with `wait: true`.

*On success:* Returns a [`SandboxSnapshot`][a1] object with a status of `available`.

*Throws:* [`SandboxSnapshotFailedError`](<https://render.com/docs/sandboxes-sdk-typescript.md#sandboxsnapshotfailederror>), [`SandboxSnapshotWaitTimeoutError`](<https://render.com/docs/sandboxes-sdk-typescript.md#sandboxsnapshotwaittimeouterror>), [`SandboxSnapshotNotFoundError`][ar], [`AbortError`][aq], [`ClientError`][at], [`ServerError`][au]

```typescript
const snapshot = await sandboxes.snapshots.waitUntilAvailable({
  sandboxGroupId: 'sbg-abc123',
  snapshotId: 'snp-abc123'
})

console.log(snapshot.status)
```

------

###### Parameter

`input`

###### Description

*Required.* An object with the following supported fields:

- `sandboxGroupId` (*required*): The ID of the sandbox group that contains the snapshot.
- `snapshotId` (*required*): The ID of the snapshot to wait for.
- `ownerId`: 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.

---

###### Parameter

`options`

###### Description

An optional object containing wait settings. See all supported options below.

---

###### *Supported `options`*

---

###### Parameter

`timeoutMs`

###### Description

The maximum time to wait, in milliseconds, including status requests.

Defaults to `300000` (five minutes).

---

###### Parameter

`intervalMs`

###### Description

The initial delay between status checks, in milliseconds. The delay doubles with each attempt until reaching at least 2000 milliseconds.

Defaults to `250`. Must be greater than `0`.

---

###### Parameter

`signal`

###### Description

An optional `AbortSignal` used to cancel the wait.

------

Throws `SandboxSnapshotFailedError` if the snapshot's status becomes `failed`. If the wait times out or is canceled, snapshot capture continues.

###### `snapshots.get(input, signal)`

Retrieves the details of the snapshot with the specified ID in the specified sandbox group.

To wait until a snapshot is available, use [`snapshots.waitUntilAvailable`][a3].

*On success:* Returns a [`SandboxSnapshot`][a1] object.

*Throws:* [`SandboxSnapshotNotFoundError`][ar], [`ClientError`][at], [`ServerError`][au]

------

###### Parameter

`input`

###### Description

*Required.* An object identifying the snapshot. See all supported fields below.

---

###### Parameter

`signal`

###### Description

An optional `AbortSignal` used to cancel the request.

---

###### *Supported `input` fields*

---

###### Parameter

`sandboxGroupId`

###### Description

*Required.* The ID of the sandbox group that contains the snapshot.

---

###### Parameter

`snapshotId`

###### Description

*Required.* The ID of the snapshot to retrieve.

---

###### Parameter

`ownerId`

###### Description

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(input)`

Lists snapshots in the specified sandbox group, newest first. Deleted and expired snapshots are excluded.

*On success:* Returns an array of [`SandboxSnapshotWithCursor`](<https://render.com/docs/sandboxes-sdk-typescript.md#sandboxsnapshotwithcursor>) entries.

*Throws:* [`ClientError`][at], [`ServerError`][au], [`RenderError`][an]

Supported fields on `input` include:

| Option | Description |
| --- | --- |
| `sandboxGroupId` | *Required.* The ID of the sandbox group whose snapshots to list. |
| `status` | An array of statuses to filter results by: `creating`, `available`, or `failed`. |
| `cursor` | The cursor from the last entry in a previous response. Use this to retrieve the next page of results. |
| `limit` | The maximum number of snapshots to return per page. Defaults to `20`. Must be between `1` and `100`. |
| `ownerId` | The ID of the workspace that owns the sandbox group. Defaults to the client configuration. If this value is not set here, it _must_ be set in the [client configuration][av]. Otherwise, this method throws `RenderError`. |

###### `snapshots.delete(input)`

Deletes the snapshot with the specified ID in the specified sandbox group. You cannot delete a snapshot while its status is `creating`. Sandboxes already restored from the snapshot are unaffected.

*On success:* Returns `void`.

*Throws:* [`SandboxSnapshotNotFoundError`][ar], [`SandboxSnapshotNotReadyError`][as], [`ClientError`][at], [`ServerError`][au]

Supported fields on `input` include:

| Option | Description |
| --- | --- |
| `sandboxGroupId` | *Required.* The ID of the sandbox group that contains the snapshot. |
| `snapshotId` | *Required.* The ID of the snapshot to delete. |
| `ownerId` | 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

###### `listGroups(options)`

Lists sandbox groups in the specified workspace. Use a group's ID when creating sandboxes or managing snapshots.

To paginate, use the cursor from the last entry to retrieve the next page. Continue until a page contains no groups.

*On success:* Returns an array of [`SandboxGroupWithCursor`][a4] entries.

*Throws:* [`ClientError`][at], [`ServerError`][au], [`RenderError`][an]

Supported fields on `options` include:

| Option | Description |
| --- | --- |
| `ownerId` | The ID of the workspace whose sandbox groups to list. Defaults to the client configuration. If this value is not set here, it _must_ be set in the [client configuration][av]. Otherwise, this method throws `RenderError`. |
| `cursor` | The cursor from the last entry in a previous response. Use this to retrieve the next page of results. |
| `limit` | The maximum number of groups to return per page. Defaults to `20`. Must be between `1` and `100`. |

###### `createGroup(input)`

Creates a sandbox group in the specified workspace.

*On success:* Returns a [`SandboxGroup`][a5] object.

*Throws:* [`ClientError`][at], [`ServerError`][au], [`RenderError`][an]

```typescript
const group = await sandboxes.createGroup({
  name: 'agents',
  region: 'oregon'
})
console.log(group.id)
```

Supported fields on `input` include:

| Field | Description |
| --- | --- |
| `name` | *Required.* The name of the sandbox group. |
| `ownerId` | The ID of the workspace that owns the sandbox group. Defaults to the [client configuration][av]. This value must be set here or in the client configuration. |
| `region` | The region for the sandbox group. Currently, only `oregon` is supported. Defaults to the client configuration, then `oregon`. |

###### `getGroup(sandboxGroupId)`

Retrieves the details of the sandbox group with the specified ID.

*On success:* Returns a [`SandboxGroup`][a5] object.

*Throws:* [`ClientError`][at], [`ServerError`][au], [`RenderError`][an]

```typescript
const group = await sandboxes.getGroup('sbg-abc123')
console.log(group.concurrencyLimit)
```

| Parameter | Description |
| --- | --- |
| `sandboxGroupId` | *Required.* The ID of the sandbox group to retrieve. |

###### `updateGroup(sandboxGroupId, concurrencyLimit)`

Updates the sandbox group's concurrency limit. The returned group includes the effective limit after Render applies its cap. Lowering the limit does not stop existing sandboxes.

*On success:* Returns a [`SandboxGroup`][a5] object.

*Throws:* [`ClientError`][at], [`ServerError`][au], [`RenderError`][an]

```typescript
const group = await sandboxes.updateGroup('sbg-abc123', 10)
console.log(group.concurrencyLimit)
```

| Parameter | Description |
| --- | --- |
| `sandboxGroupId` | *Required.* The ID of the sandbox group to update. |
| `concurrencyLimit` | *Required.* The maximum number of active sandboxes in the group. Must be at least `1`. Setting a higher value does not raise Render's cap. See [Concurrency][v]. |

## Error types

### Sandbox errors

These errors pertain to sandbox operations that cannot resolve required client configuration or encounter an unexpected response.

###### `RenderError`

Raised when an operation cannot resolve a required owner ID or encounters an unexpected sandbox response.

###### `SandboxEndedError extends ClientError`

Thrown when command execution or file transfer encounters a sandbox that is `terminated` or `errored`. Includes the status in `sandboxStatus`.

###### `SandboxDownloadTooLargeError extends RenderError`

Thrown when [`download`][5] or [`copyFrom`][6] exceeds its configured size limit. Includes `sandboxId`, `path`, and `maxSizeBytes`.

###### `SandboxDownloadError extends RenderError`

Thrown when [`copyFrom`][6] cannot write the file to the local path. Includes `sandboxId`, `path`, `localPath`, and the file-system error in `cause`. An existing file at the local path is left as it was.

### Command execution errors

These errors pertain to running commands in a sandbox.

###### `SandboxExecStreamError`

Raised when the exec stream ends with a terminal error. Carries `status` and `message` properties.

### Readiness errors

These errors pertain to waiting for a sandbox or snapshot to be ready.

###### `SandboxNotRunningError extends RenderError`

Thrown when [`waitUntilRunning`][ax] encounters a sandbox with status `errored`, `terminated`, `suspending`, or `suspended`. Includes `sandboxId` and `sandboxStatus`.

###### `SandboxSnapshotFailedError extends RenderError`

Thrown when [`snapshots.waitUntilAvailable`][a3] encounters a failed snapshot. Includes `snapshotId` and the capture error in `snapshotError`, if available.

###### `TimeoutError extends RenderError`

The parent class for SDK timeout errors.

###### `SandboxWaitTimeoutError extends TimeoutError`

Thrown when a sandbox does not reach `running` within the specified wait timeout. Includes `sandboxId`, `timeoutMs`, and `lastStatus` if a status check completed.

###### `SandboxSnapshotWaitTimeoutError extends TimeoutError`

Thrown when a snapshot does not reach `available` within the specified wait timeout. Includes `snapshotId`, `timeoutMs`, and `lastStatus` if a status check completed.

###### `SandboxCreateWaitError extends RenderError`

Thrown when [`create`][x] creates a sandbox but its wait fails. Includes `sandboxId` and the underlying error in `cause`.

The sandbox still exists. Use [`terminate`][aw] if you want to stop it.

###### `SandboxSnapshotCreateWaitError extends RenderError`

Thrown when [`snapshots.create`][9] creates a snapshot but its wait fails. Includes `snapshotId`, `sandboxGroupId`, and the underlying error in `cause`.

The snapshot still exists. You can delete it once capture finishes.

### Cancellation errors

These errors pertain to an `AbortSignal` that cancels an operation.

###### `AbortError`

Raised when an operation is aborted.

### Snapshot errors

These errors pertain to creating snapshots, restoring from snapshots, and managing snapshots.

###### `SandboxSnapshotNotFoundError`

Raised when the snapshot cannot be found in the specified group, including after deletion or expiration.

###### `SandboxSnapshotNotReadyError`

Raised when restore requires an `available` snapshot, or deletion was attempted while capture was still `creating`.

###### `SandboxSnapshotPlanMismatchError`

Raised when restoring a sandbox from a runtime snapshot onto a different plan.

### API errors

These errors pertain to responses from the Render API.

###### `ClientError`

Raised when the API returns a 4xx response, including HTTP 429 for either the request rate or concurrency cap (see [Sandbox limits][b]).

###### `ServerError`

Raised when the API returns a 5xx response.

## Additional types

###### `Sandbox`

Represents a sandbox returned by `create()`, `get()`, or `waitUntilRunning()`, or included in a list result.

------

##### `id`

The sandbox's ID.

##### `status`

The sandbox's current status:

| Status | Description |
| --- | --- |
| *`creating`* | *Creation is in progress.* The sandbox is not yet ready to execute commands or transfer files. |
| *`running`* | *The sandbox is ready.* You can execute commands and transfer files. |
| *`suspending`* | *Suspension is in progress.* Render is saving the sandbox's state. |
| *`suspended`* | *The sandbox is suspended.* Executing a command or transferring files resumes it automatically. |
| *`resuming`* | *Resumption is in progress.* Render is restoring the sandbox's saved state. |
| *`errored`* | *The sandbox encountered an error.* It can no longer execute commands or transfer files. |
| *`terminated`* | *The sandbox has been terminated.* It can no longer execute commands or transfer files. |

##### `plan`

The sandbox's compute plan.

##### `networkPolicy`

The sandbox's outbound network policy.

##### `region`

The Render region in which the sandbox runs.

##### `timeoutSeconds`

The sandbox's runtime timeout, in seconds. `0` indicates that the timeout is disabled. This timeout restarts if the sandbox is suspended and later resumed.

##### `idleTimeoutSeconds`

The number of seconds of inactivity before automatic suspension. `0` disables automatic idle suspension. See [Idle suspension][n].

##### `sandboxGroupId`

The ID of the sandbox group that contains the sandbox.

##### `createdAt`

The time when the sandbox was created, as an ISO 8601 string.

##### `terminatedAt`

The time when the sandbox was terminated, as an ISO 8601 string, or `null` if it has not been terminated.

------

###### `SandboxDownload`

Represents the data returned by [`download`][5].

| Property | Description |
| --- | --- |
| `data` | The downloaded bytes as a `Buffer`. For a directory, this contains a tar archive. |
| `size` | The number of downloaded bytes. |
| `contentType` | The response content type, if provided. |

###### `SandboxExecEvent`

Represents an event yielded by `exec()`.

An output event has `type: 'output'`, `stream: 'stdout' | 'stderr'`, and a `data` string. The final exit event has `type: 'exit'` and an `exit_code` number.

###### `SandboxGroup`

Represents a sandbox group returned by a group method or included in a [`SandboxGroupWithCursor`][a4] entry.

| Property | Description |
| --- | --- |
| `id` | The sandbox group's ID. |
| `ownerId` | The ID of the workspace that owns the sandbox group. |
| `name` | The sandbox group's name. |
| `region` | The Render region that the sandbox group belongs to. |
| `isDefault` | Whether this is the workspace's default sandbox group. |
| `concurrencyLimit` | The effective limit on active sandboxes in this group. Suspended sandboxes do not count toward the limit. See [Concurrency][v]. |
| `createdAt` | The time when the sandbox group was created, as an ISO 8601 string. |
| `updatedAt` | The time when the sandbox group was last updated, as an ISO 8601 string. |
| `environmentId` | The ID of the associated environment, or `null` if the group has none. |

###### `SandboxGroupWithCursor`

Represents one sandbox group in a `listGroups()` result.

| Property | Description |
| --- | --- |
| `sandboxGroup` | The [`SandboxGroup`][a5] in this entry. |
| `cursor` | The cursor for this entry. |

###### `SandboxSnapshot`

Represents a snapshot returned by a `snapshots` method or included in a list result.

------

##### `id`

The snapshot's ID.

##### `sandboxGroupId`

The ID of the sandbox group that contains the snapshot.

##### `sourceSandboxId`

The ID of the sandbox from which the snapshot was captured.

##### `name`

The optional name assigned when the snapshot was created, or `null`.

##### `kind`

The snapshot type: `filesystem` or `runtime`.

##### `status`

The snapshot's current status:

| Status | Description |
| --- | --- |
| *`creating`* | *Capture is in progress.* New sandboxes cannot yet be restored from the snapshot. |
| *`available`* | *Capture succeeded.* New sandboxes can now be restored from the snapshot. |
| *`failed`* | *Capture failed.* Check the snapshot's `error` field for details. |

##### `plan`

The compute plan of the source sandbox.

##### `requestedAt`

The time when snapshot capture was requested, as an ISO 8601 string.

##### `capturedAt`

The time when capture completed, as an ISO 8601 string, or `null` while the snapshot is still being created.

##### `expiresAt`

The snapshot's current expiration time, as an ISO 8601 string. Restoring from the snapshot refreshes its TTL and updates this time accordingly.

For a snapshot with TTL disabled, this value is `9999-12-31T23:59:59Z`.

##### `ttlSeconds`

The snapshot's total time-to-live (TTL), in seconds.

This value does not dynamically decrement to reflect the current amount of time until expiration. Use the [`expiresAt`](<https://render.com/docs/sandboxes-sdk-typescript.md#expiresat>) property instead.

For a snapshot with TTL disabled, this value is `0`.

##### `sizeBytes`

The snapshot's size in bytes, or `null` until capture completes.

##### `error`

The capture error message, if capture failed; otherwise `null`.

------

###### `SandboxSnapshotWithCursor`

Represents one snapshot in a `snapshots.list()` result.

| Property | Description |
| --- | --- |
| `snapshot` | The [`SandboxSnapshot`][a1] in this entry. |
| `cursor` | The cursor for this entry. |



# Sandboxes SDK for Python
Source: https://render.com/docs/sandboxes-sdk-python


> *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:

```shell
pip install render
```

*If you already have the SDK installed,* make sure you're using version `1.9.0` or later:

```shell
pip install --upgrade render
```

After installing, make sure to add `render>=1.9.0` as a dependency in your application's `requirements.txt`, `pyproject.toml`, or equivalent.

Version 1.9.0 and later require Python 3.11 or later.

### 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.

**Tab: Sync client**

```python
from render import Render # highlight-line

sandboxes = Render().sandboxes # highlight-line
sandbox = sandboxes.create(wait=True)

for event in sandboxes.exec(sandbox.id, "echo hello"):
    print(event)
```

**Tab: Async client**

```python
import asyncio
from render import RenderAsync # highlight-line

async def main():
    sandboxes = RenderAsync().sandboxes # highlight-line
    sandbox = await sandboxes.create(wait=True)

    async for event in sandboxes.exec(sandbox.id, "echo hello"):
        print(event)

asyncio.run(main())
```

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 |
| --- | --- |
| `token` | The API key to use for authentication. Defaults to the `RENDER_API_KEY` environment variable. |
| `owner_id` | The default workspace ID for sandbox operations. Defaults to the `RENDER_WORKSPACE_ID` environment variable. |
| `region` | A compatibility parameter that does not affect sandbox placement. The sandbox group determines the region. Currently, sandboxes run in Oregon. |
| `base_url` | The base URL of the Render API. Defaults to `https://api.render.com`. |

###### `RenderAsync(*, token=None, base_url="https://api.render.com", owner_id=None, region=None)`

Initializes an asynchronous Render SDK client.

| Parameter | Description |
| --- | --- |
| `token` | The API key to use for authentication. Defaults to the `RENDER_API_KEY` environment variable. |
| `owner_id` | The default workspace ID for sandbox operations. Defaults to the `RENDER_WORKSPACE_ID` environment variable. |
| `region` | A compatibility parameter that does not affect sandbox placement. The sandbox group determines the region. Currently, sandboxes run in Oregon. |
| `base_url` | The base URL of the Render API. Defaults to `https://api.render.com`. |

## 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][ad].

*On success:* Returns a [`Sandbox`][a6] object. If `wait` is enabled, the returned sandbox has a status of `running`.

*Raises:* [`SandboxCreateWaitError`][a7], [`SnapshotNotFoundError`][a8], [`SnapshotNotReadyError`][a9], [`SnapshotPlanMismatchError`](<https://render.com/docs/sandboxes-sdk-python.md#snapshotplanmismatcherror>), [`RateLimitError`][ba], [`ClientError`][bb], [`ServerError`][bc], [`RenderError`][bd]

```python
sandbox = sandboxes.create(
    plan="2c-4g",
    timeout_seconds=300,
    wait=True,
)
print(sandbox.id, sandbox.status)
```

------

###### Parameter

`owner_id`

###### Description

The ID of the workspace that owns the sandbox. Defaults to the [client configuration][be].

This value must be set here or in the client configuration.

---

###### Parameter

`sandbox_group_id`

###### Description

The ID of the sandbox group to create the sandbox in. Defaults to the workspace's default group. See [Sandbox groups][t].

---

###### Parameter

`plan`

###### Description

The compute plan to use for the sandbox: `1c-2g`, `2c-4g`, `4c-8g`, or `8c-16g`. See [Compute plans][z].

Defaults to `1c-2g`. When restoring from a snapshot, defaults to the source sandbox's plan. A runtime snapshot requires the same plan. When restoring from a filesystem snapshot, you can choose a different plan.

---

###### Parameter

`timeout_seconds`

###### Description

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:*

- If restoring from a snapshot, the sandbox inherits the source sandbox's runtime timeout, including if disabled. The runtime timeout restarts when the sandbox is restored.
- Otherwise, the sandbox defaults to `86400` (24 hours).

Set to `0` to disable the runtime timeout and let the sandbox run indefinitely. Other values must be between `60` and `2592000` (30 days). See [Runtime timeout limits][0].

Automatic idle suspension is configured separately with `idle_timeout_seconds`.

---

###### Parameter

`idle_timeout_seconds`

###### Description

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:*

- If restoring from a snapshot, the sandbox inherits the source sandbox's idle timeout, including if disabled.
- Otherwise, the sandbox defaults to `900` (15 minutes).

Set to `0` to disable automatic idle suspension. Other values must be between `300` (5 minutes) and `86400` (24 hours). See [Idle suspension][n].

---

###### Parameter

`network_policy`

###### Description

The sandbox's outbound network policy. Provide a `NetworkPolicy` object or a policy type string (`"allow-all"`, `"deny-all"`, or `"allow-list"`).

*If you omit this field:*

- If restoring from a snapshot, the sandbox inherits the source sandbox's network policy.
- Otherwise, the sandbox defaults to `"allow-all"`.

To specify allowed destinations, provide a `NetworkPolicy` with `rules`. See all supported fields below.

---

###### Parameter

`region`

###### Description

A compatibility parameter that does not affect sandbox placement. The sandbox group determines the region. Currently, sandboxes run in Oregon.

---

###### Parameter

`env`

###### Description

A dictionary of environment variables to inject into the sandbox at creation, with variable names as keys and string values.

See [Environment variable limits][0]. The API does not return these values in sandbox details.

---

###### Parameter

`snapshot_id`

###### Description

The ID of an available snapshot in the same sandbox group to restore from.

If you provide this value, do not provide `snapshot_name`.

---

###### Parameter

`snapshot_name`

###### Description

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 `snapshot_id`.

---

###### Parameter

`wait`

###### Description

Controls how the method waits for the sandbox to become ready before returning.

Provide one of the following:

- A `SandboxWaitOptions` object containing wait settings. See all supported options below.
- `True` to wait with the default settings listed below.
- `False` (default) to return without waiting.

The wait begins after the create request returns. If it fails, this method raises [`SandboxCreateWaitError`][a7], which includes the new sandbox's ID.

---

###### *Supported `network_policy` fields*

---

###### Parameter

`type`

###### Description

*Required.* The policy type: `"allow-all"`, `"deny-all"`, or `"allow-list"`.

---

###### Parameter

`rules`

###### Description

*Required for `allow-list`.* A list of `EgressRule` objects specifying destinations the sandbox can access over HTTPS. Omit for `allow-all` or `deny-all`.

Each `EgressRule` accepts these parameters:

- `domain` (*required*): A lowercase hostname such as `api.example.com`, or a wildcard such as `*.example.com`. Do not include a scheme, port, or path. An exact hostname does not include its subdomains.
- `protocol`: Must be `"https"` if provided. Defaults to `"https"`.

Provide between 1 and 100 rules. Other outbound traffic is blocked.

---

###### *Supported `wait` options*

---

###### Parameter

`timeout_seconds`

###### Description

The maximum time to wait, in seconds. Defaults to `60`.

---

###### Parameter

`interval_seconds`

###### Description

The initial delay between status checks, in seconds. The delay doubles with each attempt until reaching at least 2 seconds.

Defaults to `0.25`. Must be greater than `0`.

------

To specify wait settings, import `SandboxWaitOptions` from `render.sandbox`:

```python
from render.sandbox import SandboxWaitOptions

sandbox = sandboxes.create(
    wait=SandboxWaitOptions(timeout_seconds=120, interval_seconds=0.5),
)
```

A failed wait does not terminate the sandbox. Use the `sandbox_id` on `SandboxCreateWaitError` to [terminate][bf] 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`][y] with `wait=True`.

*On success:* Returns a [`Sandbox`][a6] object with a status of `running`.

*Raises:* [`SandboxNotRunningError`](<https://render.com/docs/sandboxes-sdk-python.md#sandboxnotrunningerror>), [`SandboxWaitTimeoutError`](<https://render.com/docs/sandboxes-sdk-python.md#sandboxwaittimeouterror>), [`SandboxNotFoundError`][bg], [`RateLimitError`][ba], [`ClientError`][bb], [`ServerError`][bc], [`RenderError`][bd]

```python
sandbox = sandboxes.wait_until_running("sbx-abc123")
print(sandbox.status)
```

| Parameter | Description |
| --- | --- |
| `sandbox_id` | *Required.* The ID of the sandbox. |
| `timeout_seconds` | The maximum time to wait, in seconds. Defaults to `60`. |
| `interval_seconds` | The initial delay between status checks, in seconds. The delay doubles with each attempt until reaching at least 2 seconds. Defaults to `0.25`. Must be greater than `0`. |
| `owner_id` | The ID of the workspace that owns the sandbox. Defaults to the [client configuration][be]. 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`][a6] object.

*Raises:* [`SandboxNotFoundError`][bg], [`RateLimitError`][ba], [`ClientError`][bb], [`ServerError`][bc], [`RenderError`][bd]

```python
sandbox = sandboxes.from_id("sbx-abc123")
print(sandbox.status)
```

| Parameter | Description |
| --- | --- |
| `sandbox_id` | *Required.* The ID of the sandbox. |
| `owner_id` | The ID of the workspace that owns the sandbox. Defaults to the [client configuration][be]. 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`][bh] page.

*Raises:* [`RateLimitError`][ba], [`ClientError`][bb], [`ServerError`][bc], [`RenderError`][bd]

```python
page = sandboxes.list(status="running", limit=20)
for sandbox in page.sandboxes:
    print(sandbox.id)
```

| Parameter | Description |
| --- | --- |
| `owner_id` | The ID of the workspace that owns the sandbox. Defaults to the [client configuration][be]. This value must be set here or in the client configuration. |
| `status` | One status string or a sequence of status strings to filter results by. |
| `cursor` | A cursor from a previous response. Use this to retrieve the next page of results. |
| `limit` | The maximum number of sandboxes to return. The API caps this value at `100`. |
| `sandbox_group_id` | 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 the sandbox's local filesystem. Terminating an already-terminated sandbox succeeds.

*On success:* Returns `None`.

*Raises:* [`SandboxNotFoundError`][bg], [`RateLimitError`][ba], [`ClientError`][bb], [`ServerError`][bc], [`RenderError`][bd]

```python
sandboxes.terminate("sbx-abc123")
```

| Parameter | Description |
| --- | --- |
| `sandbox_id` | *Required.* The ID of the sandbox. |
| `owner_id` | The ID of the workspace that owns the sandbox. Defaults to the [client configuration][be]. 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`](<https://render.com/docs/sandboxes-sdk-python.md#sandboxexecevent>) values: a regular iterator with `Render`, or an async iterator with `RenderAsync`.

*Raises:* [`SandboxNotFoundError`][bg], [`SandboxEndedError`][bi], [`SandboxExecStreamError`](<https://render.com/docs/sandboxes-sdk-python.md#sandboxexecstreamerror>), [`SandboxExecError`](<https://render.com/docs/sandboxes-sdk-python.md#sandboxexecerror>), [`RateLimitError`][ba], [`ClientError`][bb], [`ServerError`][bc], [`RenderError`][bd]

```python
from render.sandbox import SandboxExecExit, SandboxExecOutput

for event in sandboxes.exec("sbx-abc123", "echo hello"):
    if isinstance(event, SandboxExecOutput):
        print(event.data, end="")
    elif isinstance(event, SandboxExecExit):
        print(f"Exit code: {event.exit_code}")
```

| Parameter | Description |
| --- | --- |
| `sandbox_id` | *Required.* The ID of the sandbox. |
| `command` | *Required.* The shell command to execute. |
| `owner_id` | The ID of the workspace that owns the sandbox. Defaults to the [client configuration][be]. 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`][bg], [`SandboxEndedError`][bi], [`SandboxFileNotFoundError`][bj], [`RateLimitError`][ba], [`ClientError`][bb], [`ServerError`][bc], [`RenderError`][bd]

```python
sandboxes.copy_to("sbx-abc123", "./inputs", "/home/render/inputs")
```

| Parameter | Description |
| --- | --- |
| `sandbox_id` | *Required.* The ID of the sandbox. |
| `local_path` | *Required.* The local file or directory to upload, as a string or `os.PathLike` object. |
| `remote_path` | *Required.* The destination path in the sandbox. Relative paths resolve under `/home/render`. Absolute paths resolve from the filesystem root. |
| `owner_id` | The ID of the workspace that owns the sandbox. Defaults to the [client configuration][be]. 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`][bg], [`SandboxEndedError`][bi], [`SandboxFileNotFoundError`][bj], [`SandboxDownloadError`](<https://render.com/docs/sandboxes-sdk-python.md#sandboxdownloaderror>), [`RateLimitError`][ba], [`ClientError`][bb], [`ServerError`][bc], [`RenderError`][bd]

```python
path = sandboxes.copy_from("sbx-abc123", "/home/render/output", "./output")
print(path)
```

| Parameter | Description |
| --- | --- |
| `sandbox_id` | *Required.* The ID of the sandbox. |
| `remote_path` | *Required.* The file or directory path in the sandbox to download. Relative paths resolve under `/home/render`. Absolute paths resolve from the filesystem root. |
| `local_path` | *Required.* The local destination path, as a string or `os.PathLike` object. |
| `owner_id` | The ID of the workspace that owns the sandbox. Defaults to the [client configuration][be]. 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, ttl_seconds=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`][bk] object. If `wait` is enabled, the returned snapshot has a status of `available`.

*Raises:* [`SnapshotCreateWaitError`][bl], [`SandboxNotFoundError`][bg], [`RateLimitError`][ba], [`ClientError`][bb], [`ServerError`][bc], [`RenderError`][bd]

```python
snapshot = sandboxes.snapshots.create(
    "sbx-abc123",
    kind="filesystem",
    name="prepared-environment",
    wait=True,
)
print(snapshot.id)
```

------

###### Parameter

`sandbox_id`

###### Description

*Required.* The ID of the sandbox.

---

###### Parameter

`kind`

###### Description

The snapshot type: `"filesystem"` to capture the writable filesystem, or `"runtime"` to also capture memory and CPU state.

Defaults to `"runtime"`.

---

###### Parameter

`name`

###### Description

An optional, case-sensitive name for the snapshot, with a maximum of 64 characters. Names are scoped to the sandbox group, can be reused, and cannot begin with `snp-`.

---

###### Parameter

`ttl_seconds`

###### Description

The snapshot's time-to-live (TTL), in seconds. When the TTL expires, the snapshot is deleted.

Each time you restore from the snapshot, its TTL refreshes. Set to `0` to retain the snapshot indefinitely until you [delete it](<https://render.com/docs/sandboxes-sdk-python.md#snapshots-delete>).

Defaults to 30 days.

This option replaced the `expires_at` parameter in SDK version 1.9.0.

For details, see [Snapshot retention][8].

---

###### Parameter

`owner_id`

###### Description

The ID of the workspace that owns the source sandbox. Defaults to the client configuration. If neither is set, the API determines the workspace from the source sandbox.

---

###### Parameter

`wait`

###### Description

Controls how the method waits for the snapshot to be available before returning.

Provide one of the following:

- A `SandboxWaitOptions` object containing wait settings. See all supported options below.
- `True` to wait with the default settings listed below.
- `False` (default) to return without waiting.

The wait begins after the create request returns. If it fails, this method raises [`SnapshotCreateWaitError`][bl], which includes the new snapshot's IDs.

---

###### *Supported `wait` options*

---

###### Parameter

`timeout_seconds`

###### Description

The maximum time to wait, in seconds. Defaults to `300`.

---

###### Parameter

`interval_seconds`

###### Description

The initial delay between status checks, in seconds. The delay doubles with each attempt until reaching at least 2 seconds.

Defaults to `0.25`. Must be greater than `0`.

------

To specify wait settings, import `SandboxWaitOptions` from `render.sandbox`:

```python
from render.sandbox import SandboxWaitOptions

snapshot = sandboxes.snapshots.create(
    "sbx-abc123",
    wait=SandboxWaitOptions(timeout_seconds=600),
)
```

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`][aa] with `wait=True`.

*On success:* Returns a [`Snapshot`][bk] object with a status of `available`.

*Raises:* [`SnapshotFailedError`](<https://render.com/docs/sandboxes-sdk-python.md#snapshotfailederror>), [`SnapshotWaitTimeoutError`](<https://render.com/docs/sandboxes-sdk-python.md#snapshotwaittimeouterror>), [`SnapshotNotFoundError`][a8], [`RateLimitError`][ba], [`ClientError`][bb], [`ServerError`][bc], [`RenderError`][bd]

```python
snapshot = sandboxes.snapshots.wait_until_available(
    sandbox_group_id="sbg-abc123",
    snapshot_id="snp-abc123",
)
print(snapshot.status)
```

| Parameter | Description |
| --- | --- |
| `sandbox_group_id` | *Required.* The ID of the sandbox group. |
| `snapshot_id` | *Required.* The ID of the snapshot. |
| `timeout_seconds` | The maximum time to wait, in seconds. Defaults to `300`. |
| `interval_seconds` | The initial delay between status checks, in seconds. The delay doubles with each attempt until reaching at least 2 seconds. Defaults to `0.25`. Must be greater than `0`. |
| `owner_id` | 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`][bk] object.

*Raises:* [`SnapshotNotFoundError`][a8], [`RateLimitError`][ba], [`ClientError`][bb], [`ServerError`][bc], [`RenderError`][bd]

```python
snapshot = sandboxes.snapshots.from_id(
    sandbox_group_id="sbg-abc123",
    snapshot_id="snp-abc123",
)
print(snapshot.status)
```

| Parameter | Description |
| --- | --- |
| `sandbox_group_id` | *Required.* The ID of the sandbox group. |
| `snapshot_id` | *Required.* The ID of the snapshot. |
| `owner_id` | 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`](<https://render.com/docs/sandboxes-sdk-python.md#snapshotlist>) page.

*Raises:* [`RateLimitError`][ba], [`ClientError`][bb], [`ServerError`][bc], [`RenderError`][bd]

```python
page = sandboxes.snapshots.list(sandbox_group_id="sbg-abc123")
for snapshot in page.snapshots:
    print(snapshot.id, snapshot.status)
```

| Parameter | Description |
| --- | --- |
| `sandbox_group_id` | *Required.* The ID of the sandbox group. |
| `status` | One status string or a sequence of status strings to filter results by: `"creating"`, `"available"`, or `"failed"`. |
| `cursor` | A cursor from a previous response. Use this to retrieve the next page of results. |
| `limit` | The maximum number of snapshots to return. The API caps this value at `100`. |
| `owner_id` | 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. Otherwise, this method raises `RenderError`. |

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`][a8], [`SnapshotNotReadyError`][a9], [`RateLimitError`][ba], [`ClientError`][bb], [`ServerError`][bc], [`RenderError`][bd]

```python
sandboxes.snapshots.delete(
    sandbox_group_id="sbg-abc123",
    snapshot_id="snp-abc123",
)
```

| Parameter | Description |
| --- | --- |
| `sandbox_group_id` | *Required.* The ID of the sandbox group. |
| `snapshot_id` | *Required.* The ID of the snapshot. |
| `owner_id` | 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`][bm] page.

*Raises:* [`RateLimitError`][ba], [`ClientError`][bb], [`ServerError`][bc], [`RenderError`][bd]

```python
page = sandboxes.list_groups()
for group in page.groups:
    print(group.id, group.name)
```

| Parameter | Description |
| --- | --- |
| `owner_id` | The ID of the workspace that owns the sandbox. Defaults to the [client configuration][be]. This value must be set here or in the client configuration. |
| `cursor` | A cursor from a previous response. Use this to retrieve the next page of results. |
| `limit` | The maximum number of groups to return per page. Defaults to `20`. Must be between `1` and `100`. |

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`][bn] object.

*Raises:* [`RateLimitError`][ba], [`ClientError`][bb], [`ServerError`][bc], [`RenderError`][bd]

```python
group = sandboxes.create_group("Agent environments", region="oregon")
print(group.id)
```

| Parameter | Description |
| --- | --- |
| `name` | *Required.* The name of the sandbox group. |
| `owner_id` | The ID of the workspace that owns the sandbox. Defaults to the [client configuration][be]. This value must be set here or in the client configuration. |
| `region` | The region for the sandbox group. Currently, only `"oregon"` is supported. Omit to use the workspace default. |

###### `get_group(sandbox_group_id) -> SandboxGroup`

Retrieves the details of the sandbox group with the specified ID.

*On success:* Returns a [`SandboxGroup`][bn] object.

*Raises:* [`RateLimitError`][ba], [`ClientError`][bb], [`ServerError`][bc], [`RenderError`][bd]

```python
group = sandboxes.get_group("sbg-abc123")
print(group.concurrency_limit)
```

| Parameter | Description |
| --- | --- |
| `sandbox_group_id` | *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`][bn] object with the effective concurrency limit.

*Raises:* [`RateLimitError`][ba], [`ClientError`][bb], [`ServerError`][bc], [`RenderError`][bd]

```python
group = sandboxes.update_group("sbg-abc123", concurrency_limit=10)
```

| Parameter | Description |
| --- | --- |
| `sandbox_group_id` | *Required.* The ID of the sandbox group. |
| `concurrency_limit` | *Required.* The maximum number of active sandboxes in the group. Must be at least `1`. Render applies its concurrency cap, so setting a higher value does not raise that cap. See [Concurrency][v]. |

## 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.

###### `SandboxEndedError(ClientError)`

Raised when command execution or file transfer encounters a sandbox that is `terminated` or `errored`. Includes the status in `sandbox_status`.

### 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`][bf] 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][b].

###### `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`][bh].

------

##### `id`

The sandbox's ID.

##### `status`

The sandbox's current status:

| Status | Description |
| --- | --- |
| *`creating`* | *Creation is in progress.* The sandbox is not yet ready to execute commands or transfer files. |
| *`running`* | *The sandbox is ready.* You can execute commands and transfer files. |
| *`suspending`* | *Suspension is in progress.* Render is saving the sandbox's state. |
| *`suspended`* | *The sandbox is suspended.* Executing a command or transferring files resumes it automatically. |
| *`resuming`* | *Resumption is in progress.* Render is restoring the sandbox's saved state. |
| *`errored`* | *The sandbox encountered an error.* It can no longer execute commands or transfer files. |
| *`terminated`* | *The sandbox has been terminated.* It can no longer execute commands or transfer files. |

##### `plan`

The sandbox's compute plan.

##### `network_policy`

A `NetworkPolicy` object with `type` and `rules` fields. See the supported [`network_policy` fields][y].

##### `region`

The Render region in which the sandbox runs.

##### `timeout_seconds`

The sandbox's runtime timeout, in seconds. `0` indicates that the timeout is disabled. This timeout restarts if the sandbox is suspended and later resumed.

##### `idle_timeout_seconds`

The period of inactivity before the sandbox is suspended, in seconds. `0` disables automatic idle suspension. See [Idle suspension][n].

##### `sandbox_group_id`

The ID of the sandbox group that contains the sandbox.

##### `created_at`

The time when the sandbox was created, as a `datetime`.

##### `terminated_at`

The time when the sandbox was terminated, as a `datetime`, or `None` if it has not been terminated.

------

###### `SandboxList`

Represents one page of sandboxes returned by `list()`.

| Property | Description |
| --- | --- |
| `sandboxes` | A list of `Sandbox` objects in this page. |
| `next_cursor` | The cursor to pass on the next request. `None` when the current page is empty. |

###### `SandboxGroup`

Represents a sandbox group returned by a group method or included in a [`SandboxGroupList`][bm].

| Property | Description |
| --- | --- |
| `id` | The sandbox group's ID. |
| `owner_id` | The ID of the workspace that owns the sandbox group. |
| `name` | The sandbox group's name. |
| `region` | The Render region that the sandbox group belongs to. |
| `is_default` | Whether this is the workspace's default sandbox group. |
| `concurrency_limit` | The effective limit on active sandboxes in this group. Suspended sandboxes do not count toward the limit. See [Concurrency][v]. |
| `created_at` | The time when the sandbox group was created, as a `datetime`. |
| `updated_at` | The time when the sandbox group was last updated, as a `datetime`. |
| `environment_id` | The ID of the associated environment, or `None` if the group has none. |

###### `SandboxGroupList`

Represents one page of sandbox groups returned by `list_groups()`.

| Property | Description |
| --- | --- |
| `groups` | A list of `SandboxGroup` objects in this page. |
| `next_cursor` | The cursor to pass on the next request. `None` when the current page is empty. |

###### `Snapshot`

Represents a snapshot returned by a `snapshots` method or included in a `SnapshotList`.

------

##### `id`

The snapshot's ID.

##### `sandbox_group_id`

The ID of the sandbox group that contains the snapshot.

##### `source_sandbox_id`

The ID of the sandbox from which the snapshot was captured.

##### `name`

The optional name assigned when the snapshot was created, or `None`.

##### `kind`

The snapshot type: `filesystem` or `runtime`.

##### `status`

The snapshot's current status:

| Status | Description |
| --- | --- |
| *`creating`* | *Capture is in progress.* New sandboxes cannot yet be restored from the snapshot. |
| *`available`* | *Capture succeeded.* New sandboxes can now be restored from the snapshot. |
| *`failed`* | *Capture failed.* Check the snapshot's `error` field for details. |

##### `plan`

The compute plan of the source sandbox.

##### `requested_at`

The time when snapshot capture was requested, as a `datetime`.

##### `captured_at`

The time when capture completed, as a `datetime`, or `None` while the snapshot is still being created.

##### `expires_at`

The snapshot's current expiration time, as a `datetime`. Restoring from the snapshot refreshes its TTL and updates this time accordingly.

For a snapshot with TTL disabled, this value is `9999-12-31T23:59:59Z`.

##### `ttl_seconds`

The snapshot's total time-to-live (TTL), in seconds.

This value does not dynamically decrement to reflect the current amount of time until expiration. Use the [`expires_at`](<https://render.com/docs/sandboxes-sdk-python.md#expires-at>) property instead.

For a snapshot with TTL disabled, this value is `0`.

##### `size_bytes`

The snapshot's size in bytes, or `None` until capture completes.

##### `error`

The capture error message if capture failed, otherwise `None`.

------

###### `SnapshotList`

Represents one page of snapshots returned by `snapshots.list()`.

| Property | Description |
| --- | --- |
| `snapshots` | A list of `Snapshot` objects in this page. |
| `next_cursor` | The cursor to pass on the next request. `None` when the current page is empty. |

###### `SandboxExecOutput`

Represents an output event yielded by `exec()`.

| Property | Description |
| --- | --- |
| `stream` | The output stream: `stdout` or `stderr`. |
| `data` | The output text. |

###### `SandboxExecExit`

Represents the final event yielded by `exec()`.

| Property | Description |
| --- | --- |
| `exit_code` | The command's exit code. |

###### `SandboxExecEvent`

The `SandboxExecEvent` type is a `SandboxExecOutput` or `SandboxExecExit` object yielded by `exec()`.



# Render Sandboxes CLI Reference
Source: https://render.com/docs/cli-reference

Full CLI reference: [Render CLI Reference][i].

For installation, authentication, and workspace selection, see [the Render CLI guide](<https://render.com/docs/cli.md#setup>). For scripts and agents, see [non-interactive mode](<https://render.com/docs/cli.md#non-interactive-mode>).

## Global options

| Option | Description |
| --- | --- |
| `--confirm` | Skip all confirmation prompts |
| `--output`, `-o` | Set output format to interactive, json, yaml, or text. Auto-switches to text on non-TTY |

## Sandboxes

### Sandbox lifecycle

###### `sandboxes`

Manage sandboxes for your Render workspace.

Sandboxes are ephemeral compute environments for running code, agents, and experiments.

Every sandbox belongs to a sandbox group, which scopes it to a region. Manage
groups with "render sandbox-groups".

Snapshot a sandbox with "render sandboxes snapshots create" and restore new
sandboxes from it with "render sandboxes create `--snapshot-id`".

*Usage:*

```bash
render sandboxes
```

*Available commands:*

| Command | Description |
| --- | --- |
| [`copy`][2] | Copy files to or from a sandbox |
| [`create`][w] | Create a new sandbox |
| [`exec`](<https://render.com/docs/cli-reference.md#sandboxes-exec>) | Execute a command in a sandbox |
| [`list`](<https://render.com/docs/cli-reference.md#sandboxes-list>) | List sandboxes |
| [`snapshots`](<https://render.com/docs/cli-reference.md#sandboxes-snapshots>) | Manage sandbox snapshots |
| [`stop`](<https://render.com/docs/cli-reference.md#sandboxes-stop>) | Terminate a sandbox |

*Examples:*

```bash
render sandboxes create
render sandboxes create --plan=2c-4g --region=oregon
render sandboxes create --snapshot-id snp-abc123
render sandboxes copy ./main.py sbx-abc123:/app/main.py
render sandboxes exec sbx-abc123 -- echo hello
render sandboxes snapshots create sbx-abc123
render sandboxes snapshots list --group sbg-abc123
render sandboxes stop sbx-abc123 --confirm
```

*Options:*

[Global options][bo] only

###### `sandboxes create`

Create a new sandbox in the current workspace.

*Usage:*

```bash
render sandboxes create
```

*Examples:*

```bash
render sandboxes create
render sandboxes create --name=my-agent
render sandboxes create --plan=2c-4g
render sandboxes create --group=sbg-cph1rs3idesc73a2b2mg
render sandboxes create --timeout=3600
render sandboxes create --timeout=0
render sandboxes create --idle-timeout=1800
render sandboxes create --idle-timeout=0
render sandboxes create --network-policy=deny-all
render sandboxes create --allow-egress-https api.github.com --allow-egress-https '*.pypi.org'
render sandboxes create --env-var FOO=bar --env-var BAZ=qux
render sandboxes create --env-file .env.production --env-var LOG_LEVEL=debug
render sandboxes create --from gold
render sandboxes create --from snp-cph1rs3idesc73a2b2mg
render sandboxes create --image python
render sandboxes create --image sbb-cph1rs3idesc73a2b2mg
render sandboxes create --from gold --wait
```

*Options:*

[Global options][bo], plus:

| Option | Description |
| --- | --- |
| `--allow-egress-https` | Allow outbound HTTPS to a domain, e.g. api.example.com or *.example.com. Repeat for multiple domains. Implies `--network-policy=allow-list` |
| `--env-file` | Path to an env file to load. Repeat to load multiple files (later files override earlier ones). Every listed file must exist. |
| `--env-var` | Set environment variables in `KEY=VALUE` format (can be specified multiple times). Inline values override values loaded from `--env-file`. |
| `--from` | Start from a snapshot ID or name |
| `--group` | Sandbox group ID. Omit to use the workspace default group |
| `--idle-timeout` | Seconds of inactivity before suspension. 0 disables automatic idle suspension |
| `--image` | Start from an imported image instead of the base image, by image ID or name. A name uses the newest succeeded image with that name in the sandbox group |
| `--name` | Label the sandbox, e.g. my-agent. Names aren't unique; use the ID to address the sandbox. Up to 64 characters, and can't start with sbx- |
| `--network-policy` | Outbound network policy: allow-all, deny-all, allow-list |
| `--plan` | Compute plan: 1c-2g, 2c-4g, 4c-8g, 8c-16g |
| `--region` | Accepted for compatibility; placement uses the sandbox group region |
| `--snapshot-id` | Start from this snapshot instead of the base image. The snapshot must be available and in the same sandbox group. A runtime snapshot requires `--plan` to match its plan. |
| `--timeout` | Maximum sandbox lifetime in seconds, up to 2592000 (30 days). 0 means no timeout. Omit to use the default of 86400 (24 hours) |
| `--wait` | Wait until the sandbox is running, up to 60 seconds, instead of returning while it's still creating |

###### `sandboxes list`

List sandboxes in your workspace.

By default, terminated sandboxes are excluded. Use `--all` to include them, or `--status` to filter by specific statuses.

*Usage:*

```bash
render sandboxes list
```

*Examples:*

```bash
render sandboxes list
render sandboxes list --all
render sandboxes list --name=my-agent
render sandboxes list --status=running
render sandboxes list --status=running --status=creating
render sandboxes list -o json
```

*Options:*

[Global options][bo], plus:

| Option | Description |
| --- | --- |
| `--all` | Include terminated sandboxes |
| `--group` | Filter by sandbox group ID |
| `--name` | Filter by exact sandbox name. Names aren't unique, so this can match more than one sandbox |
| `--status` | Filter by status (repeatable: creating, running, suspending, suspended, resuming, errored, terminated) |

###### `sandboxes stop <sandboxId>`

Terminate a running sandbox. This action is irreversible.

Without `--confirm`, this command previews what would be terminated and makes no
changes. Pass `--confirm` to actually terminate the sandbox.

*Usage:*

```bash
render sandboxes stop <sandboxId>
```

*Examples:*

```bash
# Preview termination (no changes made)
render sandboxes stop sbx-abc123

# Terminate the sandbox
render sandboxes stop sbx-abc123 --confirm

# JSON output
render sandboxes stop sbx-abc123 --confirm --output json
```

*Options:*

[Global options][bo] only

### Runtime execution

###### `sandboxes copy <src> <dst>`

Copy a file or directory between the local filesystem and a running sandbox.

Prefix the remote side with the sandbox ID and a colon, like scp. A relative
sandbox path resolves inside the sandbox's home directory; an absolute path
addresses the sandbox filesystem root. Directories are transferred as
archives: uploading a local directory recreates it at the sandbox path, and
downloading a sandbox directory recreates it under the local path. "cp" works
as an alias.

Unlike cp, a directory destination is not nested into: copying ./src to
sbx-abc123:/tmp/src puts src's contents at /tmp/src, not at /tmp/src/src. A
single file copied to an existing local directory does land inside it.

*Usage:*

```bash
render sandboxes copy <src> <dst>
```

*Aliases:* `cp`

*Examples:*

```bash
render sandboxes copy ./main.py sbx-abc123:main.py
render sandboxes copy sbx-abc123:output.json ./output.json
render sandboxes copy ./src sbx-abc123:/tmp/src
render sandboxes cp sbx-abc123:. ./sandbox-home
render sandboxes copy sbx-abc123:output.json ./downloads/ --output json
```

*Options:*

[Global options][bo] only

###### `sandboxes exec <sandboxId> -- <command>`

Run a single command in a running sandbox. Streams stdout and stderr as
the command runs, then exits with the remote command's exit code.

Pass the command after a "--" separator so its own flags aren't parsed by the
CLI.

*Usage:*

```bash
render sandboxes exec <sandboxId> -- <command>
```

*Examples:*

```bash
render sandboxes exec sbx-abc123 -- echo hello
render sandboxes exec sbx-abc123 -- python script.py
```

*Options:*

[Global options][bo] only

### Snapshot management

###### `sandboxes snapshots`

Manage snapshots of sandboxes in your Render workspace.

A snapshot captures a running sandbox so a new sandbox can be restored from it with "render sandboxes create `--snapshot-id`". A filesystem snapshot captures the writable filesystem and restores onto any plan. A runtime snapshot also captures memory and CPU state and restores only onto the plan of the source sandbox.

Snapshots belong to the sandbox group of their source sandbox. Getting, listing, or deleting a snapshot uses the active workspace's default group unless `--group` is provided.

*Usage:*

```bash
render sandboxes snapshots
```

*Available commands:*

| Command | Description |
| --- | --- |
| [`create`](<https://render.com/docs/cli-reference.md#sandboxes-snapshots-create>) | Snapshot a running sandbox |
| [`delete`](<https://render.com/docs/cli-reference.md#sandboxes-snapshots-delete>) | Delete a sandbox snapshot |
| [`get`](<https://render.com/docs/cli-reference.md#sandboxes-snapshots-get>) | Get a sandbox snapshot |
| [`list`](<https://render.com/docs/cli-reference.md#sandboxes-snapshots-list>) | List sandbox snapshots |

*Examples:*

```bash
# Snapshot a running sandbox
render sandboxes snapshots create sbx-abc123

# List the snapshots in the default sandbox group
render sandboxes snapshots list

# List the snapshots in a specific sandbox group
render sandboxes snapshots list --group sbg-abc123

# Get one snapshot
render sandboxes snapshots get snp-abc123

# Delete a snapshot
render sandboxes snapshots delete snp-abc123 --confirm

# Delete a snapshot in a specific group
render sandboxes snapshots delete snp-abc123 --group sbg-abc123 --confirm
```

*Options:*

[Global options][bo] only

###### `sandboxes snapshots create <sandboxId>`

Capture a snapshot of a running sandbox.

The command returns as soon as the API accepts the request, while the snapshot
status is still "creating". Pass `--wait` to return once it's "available", so a
sandbox can start from it.

The sandbox keeps running after the capture.

*Usage:*

```bash
render sandboxes snapshots create <sandboxId>
```

*Examples:*

```bash
# Snapshot the filesystem, memory, and CPU state (default)
render sandboxes snapshots create sbx-abc123

# Snapshot only the filesystem
render sandboxes snapshots create sbx-abc123 --kind filesystem

# Name the snapshot
render sandboxes snapshots create sbx-abc123 --name gold

# Wait until new sandboxes can start from it
render sandboxes snapshots create sbx-abc123 --name gold --wait

# JSON output
render sandboxes snapshots create sbx-abc123 --output json
```

*Options:*

[Global options][bo], plus:

| Option | Description |
| --- | --- |
| `--kind` | Snapshot kind: runtime (default), filesystem |
| `--name` | Name the snapshot |
| `--wait` | Wait until the snapshot is available, up to 5 minutes |

###### `sandboxes snapshots delete <snapshotId>`

Delete one sandbox snapshot by ID. This action is irreversible.

Uses the active workspace's default sandbox group unless `--group` is provided.
Without `--confirm`, this command previews what would be deleted and makes no
changes. A snapshot that is still being created cannot be deleted yet. An
expired snapshot is reported as not found.

*Usage:*

```bash
render sandboxes snapshots delete <snapshotId>
```

*Examples:*

```bash
# Preview deletion (no changes made)
render sandboxes snapshots delete snp-abc123

# Delete the snapshot
render sandboxes snapshots delete snp-abc123 --confirm

# Delete a snapshot in a specific group
render sandboxes snapshots delete snp-abc123 --group sbg-abc123 --confirm

# JSON output
render sandboxes snapshots delete snp-abc123 --confirm --output json
```

*Options:*

[Global options][bo], plus:

| Option | Description |
| --- | --- |
| `--group` | Sandbox group the snapshot belongs to (defaults to the active workspace's default group) |

###### `sandboxes snapshots get <snapshotId>`

Get one sandbox snapshot by ID.

Uses the active workspace's default sandbox group unless `--group` is provided.
An expired snapshot is reported as not found.

*Usage:*

```bash
render sandboxes snapshots get <snapshotId>
```

*Examples:*

```bash
# Get a snapshot
render sandboxes snapshots get snp-abc123

# Get a snapshot in a specific group
render sandboxes snapshots get snp-abc123 --group sbg-abc123

# JSON output
render sandboxes snapshots get snp-abc123 --output json
```

*Options:*

[Global options][bo], plus:

| Option | Description |
| --- | --- |
| `--group` | Sandbox group the snapshot belongs to (defaults to the active workspace's default group) |

###### `sandboxes snapshots list`

List the snapshots in a sandbox group, newest first.

Uses the active workspace's default sandbox group unless `--group` is provided.
Deleted and expired snapshots are not listed.

*Usage:*

```bash
render sandboxes snapshots list
```

*Examples:*

```bash
# List every snapshot in the default sandbox group
render sandboxes snapshots list

# List snapshots in a specific group
render sandboxes snapshots list --group sbg-abc123

# Only snapshots that are ready to start a sandbox from
render sandboxes snapshots list --status available

# JSON output
render sandboxes snapshots list --output json
```

*Options:*

[Global options][bo], plus:

| Option | Description |
| --- | --- |
| `--group` | Sandbox group to list (defaults to the active workspace's default group) |
| `--status` | Filter by status (repeatable: creating, available, failed) |

### Sandbox group management

###### `sandbox-groups`

Manage sandbox groups for your Render workspace.

Sandbox groups scope a workspace's sandboxes to a region and (optionally) an
environment. The workspace's first group is its default until you set
another with "render sandbox-groups default set".

*Usage:*

```bash
render sandbox-groups
```

*Available commands:*

| Command | Description |
| --- | --- |
| [`create`](<https://render.com/docs/cli-reference.md#sandbox-groups-create>) | Create a sandbox group in the active workspace |
| [`default`](<https://render.com/docs/cli-reference.md#sandbox-groups-default>) | Manage the workspace's default sandbox group |
| [`delete`](<https://render.com/docs/cli-reference.md#sandbox-groups-delete>) | Delete a sandbox group |
| [`list`](<https://render.com/docs/cli-reference.md#sandbox-groups-list>) | List sandbox groups in the active workspace |

*Examples:*

```bash
render sandbox-groups list
render sandbox-groups list -o json
render sandbox-groups create --name agents
render sandbox-groups default set sbg-abc123
render sandbox-groups delete sbg-abc123 --confirm
```

*Options:*

[Global options][bo] only

###### `sandbox-groups create`

Create a sandbox group in your workspace.

Group names are unique within a workspace. The workspace's first group becomes
its default, where "render sandboxes create" places sandboxes unless
`--group` is given.

*Usage:*

```bash
render sandbox-groups create
```

*Examples:*

```bash
# Create a sandbox group
render sandbox-groups create --name agents

# Output as JSON
render sandbox-groups create --name agents -o json
```

*Options:*

[Global options][bo], plus:

| Option | Description |
| --- | --- |
| `--name` | Name for the group, unique within the workspace |

###### `sandbox-groups default`

Manage the workspace's default sandbox group.

The default group is where "render sandboxes create" places sandboxes unless
`--group` is given. A workspace has exactly one default group.

*Usage:*

```bash
render sandbox-groups default
```

*Available commands:*

| Command | Description |
| --- | --- |
| [`set`](<https://render.com/docs/cli-reference.md#sandbox-groups-default-set>) | Make a sandbox group the workspace's default |

*Options:*

[Global options][bo] only

###### `sandbox-groups default set <sandboxGroupId>`

Make a sandbox group the default for its workspace.

The previous default stops being the default. Running this on the current
default makes no changes. A suspended group cannot be made the default.

*Usage:*

```bash
render sandbox-groups default set <sandboxGroupId>
```

*Examples:*

```bash
# Make a group the default
render sandbox-groups default set sbg-abc123

# Output as JSON
render sandbox-groups default set sbg-abc123 -o json
```

*Options:*

[Global options][bo] only

###### `sandbox-groups delete <sandboxGroupId>`

Delete a sandbox group. This action is irreversible.

Deleting a group terminates its sandboxes and deletes its snapshots shortly after. Suspended groups cannot be deleted. The workspace's
default group cannot be deleted; make another group the default with
"render sandbox-groups default set `<sandboxGroupId>`" first. Without `--confirm`,
show the group that would be deleted without making changes.

*Usage:*

```bash
render sandbox-groups delete <sandboxGroupId>
```

*Examples:*

```bash
# Preview group deletion (no changes made)
render sandbox-groups delete sbg-abc123

# Delete the group
render sandbox-groups delete sbg-abc123 --confirm

# Output as JSON
render sandbox-groups delete sbg-abc123 --confirm -o json
```

*Options:*

[Global options][bo] only

###### `sandbox-groups list`

List all sandbox groups in your workspace, newest first.

*Usage:*

```bash
render sandbox-groups list
```

*Examples:*

```bash
# List sandbox groups in the active workspace
render sandbox-groups list

# Output as JSON
render sandbox-groups list -o json
```

*Options:*

[Global options][bo] only



# Glossary

The following terms are used throughout the Render docs:

###### private network

Your Render services in the same *region* can reach each other without traversing the public internet, enabling faster and safer communication.

###### Render Sandboxes

Create a sandbox to execute untrusted code in a managed, ephemeral environment.

Ideal for agents, code interpreters, builds, tests, and other workloads that require isolated execution.

###### compute plan

Specifies the CPU and RAM available to a running *instance* on Render.

For example, common compute plans for a new *web service* include:

- *`free`*: 0.1 CPU / 512 MB RAM
- *`0.5c-512mb`*: 0.5 CPU / 512 MB RAM
- *`1c-2g`*: 1 CPU / 2 GB RAM

Compute plans were previously known as *instance types*.

###### region

Each Render service runs in one of the following regions: *Oregon*, *Ohio*, *Virginia*, *Frankfurt*, or *Singapore*.

Services in the same region can communicate over their *private network*.



[a]: <https://render.com/docs/sandboxes.md>
[b]: <https://render.com/docs/sandboxes-limits.md>
[c]: <https://render.com/docs/sandboxes-creating.md>
[d]: <https://render.com/docs/sandboxes-executing.md>
[e]: <https://render.com/docs/sandboxes-files.md>
[f]: <https://render.com/docs/sandboxes-snapshots.md>
[g]: <https://render.com/docs/sandboxes-sdk-typescript.md>
[h]: <https://render.com/docs/sandboxes-sdk-python.md>
[i]: <https://render.com/docs/cli-reference.md>
[j]: <https://render.com/docs/sandboxes-creating.md#terminating-a-sandbox>
[k]: <https://render.com/docs/sandboxes-creating.md#runtime-timeout>
[l]: <https://render.com/docs/sandboxes-creating.md#setting-timeouts>
[m]: <https://render.com/docs/sandboxes-files.md#downloading-a-file>
[n]: <https://render.com/docs/sandboxes-creating.md#idle-timeout>
[o]: <https://render.com/docs/sandboxes-creating.md#compute-plan>
[p]: <https://render.com/docs/sandboxes-creating.md#network-access>
[q]: <https://dashboard.render.com/u/settings?add-api-key>
[r]: <https://dashboard.render.com>
[s]: <https://render.com/docs/sandboxes-creating.md#configuring-sandbox-behavior>
[t]: <https://render.com/docs/sandboxes-creating.md#sandbox-groups>
[u]: <https://render.com/docs/sandboxes-creating.md#timeouts>
[v]: <https://render.com/docs/sandboxes-limits.md#concurrency-per-group>
[w]: <https://render.com/docs/cli-reference.md#sandboxes-create>
[x]: <https://render.com/docs/sandboxes-sdk-typescript.md#create>
[y]: <https://render.com/docs/sandboxes-sdk-python.md#create>
[z]: <https://render.com/docs/sandboxes-limits.md#compute-plans-and-billing>
[0]: <https://render.com/docs/sandboxes-limits.md#general-limits>
[1]: <https://render.com/docs/sandboxes-sdk-python.md#exec>
[2]: <https://render.com/docs/cli-reference.md#sandboxes-copy>
[3]: <https://render.com/docs/sandboxes-sdk-typescript.md#upload>
[4]: <https://render.com/docs/sandboxes-sdk-python.md#copy-to>
[5]: <https://render.com/docs/sandboxes-sdk-typescript.md#download>
[6]: <https://render.com/docs/sandboxes-sdk-typescript.md#copyfrom>
[7]: <https://render.com/docs/sandboxes-sdk-python.md#copy-from>
[8]: <https://render.com/docs/sandboxes-snapshots.md#snapshot-retention>
[9]: <https://render.com/docs/sandboxes-sdk-typescript.md#snapshots-create>
[aa]: <https://render.com/docs/sandboxes-sdk-python.md#snapshots-create>
[ab]: <https://render.com/docs/sandboxes-snapshots.md#retrieving-snapshot-details>
[ac]: <https://render.com/docs/sandboxes-snapshots.md#capturing-a-snapshot>
[ad]: <https://render.com/docs/sandboxes-snapshots.md#restoring-from-a-snapshot>
[ae]: <https://render.com/docs/sandboxes-sdk-python.md#ttl-seconds>
[af]: <https://platform.claude.com/settings/keys>
[ag]: <https://render.com/docs/sandboxes.md#beta-limitations>
[ah]: <https://render.com/docs/cli.md>
[ai]: <https://cursor.com/docs/account/enterprise/service-accounts>
[aj]: <https://cursor.com/docs/cloud-agent/self-hosted/pool#any-repo-pools>
[ak]: <https://platform.openai.com/api-keys>
[al]: <https://platform.openai.com/agents?tab=environments&environment_view=keys>
[am]: <https://developers.openai.com/api/docs/guides/agents-api/environments/self-hosted#authentication>
[an]: <https://render.com/docs/sandboxes-sdk-typescript.md#rendererror>
[ao]: <https://render.com/docs/sandboxes-sdk-typescript.md#sandbox>
[ap]: <https://render.com/docs/sandboxes-sdk-typescript.md#sandboxcreatewaiterror>
[aq]: <https://render.com/docs/sandboxes-sdk-typescript.md#aborterror>
[ar]: <https://render.com/docs/sandboxes-sdk-typescript.md#sandboxsnapshotnotfounderror>
[as]: <https://render.com/docs/sandboxes-sdk-typescript.md#sandboxsnapshotnotreadyerror>
[at]: <https://render.com/docs/sandboxes-sdk-typescript.md#clienterror>
[au]: <https://render.com/docs/sandboxes-sdk-typescript.md#servererror>
[av]: <https://render.com/docs/sandboxes-sdk-typescript.md#2-import-the-client>
[aw]: <https://render.com/docs/sandboxes-sdk-typescript.md#terminate>
[ax]: <https://render.com/docs/sandboxes-sdk-typescript.md#waituntilrunning>
[ay]: <https://render.com/docs/sandboxes-sdk-typescript.md#sandboxendederror>
[az]: <https://render.com/docs/sandboxes-sdk-typescript.md#sandboxdownload>
[a0]: <https://render.com/docs/sandboxes-sdk-typescript.md#sandboxdownloadtoolargeerror>
[a1]: <https://render.com/docs/sandboxes-sdk-typescript.md#sandboxsnapshot>
[a2]: <https://render.com/docs/sandboxes-sdk-typescript.md#sandboxsnapshotcreatewaiterror>
[a3]: <https://render.com/docs/sandboxes-sdk-typescript.md#snapshots-waituntilavailable>
[a4]: <https://render.com/docs/sandboxes-sdk-typescript.md#sandboxgroupwithcursor>
[a5]: <https://render.com/docs/sandboxes-sdk-typescript.md#sandboxgroup>
[a6]: <https://render.com/docs/sandboxes-sdk-python.md#sandbox>
[a7]: <https://render.com/docs/sandboxes-sdk-python.md#sandboxcreatewaiterror>
[a8]: <https://render.com/docs/sandboxes-sdk-python.md#snapshotnotfounderror>
[a9]: <https://render.com/docs/sandboxes-sdk-python.md#snapshotnotreadyerror>
[ba]: <https://render.com/docs/sandboxes-sdk-python.md#ratelimiterror>
[bb]: <https://render.com/docs/sandboxes-sdk-python.md#clienterror>
[bc]: <https://render.com/docs/sandboxes-sdk-python.md#servererror>
[bd]: <https://render.com/docs/sandboxes-sdk-python.md#rendererror>
[be]: <https://render.com/docs/sandboxes-sdk-python.md#2-import-the-client-sync-or-async>
[bf]: <https://render.com/docs/sandboxes-sdk-python.md#terminate>
[bg]: <https://render.com/docs/sandboxes-sdk-python.md#sandboxnotfounderror>
[bh]: <https://render.com/docs/sandboxes-sdk-python.md#sandboxlist>
[bi]: <https://render.com/docs/sandboxes-sdk-python.md#sandboxendederror>
[bj]: <https://render.com/docs/sandboxes-sdk-python.md#sandboxfilenotfounderror>
[bk]: <https://render.com/docs/sandboxes-sdk-python.md#snapshot>
[bl]: <https://render.com/docs/sandboxes-sdk-python.md#snapshotcreatewaiterror>
[bm]: <https://render.com/docs/sandboxes-sdk-python.md#sandboxgrouplist>
[bn]: <https://render.com/docs/sandboxes-sdk-python.md#sandboxgroup>
[bo]: <https://render.com/docs/cli-reference.md#global-options>
