# Creating and Configuring Sandboxes — Configure sandbox compute, environment variables, and network access.

> This article is part of the [Render Sandboxes documentation bundle](https://render.com/docs/sandboxes/all). Fetch the bundle for all related articles in one Markdown document.


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

You can create [sandboxes](/docs/sandboxes.md) 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](/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`](/docs/cli-reference.md#sandboxes-create) 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`](/docs/sandboxes-sdk-typescript.md#create) 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`](/docs/sandboxes-sdk-python.md#create) 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`](/docs/sandboxes-sdk-python.md#create) with the sandbox's configuration options as keyword parameters.

This example sets a five-minute [runtime timeout](#runtime-timeout) and waits up to the default timeout of 60 seconds for the sandbox to become ready. After creation succeeds, you can [execute commands](/docs/sandboxes-executing.md) and [manage files](/docs/sandboxes-files.md) 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](/docs/sandboxes-limits.md#compute-plans-and-billing).

When [restoring from a snapshot](/docs/sandboxes-snapshots.md), 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](#setting-timeouts).

*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](/docs/sandboxes-snapshots.md), 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](/docs/sandboxes-snapshots.md) 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](/docs/sandboxes-executing.md) or [file transfer](/docs/sandboxes-files.md) is in progress.

- For a new sandbox, defaults to `900` (15 minutes)
- For a sandbox restored from a [snapshot](/docs/sandboxes-snapshots.md), 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](#network-access) 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](#runtime-timeout) of one hour and an [idle timeout](#idle-timeout) 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`](/docs/cli-reference.md#sandboxes-create), 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`](/docs/sandboxes-sdk-typescript.md#create), 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`](/docs/sandboxes-sdk-python.md#create), 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`](/docs/sandboxes-sdk-python.md#create), 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](/docs/sandboxes-limits.md#general-limits) 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](/docs/sandboxes-snapshots.md) 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](/docs/sandboxes-snapshots.md) available to restore from when creating a sandbox in the group
- The sandbox's [concurrency limit](/docs/sandboxes-limits.md#concurrency-per-group)

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](/docs/sandboxes-sdk-typescript.md#listgroups) or [Python](/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](https://dashboard.render.com). 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](/docs/sandboxes-snapshots.md), 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](/docs/sandboxes-limits.md#concurrency-per-group) (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](/docs/sandboxes-sdk-typescript.md#list) and [Python](/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.

---

##### Appendix: Glossary definitions

###### 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*.

Related article: https://render.com/docs/compute-plans.md

###### 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*.

Related article: https://render.com/docs/regions.md