Creating and Configuring Sandboxes

Configure sandbox compute, environment variables, and network access.

Render Sandboxes is in public beta.

APIs, defaults, and limits might change during the beta period.

You can create sandboxes 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.

Basic example

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

Render CLI

shell

$ render sandboxes create --timeout=300 --wait

Run render sandboxes create with flags for the sandbox's configuration options.

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 with an object containing the sandbox's configuration options.

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 with the sandbox's configuration options as keyword parameters.

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 with the sandbox's configuration options as keyword parameters.

This example sets a five-minute 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 and manage files 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:

Render CLI

shell

$ render sandboxes create \
    --wait \
    --plan=2c-4g

TypeScript SDK

typescript

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

Python SDK (sync)

python

sandbox = sandboxes.create(
    plan="2c-4g", 
    wait=True,
)

Python SDK (async)

python

sandbox = await sandboxes.create(
    plan="2c-4g", 
    wait=True,
)

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

When restoring from a snapshot, 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.

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

Timeout Description

Timeout	Description
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, 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 filesystem is permanently lost. To preserve its state for future sandboxes, capture a snapshot 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 or file transfer is in progress. For a new sandbox, defaults to `900` (15 minutes) For a sandbox restored from a snapshot, 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 when it resumes. Background processes do not keep a sandbox active after the command that started them finishes.

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, 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 filesystem is permanently lost. To preserve its state for future sandboxes, capture a snapshot before it terminates.

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 or file transfer is in progress.

For a new sandbox, defaults to 900 (15 minutes)
For a sandbox restored from a snapshot, 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 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 of one hour and an idle timeout of 30 minutes.

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

Render CLI

When creating a sandbox with sandboxes create, set runtime timeout with --timeout and idle timeout with --idle-timeout:

shell

$ render sandboxes create --timeout=3600 --idle-timeout=1800 --wait

TypeScript SDK

When creating a sandbox with sandboxes.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
})

Python SDK (sync)

When creating a sandbox with sandboxes.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,
)

Python SDK (async)

When creating a sandbox with sandboxes.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:

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.

TypeScript SDK

typescript

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

Python SDK (sync)

python

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

Python SDK (async)

python

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

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

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.

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.

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.

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 available to restore from when creating a sandbox in the group
The sandbox's concurrency limit

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:

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

TypeScript SDK

typescript

const entries = await sandboxes.listGroups()

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

Python SDK (sync)

python

result = sandboxes.list_groups()

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

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 or Python 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:

Render CLI

shell

$ render sandbox-groups create --name agents

TypeScript SDK

typescript

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

Python SDK (sync)

python

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

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

Render CLI

shell

$ render sandboxes create --group=sbg-abc123 --timeout=300 --wait

TypeScript SDK

typescript

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

Python SDK (sync)

python

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

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

TypeScript SDK

typescript

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

Python SDK (sync)

python

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

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 1,000 (even if you provide a higher value). For details, see Concurrency per group.

Finding existing sandboxes

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

Render CLI

shell

$ render sandboxes list --status running

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

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').

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").

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 and Python references.

Terminating a sandbox

Terminate a sandbox when you no longer need it:

Render CLI

shell

$ render sandboxes stop sbx-abc123 --confirm

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

TypeScript SDK

typescript

await sandboxes.terminate(sandbox.id)

Python SDK (sync)

python

sandboxes.terminate(sandbox.id)

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.