> ## Documentation Index
> Fetch the complete documentation index at: https://ona.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Base snapshots for AWS runners

> Understand how Ona uses automatic base snapshots to reduce startup time on Enterprise AWS runners.

<Note>Available on the Enterprise plan. Base snapshots require a supported AWS runner and are rolling out gradually. [Contact sales](https://ona.com/contact/sales) to request access.</Note>

Base snapshots are an automatic startup optimization for environments on AWS runners. Ona builds and refreshes them in the background. Developers and organization administrators do not need to create, schedule, or monitor them.

A base snapshot stores a prepared copy of the organization's [default image](/docs/ona/organizations/policies/default-image), its container image layers, and runner-managed startup assets. A new environment can restore this cached data instead of downloading it again. The workspace, repository, user configuration, and project setup still start fresh.

Organizations with large default images or self-hosted registries with limited pull throughput benefit most because new environments avoid repeatedly pulling and unpacking the image.

## How base snapshots reduce startup time

Ona maintains one base snapshot for each eligible AWS runner in an organization:

1. Ona starts a system-owned build environment on the runner.
2. The build environment pulls the organization default image and prepares shared startup assets.
3. Ona removes environment-specific data and credentials, then stores the prepared data disk as an Amazon EBS snapshot.
4. New environments on the same runner can restore the EBS snapshot as a best-effort cache.

If a project has a compatible [prebuild](/docs/ona/projects/prebuilds), the prebuild takes precedence because it contains project-specific state. Otherwise, Ona uses a compatible base snapshot when one is available.

## Eligibility is automatic

Ona creates base snapshots when all of these conditions are met:

* The organization is on the Enterprise plan and has base snapshots enabled by Ona.
* The environment uses a supported, up-to-date AWS runner with [dual disk](/docs/ona/runners/dual-disk) support.
* The organization has configured a [default image](/docs/ona/organizations/policies/default-image).
* The runner has at least one enabled environment class with a valid data disk size.

Eligibility applies at the organization level. Administrators do not enable individual runners or environments.

## Refreshes and fallback happen in the background

Ona builds the first snapshot after the runner becomes eligible and refreshes it once per day. Every daily refresh creates a new EBS snapshot, even when the default image reference has not changed. This picks up changes behind mutable image tags.

Changing the default image reference also starts a replacement build. The previous compatible snapshot remains available until the replacement succeeds. Ona then deletes the older snapshot.

Base snapshots are a best-effort cache. If no compatible snapshot is available, a lookup or restore fails, or a runner becomes ineligible, environment creation continues through the normal cold-start path. The environment pulls the default image and may take longer to start, but the missing cache does not prevent creation. Ona retries failed background builds without administrator action.

## Private images require organization credentials

If the default image is in a private registry, configure its credentials as an organization-level [container registry secret](/docs/ona/configuration/secrets/container-registry-secret). Base snapshot build environments receive organization registry credentials only. They do not receive project secrets, user secrets, repository contents, or project automations.

For Amazon ECR, you can use runner-native IAM authentication. Create the registry secret at **Settings → Organization → Secrets** and configure the environment role permissions described in [AWS ECR with IAM authentication](/docs/ona/configuration/secrets/container-registry-secret#using-aws-ecr-with-iam-authentication).

## Snapshots remain scoped to their runner

The EBS snapshot remains in the AWS account and region that host the runner. Ona uses it only for environments on that runner. It contains reusable container and startup data, not workspace or user data.

## Usage and AWS costs

Each base snapshot build runs as a background environment. Ona meters the time that it runs as normal environment usage. This includes initial builds, daily refreshes, retries, and replacements after an administrator resets cached image data. System-owned build environments do not count toward per-user running-environment limits.

The underlying compute and storage resources run in your AWS account. AWS bills the EC2 and EBS resources used during a build and the EBS snapshot storage. Ona does not meter base snapshot storage separately. See [AWS runner costs and budgeting](/docs/ona/runners/aws/aws-runner-costs#base-snapshot-costs).

At steady state, Ona keeps one compatible successful base snapshot for each eligible runner. The current and replacement snapshots can coexist during a refresh. Ona deletes the older snapshot after the replacement is ready.

## Administrators normally do not manage base snapshots

Ona monitors snapshot availability and build health. There is no base snapshot status page in the dashboard. Organization administrators only see the **Reset cached image data** action described below.

When troubleshooting, organization administrators can use `gitpod base-snapshot list`, `gitpod base-snapshot get <base-snapshot-id>`, and `gitpod base-snapshot logs <base-snapshot-id>` to inspect snapshots. The command group also provides `create <runner-id>`, `cancel <base-snapshot-id>`, and `delete <base-snapshot-id>...` controls. Run `gitpod base-snapshot --help` for command usage, and use lifecycle controls in coordination with Ona support.

Organization administrators can [reset cached image data](/docs/ona/organizations/policies/default-image#reset-cached-image-data) when stale or incorrect cached data must be removed. Resetting deletes completed base snapshots across the organization's eligible AWS runners. Ona builds replacements automatically, and environments use the cold-start path until replacements are ready.

## FAQ

<Accordion title="Do developers need to know whether a base snapshot was used?">
  No. Base snapshot selection and cold fallback happen during environment creation. The environment has the same fresh workspace and configuration either way.
</Accordion>

<Accordion title="Do base snapshots replace prebuilds or the Dev Container image cache?">
  No. Base snapshots cache organization-wide default-image data for one AWS runner. [Prebuilds](/docs/ona/projects/prebuilds) add project-specific workspace and setup state, while the [Dev Container image cache](/docs/ona/runners/devcontainer-image-cache) caches built Dev Container images. Ona can use these startup optimizations together.
</Accordion>

<Accordion title="Do custom management-plane domains require extra configuration?">
  No. Base snapshot lifecycle operations and the **Reset cached image data** control use your organization's active management-plane domain. Registry image references and credentials do not change when the organization uses a custom domain.
</Accordion>

## Troubleshooting

<Accordion title="Environments keep pulling the default image during startup">
  The runner may not have a usable base snapshot yet. This can happen after first enablement, a default-image change, a cache reset, or a failed refresh. Ona continues with a cold start and builds or retries the snapshot in the background.

  For a private default image, confirm that its container registry credential is an organization secret and that the AWS environment role can pull the image. If cold starts continue beyond the next daily refresh, contact Ona support with the organization and runner names.
</Accordion>