Visitar URL original
Creating and Configuring Sandboxes – Render Docs

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

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

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 , which provides 1 CPU and 2 GB RAM. You can specify a different compute plan with the following syntax:

Render CLI

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.

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

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:

Environment variables

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

Render CLI

You can also load variables from an environment file:

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

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

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

  • 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
  • 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

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

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

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

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

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

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

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

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

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