auto and let the step size itself. Ravion launches, packs, scales and retires the hosts. On a running host, a sandbox boots in one to two seconds, and the disk cache brings back the whole disk from the last saved run.
How the fleet works
Each execution environment gets its own set of sandbox hosts, in its VPC and subnets. The first step that runs withtype: sandbox sets them up. There’s nothing to provision.
Everything runs in your AWS account. Sandboxes can reach private resources in the VPC, and saved disks stay in an S3 bucket in your account. Hosts connect out to Ravion, so they need no inbound ports.
One host runs many sandboxes at once. Each sandbox is a separate VM with its own kernel, network namespace, CPU, memory and disk.
- Placement. Ravion puts a step on a running host with room, preferring the host that last ran it, since that host already has its disk cached.
- Scale up. When no host has room, Ravion launches one sized for the waiting steps. When a pipeline run starts, Ravion plans hosts for the whole run up front, so later steps don’t wait for a launch.
- Spot. Interruptible steps can run on Spot hosts. Other steps only run on On-Demand hosts.
- Scale down. Ravion shuts down a host once it’s empty. If the remaining hosts don’t have room for what’s coming next, it waits 40 seconds first. Running steps always finish.
Host lifecycle
Hosts are disposable. Saved disks live in an S3 bucket in your AWS account, so you lose no cache when a host goes away. The next host restores the disk from S3.
For faster starts after quiet periods, you can keep a few hosts on hand: running in ephemeral mode, or stopped in persistent mode. See Sandbox settings.
Why sandboxes are fast
A cold CI job spends much of its time getting back to where the last one was: installing tools, restoring caches and pulling Docker layers. A sandbox skips that. It boots in one to two seconds with the whole disk from the last saved run already attached.The whole disk is the cache
Whendisk_cache is on, Ravion saves the sandbox’s entire root disk when a step succeeds or one of its commands fails. You don’t list cache paths. Everything the step left behind comes back next time:
- Packages installed with
apt,setupactions or install scripts node_modules,~/.cache,~/.m2, Go and Cargo build caches,.next/cache,.turbo- Docker images, layer cache and BuildKit
RUN --mount=type=cachedirectories in/var/lib/docker - Your git checkout, so the next clone only fetches new commits
Restores stream instead of downloading
A saved disk is stored as 2 MiB chunks, zstd-compressed and named by their content hash. A restore doesn’t download the disk first:- The sandbox boots right away with the full disk attached. Its writes go to its own copy-on-write layer.
- When the sandbox reads a block, the host serves it from its local NVMe cache. On a miss, it fetches only that chunk from S3 and checks it against its hash.
- In the background, the host prefetches the chunks the previous run read, in the order it read them.
Saves upload only what changed
While the step runs, the host uploads changed chunks in the background. When the step succeeds or one of its commands fails, only the remaining chunks are left to upload. Ravion does not save a disk when a step is cancelled, times out, runs out of disk, or loses its host. Unchanged chunks are never uploaded again, and empty chunks cost nothing.The VM runs at host speed
Each sandbox’s memory is backed by 2 MiB huge pages, and the guest kernel is tuned to avoid costly exits to the hypervisor. CPU- and memory-heavy work such as compiling and package installs runs close to bare-host speed. On instance types with local NVMe, the sandbox disks and chunk cache use it instead of EBS.Compared with other CI caches
With path-based caches, anything you don’t list starts over on every run, including system packages, toolchains and files outside those paths. A sandbox keeps everything.
Why sandboxes are cheap
Hosts run in your AWS account, so you pay AWS directly at your own rates. Ravion keeps that bill low:- Spot for interruptible steps. Spot capacity costs much less than On-Demand. Interruptible steps run on Spot, with On-Demand as the fallback. If AWS reclaims a Spot host in its first hour, AWS doesn’t charge for that host’s usage, and Ravion reruns the step on another host.
- Many sandboxes per host. Each step gets exactly the CPU and memory it asks for, on a shared host, instead of a whole instance per job.
- Whole-run planning. When a pipeline run starts, Ravion estimates each step’s duration from its recent successful runs. It packs short steps beside long ones, holds room for the steps due next, and launches hosts only for work that won’t fit. Hosts stay busy, and steps don’t wait for capacity.
- No idle hosts. Ravion shuts down empty hosts as soon as the rest of the fleet can handle what’s next. By default, nothing runs between pipeline runs.
When to use sandboxes
Use sandboxes for pipeline steps and module builds by default, including builds, tests, migrations and other scripted tasks. Useec2 or ec2-spot infrastructure only when you need a custom AMI or a dedicated EC2 instance. See EC2 runners for what those images include.
What runs inside a sandbox
Every sandbox boots the same x86_64 Ubuntu 24.04 image. It has the apt packages GitHub’subuntu-24.04 runner image installs, such as git and Git LFS, build-essential, Clang 18 (clang-18, lld-18, lldb-18, clang-format-18 and clang-tidy-18), zip, rsync, wget, brotli, sqlite3 and the PostgreSQL client. It also has GitHub CLI (gh), Node.js 24, Docker with Docker Compose, the AWS CLI, jq, yq, ccache, sccache and Bazelisk (as bazel). Like GitHub’s images, apt-get install doesn’t ask for confirmation.
The image is still much smaller than GitHub’s hosted runner images. Their ubuntu-latest also comes with several versions each of Node.js, Python, Java, Go, Ruby and .NET, plus browsers, databases and cloud tools. The sandbox image doesn’t. If a step needs something missing, install it natively:
- System packages with
apt-get, for exampleapt-get update && apt-get install -y python3-pip. Steps run as root. - Language versions with the usual
setup-*actions in GitHub Actions jobs, or with version managers and install scripts in pipeline steps. - Anything else by downloading its binary or installer in a command.
disk_cache on, what you install usually stays for later runs — only runs that can write the cache save their disk. See Disk cache.
Docker starts in the background when the sandbox boots, and 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
1
Update your AWS permissions
Sandboxes require AWS account role policy 1.0.52 or later.
- Go to Settings / AWS accounts and open the account.
- Click Update AWS Permissions and follow the steps to update the CloudFormation stack.
ravion aws account policy-diff <aws-account-id> to review the change. Then apply it with aws cloudformation update-stack and a template URL from ravion aws account cloudformation-template-url <aws-account-id>.2
Update modules with a build step
This applies to module builds only. Modules that build your code, such as
rvn-ecs-web, rvn-lambda or rvn-aws-static, need a version released on or after October 10, 2026; older versions only build on EC2. Modules without a build step, such as rvn-stack, need no update, and pipeline steps run in sandboxes regardless of module versions.3
Run pipeline steps or module builds in sandboxes
Set pipeline steps to
type: sandbox. New module builds use sandboxes by default; switch existing modules that still use EC2.Pipeline steps
Set the step’sinfrastructure.type to sandbox. Any step with an infrastructure block can run in a sandbox, including custom, build:image and build:static.
Replace ci-builders with the ID or given ID of your execution environment. To create one, go to Settings / Execution environments.
Sandboxes don’t take
instance_size, ami or storage. See SandboxStepInfrastructure for the full schema.
Automatic sizing
Automatic sizing is in preview. Contact support to share feedback.
cpu, memory or disk to auto and Ravion sizes the sandbox from the step’s earlier runs. These work with or without interruptible: true.
- Automatic sizing starts at 4 vCPU, 16 GiB memory and 40 GiB disk. Fixed values stay fixed.
- Every run teaches Ravion what the step needs. Sizes grow fast when a step needs more, come down gradually when it needs less, then settle. Sizes are learned per pipeline step and execution environment.
- For interruptible steps, Ravion can test smaller sizes. If a step runs out of memory or disk, Ravion gives it more and retries it in the same pipeline run, up to twice per step. The step’s log shows each retry.
- If Java (
java.lang.OutOfMemoryError: Java heap space) or Node (JavaScript heap out of memory) runs out of heap, check whether your command sets a heap limit with-Xmx(Java) or--max-old-space-size(Node). Raise that limit if needed. Interruptible steps can also get more memory and retry automatically.
interruptible off:
Module builds
New module builds use sandboxes by default. See Build infrastructure to configure builds or switch an existing module from EC2.Sandbox settings
Go to Settings / Execution environments, choose the environment, then open Config / Sandboxes.
To stop using sandboxes, switch your steps and module builds back to EC2. Running
ravion execution-environment update <id> --sandboxes null removes the hosts, but the next sandbox step sets them up again.
Track cost and hosts
Go to Settings / Execution environments and choose the environment. Usage shows what the environment cost in a billing period, or any date range up to 93 days. It covers pipeline steps, module builds and GitHub Actions jobs, on sandboxes and EC2:- Cost: a daily chart and totals for compute, disk and storage, network, and Ravion pipeline minutes. AWS amounts are estimates.
- Time to start: median and p95 time spent waiting for capacity and starting the sandbox or runner.
- By pipeline: step runs, minutes, AWS cost and Ravion cost for each pipeline. Expand a pipeline to see its steps. GitHub Actions jobs are under GitHub Actions Runner, by repository and then workflow.
- By instance type: hours, compute cost and Spot savings for each EC2 instance type.
ravion execution-environment sandbox-hosts <id>.
Interruptible steps and spot hosts
interruptible: true means a step can be stopped partway and started over. Builds, tests and lint usually can.
- Interruptible steps can run on Spot hosts, or on spare room on On-Demand hosts. Ravion tries several Spot instance types and Availability Zones, then falls back to On-Demand.
- If an interruptible step loses its host, Ravion reruns it from the start on another host. The last retry always runs On-Demand.
- If a step that isn’t interruptible loses its host, the step fails.
interruptible off for steps with side effects that aren’t safe to repeat, such as database migrations and deploys.
Choose a region
Spot is where most of the savings come from. Each Availability Zone that offers the sandbox instance types (c8id, m8id, r8id, i7i and i7ie) is another Spot pool for Ravion to try before falling back to On-Demand. A region with more of these zones is more likely to find Spot capacity.
These regions offer every sandbox instance type. They’re ordered by how many Availability Zones offer those types, then by price:
Other regions offer fewer sandbox types. For example,
eu-west-1 and eu-west-2 have no c8id, and most other regions only have i7i and i7ie.
Choose for Spot capacity first, not for where your team is. CI jobs mostly talk to GitHub and package registries, and an extra region hop barely changes job time.
Pick a region close to your data instead when:
- Jobs move a lot of data to AWS resources in another region. For example, pushing images to ECR, or reading from S3 buckets or test databases. AWS charges for data transfer between regions, about $0.01 to $0.02 per GB between US regions, and each request takes longer.
- Your GitHub is hosted in another region, such as GitHub Enterprise Cloud with data residency in the EU, Australia or Japan.
- Compliance rules require builds to stay in a region.
Disk cache
disk_cache controls whether a sandbox keeps its disk between runs. See Why sandboxes are fast for how it works.
A run restores the disk saved for its branch. If there’s none, it uses the pull request’s base branch, then the repository’s default branch. A step saves its disk to its own branch when it succeeds or one of its commands fails. It does not save when cancelled, timed out, out of disk, or when its host is lost.
To start a run on clean disks, pass
--no-cache to ravion pipeline run create or ravion pipeline run retry.
Delete cached state
To remove cached state after a compromised dependency or a bad build, open Settings / Execution environments, select the environment, then open Config / Cache. Choose an option from the Delete cache button and confirm:- Delete cache pauses new sandbox jobs and lets running jobs finish before clearing their caches.
- Kill all jobs & delete cache stops running jobs in this execution environment before clearing their caches.
Shared build cache for pipeline steps
Private pipeline sandbox steps with a git source automatically use a shared build cache, independently ofdisk_cache. Ravion configures Go builds through GOCACHEPROG. If you already use sccache, Rust builds use the shared cache through SCCACHE_WEBDAV_ENDPOINT. Turborepo uses it as its remote cache through TURBO_API and TURBO_TOKEN. Bazel builds, tests and runs use it as their remote cache unless your workspace sets its own remote cache or remote executor.
Ravion scopes cache entries to the repository and branch, and reads from the repository’s default branch when the branch has no entry. Pipeline steps share entries with that repository’s GitHub Actions jobs.
Your own GOCACHEPROG, sccache, TURBO_* or Bazel remote settings take precedence. To turn off one of these caches for a step, set RAVION_GO_CACHE_PROG=off, RAVION_SCCACHE=off, RAVION_TURBO_CACHE=off or RAVION_BAZEL_CACHE=off in its environment. The shared build cache does not apply inside container instructions or Docker builds.
Limits and caveats
- CPU limit. Each sandbox supports up to 32 vCPUs because of Firecracker’s per-microVM limit. This applies to both fixed CPU values and automatic sizing. Larger hosts can run multiple sandboxes, but cannot give a single sandbox more than 32 vCPUs.
- Account and region targets. With
aws_account_idandregion, Ravion uses that account and region’s execution environment, and creates one in the default VPC if none exists. Useexecution_environment_idto choose the network. - Step size. A step’s
cpu,memoryanddiskmust fit an instance type available in your region. If you restrict Machine types, include one large enough. - Cold starts. With no reserve, a step after an idle period waits for a new host to launch. Keep idle hosts running, or use persistent hosts, to shorten the wait.