Sandboxes

A sandbox runs a pipeline step or a module build as a Firecracker microVM. The microVM runs on a pool of EC2 hosts in your AWS account. Steps start in seconds when a host has room. When no host is available, Ravion launches one. Each execution environment can have one sandbox pool. The first step that targets it with type: sandbox creates the pool automatically. Ravion chooses the host machine types unless you set your own. Several sandboxes can share one host.

When to use sandboxes

Use sandboxes for pipeline steps and module builds by default, including builds, tests, migrations and other scripted tasks. Use ec2 or ec2-spot infrastructure only when you need a custom AMI or direct access to a dedicated EC2 instance. Tasks that must not restart, such as migrations, can still run in a sandbox with interruptible: false.

What runs inside a sandbox

Every sandbox boots the same x86_64 Ubuntu 24.04 image, with git, GitHub CLI (gh), build-essential, Node.js 24, Docker, the AWS CLI, jq, curl and zstd. Install anything else with the step’s setup actions or commands. Docker starts in the background when the sandbox boots. The first docker command waits for it. Tools that talk to Docker another way, such as Testcontainers or a Docker SDK, must wait for the daemon themselves.

Get started

Update your AWS permissions

Sandboxes require AWS account role policy 1.0.52 or later. Upgrade to the latest version if yours is older.

Go to Settings / AWS accounts and open the account.
Click Update AWS Permissions and follow the steps to update the CloudFormation stack.

From the CLI, run ravion aws account policy-diff <aws-account-id> to review the change, then apply it with aws cloudformation update-stack and a fresh template URL from ravion aws account cloudformation-template-url <aws-account-id>.Missing permissions can prevent the pool from launching hosts. Check the reported AWS permission error if a launch fails.

Update your modules

Update your modules to the latest versions available as of October 10, 2026, or newer. Older module versions don’t support sandboxes.

Run pipeline steps or module builds in sandboxes

Set pipeline steps to type: sandbox. New module builds use sandboxes by default; switch existing modules if they still use EC2.

Pipeline steps

Set the step’s infrastructure.type to sandbox. Any step with an infrastructure block can run in a sandbox, such as custom, build:image and build:static. Use your existing execution environment’s ID or given ID in place of ci-builders below. If you need a new environment, create one in Settings / Execution environments. You don’t need to configure a pool; your first sandbox step creates it automatically.

- id: run_tests
  name: Run tests
  type: custom
  source:
    type: git
    repo: https://github.com/my-org/my-repo
    branch: main
  commands:
    - npm ci
    - npm test
  infrastructure:
    type: sandbox
    execution_environment_id: ci-builders
    cpu: 4
    memory: 16
    disk: 40
    disk_cache: auto
    interruptible: true

Field	Required	Default	What it does
`execution_environment_id`	One target	None	ID or given ID of the execution environment whose pool runs the step.
`aws_account_id` + `region`	One target	None	Use the execution environment for this account and region instead. See Limits.
`cpu`	Yes	None	vCPUs for the sandbox.
`memory`	Yes	None	Memory in GiB.
`disk`	No	8	GiB of host disk the sandbox reserves for what it writes. A host takes the step only when it has this much free.
`disk_cache`	No	`off`	Keep the sandbox’s disk between runs. See Disk cache.
`interruptible`	No	`false`	Let the step run on spot hosts and rerun from the start if its host is lost. See Interruptible steps.

Sandboxes don’t take instance_size, ami or storage. The full schema is in SandboxStepInfrastructure.

Module builds

New module builds use sandboxes by default. See Build infrastructure to configure builds or switch an existing module from EC2.

Pool settings

Open Settings / Execution environments, choose the environment, then open Config / Sandboxes. These are the defaults for a new pool. Existing pools keep their saved settings.

Setting	Default	What it does
Machine types	Automatic	Leave empty to let Ravion choose compatible types for your region and workload. Add types only to restrict that choice or customize host disks. Removing every type returns to automatic selection; it does not turn the pool off.
Host storage	Ephemeral	Ephemeral terminates idle hosts unless you keep some running. Types with an instance store use it for sandboxes and local cache. Persistent stops idle on-demand hosts and retains their disks for reuse. Spot hosts are always terminated, even in a persistent pool.
Use spot hosts for interruptible steps	On	Allows spot hosts for interruptible steps. Steps that aren’t interruptible still use on-demand hosts.
Idle hosts to keep running / Stopped hosts to retain	None	Ephemeral pools keep the chosen number running, with compute charges. Persistent pools retain stopped hosts and their disks instead. Peak matches your busiest minute; Rolling average matches your average daily peak over the selected window. Fixed keeps a set number; None keeps none.
Terminate idle hosts after (seconds)	20	How long an idle host waits before termination. With a running reserve, this becomes Terminate excess idle hosts after (seconds). Persistent pools use Stop idle hosts after (seconds).
Delete stopped hosts after (minutes)	1440	Deletes stopped hosts outside the retained reserve after this time. Persistent pools only.

To stop using sandboxes, switch your steps and module builds back to EC2. Removing a pool through the CLI tears down its hosts, but the next sandbox step creates a default pool again.

Interruptible steps and spot hosts

interruptible: true says a step can be stopped partway and started over. Builds, tests and lint usually can.

Only interruptible steps run on spot hosts, and only in a pool with Use spot hosts for interruptible steps turned on. Other steps run on on-demand hosts.
If an interruptible step’s host is lost or AWS reclaims it, Ravion reruns the step from the start on another host. The last retry always runs on an on-demand host.
If a step that isn’t interruptible loses its host, the step fails.

Leave interruptible off for steps that change things outside the sandbox and can’t safely be cut off and rerun, such as database migrations or deploys.

Disk cache

disk_cache controls whether a sandbox keeps its disk, with your dependencies, build output and Docker layers, between runs.

Value	What it does
`off`	Boot the base image every run and keep nothing. This is the default.
`auto`	Keep this step’s own disk, named by its git source and step. Needs a git `source`.
A key, such as `web-deps`	Every step in the repository that uses the same key shares one disk. The last successful run to finish saves it. Keys are up to 64 lowercase letters, digits, `.`, `_` or `-`.

A run restores the disk saved for its branch. If there’s none, it uses the disk from the branch’s pull request base, then the repository’s default branch. A run saves its disk back to its own branch only when it succeeds.

Limits and caveats

Account and region targets. With aws_account_id and region, Ravion uses that account and region’s execution environment, and creates one from the default VPC if none exists. The sandbox pool is also created automatically. Use execution_environment_id to select a specific network placement.
Size and regional availability. The step’s cpu, memory and disk must fit an available host type. If you restrict Machine types, include a type large enough for the step, or leave the list empty for automatic selection. Automatic selection still depends on compatible types being available in your region and AWS having capacity.
Cold starts. The default pool keeps no idle hosts running. A step may wait for a new host after an idle period. Set Idle hosts to keep running to reduce this wait, at the cost of continued compute charges. Persistent pools can wake retained stopped hosts instead.

Introduction

Concepts

Config as code

Migrate

Modules

Pipelines

Guides

Troubleshooting

Agent setup

Module definitions

When to use sandboxes

What runs inside a sandbox

Get started

Pipeline steps

Module builds

Pool settings

Interruptible steps and spot hosts

Disk cache

Limits and caveats

​When to use sandboxes

​What runs inside a sandbox

​Get started

​Pipeline steps

​Module builds

​Pool settings

​Interruptible steps and spot hosts

​Disk cache

​Limits and caveats

When to use sandboxes

What runs inside a sandbox

Get started

Pipeline steps

Module builds

Pool settings

Interruptible steps and spot hosts

Disk cache

Limits and caveats