Skip to main content

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.

Requires Core plan or higher.
The Dev Container image cache stores built Dev Container images in the runner’s container registry. Environments with identical Dev Container configurations can reuse a cached image instead of rebuilding it from scratch, reducing startup time from minutes to seconds. Ona Cloud includes image caching by default. For runners in your own cloud account, Ona stores cached images in the runner’s native registry: Amazon ECR for AWS runners and Google Artifact Registry for GCP runners.

​
How it works

  1. Hash computation: When starting an environment, Ona computes a hash from the Dev Container configuration, including:
    • Contents of devcontainer.json
    • Contents of any referenced Dockerfile
    • Digest of any existing container image referenced directly in devcontainer.json
  2. Cache lookup: Ona checks whether an image with this hash already exists:
    • If found, Ona pulls and uses the cached image
    • If not found, Ona builds a new image, pushes it to the cache, then uses it
  3. Shared caching: The cache is shared across all users within a project. The first team member who starts an environment with a new Dev Container configuration builds and caches the image. Later environments in the same project with the same configuration use the shared cached image.
When rebuilding an existing environment’s Dev Container, Ona tries to pull from the cache but does not push new cached images. Only the initial Dev Container build when an environment is created can push to the cache.
Non-project environments, such as environments started directly from a context URL, do not use the cache.

​
Enable or disable the cache

For supported runners, configure the cache in runner settings:
  1. Go to Settings -> Runners in your Ona organization
  2. Select your runner
  3. Toggle Dev container image cache
  4. Click Save
Disabling the cache prevents new images from being cached and stops existing environments from pulling from the cache on rebuild. Existing cached images remain in the provider registry until they expire after 30 days or are manually deleted.

​
What gets cached

The cache includes the built image from a devcontainer build of your configuration:
  • Base image layers: Your specified base image and any modifications
  • Dev container features: Configured Dev Container features
  • Build steps: RUN, COPY, and other Dockerfile instructions
  • Tool installations: Package managers, development tools, and dependencies installed during the build
The cache does not include:
  • Lifecycle hooks such as onCreateCommand, which run after the environment starts
  • User-specific configuration applied at runtime
  • Files that change after container creation

​
Cache invalidation

A new image is built and cached when:
  • The Dev Container configuration hash changes
  • devcontainer.json changes
  • A referenced Dockerfile changes
  • The digest of an image referenced directly in devcontainer.json changes
  • The cached image expires
  • The cached image is manually deleted from the provider registry
When devcontainer.json directly references an existing image, Ona includes the image digest in the cache key: 
{
  "image": "mcr.microsoft.com/devcontainers/typescript-node:0-18"
}
If the image maintainer publishes a new digest for the referenced tag, Ona invalidates the cache and builds a new cached image. When devcontainer.json builds from a Dockerfile, Ona tracks the Dockerfile contents. Base images referenced in FROM instructions are not monitored directly, so change the Dockerfile or delete the cached image when you need to force a rebuild for base image updates.

​
Force a new image build

To force rebuilding and re-caching an image, change the configuration hash or delete the cached image from the provider registry.

​
Modify Dev Container configuration

Add or modify content in devcontainer.json: 
{
  "name": "My Dev Container",
  "image": "mcr.microsoft.com/devcontainers/typescript-node:0-18",
  "features": {
    "ghcr.io/devcontainers/features/git:1": {}
  }
}

​
Modify the Dockerfile

If your Dev Container builds from a Dockerfile, change the Dockerfile: 
FROM node:18
# Force rebuild: 2026-06-01
RUN npm install -g typescript

​
Delete the provider registry image

Delete the cached image tag from the AWS ECR or Google Artifact Registry repository for the project. The next environment creation rebuilds and caches the image.

​
Supported configurations

Supported:
  • Standard Dev Container configurations with a Dockerfile or direct image reference
  • Dev Container features from any registry
  • Ona Cloud
  • AWS runners
  • GCP runners
Not supported:
  • Docker Compose-based Dev Containers
  • Non-project environments, such as environments started directly from a context URL

​
Monitoring

Cache hits are logged during environment creation: 
Using pre-built dev container (saved ~3m45s build time)

​
Security model

The Dev Container image cache is project-scoped:
  • Project isolation: Cached images are only available to environments in the same project
  • Hash-based reuse: Images are reused only for matching Dev Container configurations
  • Limited push access: Push credentials are granted only during the initial environment build
  • Pull-only refreshes: Existing environments receive refreshed pull credentials, not push credentials
  • Temporary credentials: Registry credentials are short-lived and scoped to the project cache repository
Because cached images are shared across project members, do not write user-specific credentials or personal secrets into image layers. Use organization secrets or project secrets with build-time secret mounts when the build needs credentials.

​
Provider details

​
Ona Cloud

Ona Cloud includes Dev Container image caching by default. Ona manages the backing registry, lifecycle policy, and credentials.

​
AWS runners

AWS runners store cached images in Amazon ECR in your AWS account. Cached image repositories use this naming pattern: 
gitpod-runner-{runnerID}/projects/{projectID}/image-build
For existing AWS runners, upgrade the CloudFormation stack before enabling the cache:
  1. Upgrade your CloudFormation stack to a version that supports the cache
  2. Go to Settings -> Runners in your Ona organization
  3. Select your AWS runner
  4. Toggle Dev container image cache
  5. Click Save
Upgrading CloudFormation templates that were applied from January 2025 or earlier will cause existing environments to no longer be accessible due to SSH port changes. Before upgrading, either stop and discard existing environments, or manually update the security group to allow access from 0.0.0.0/0 to port 22, in addition to port 29222, after upgrading the stack.
AWS runner configuration panel showing Dev container image cache toggle option AWS storage and access details:
  • Images are stored in Amazon ECR in the same AWS region as the runner
  • ECR repositories inherit tags from the CloudFormation stack for cost allocation
  • Repository tags are immutable
  • Images expire after 30 days
  • Registry access uses AWS IAM temporary credentials
To force a rebuild by deleting the cached image, delete the image tag from the runner’s ECR repository. The next environment creation with the same Dev Container configuration rebuilds and caches the image.

​
GCP runners

GCP runners store cached images in Google Artifact Registry in your Google Cloud project. Cached image repositories use this naming pattern: 
{region}-docker.pkg.dev/{gcpProjectID}/gitpod-cache-{runnerID}/projects/{projectID}/image-build
The GCP runner Terraform module grants the required Artifact Registry permissions. When cache credentials are built, the runner creates or validates the gitpod-cache-{runnerID} repository in Artifact Registry. The same Dev container image cache runner setting controls whether project environments receive cache registry credentials. GCP storage and access details:
  • Images are stored in Artifact Registry
  • The Artifact Registry repository uses Docker format
  • Repository tags are immutable
  • Images expire after 30 days
  • Registry access uses temporary Google Cloud access tokens
To force a rebuild by deleting the cached image, delete the image tag from the runner’s Artifact Registry repository. The next environment creation with the same Dev Container configuration rebuilds and caches the image.

​
Troubleshooting

If images are not being cached:
  1. Check runner configuration: Ensure the Dev Container image cache is enabled in runner settings
  2. Check the environment type: Non-project environments do not use the cache
  3. Check provider infrastructure: For AWS, verify the CloudFormation stack version and ECR permissions. For GCP, verify Terraform-managed Artifact Registry permissions
  4. Check runner logs: Look for cache-related errors in CloudWatch for AWS runners or Cloud Logging for GCP runners
  5. Review environment logs: Look for cache-related error messages
  6. Check image digest warnings: If using the image field, look for digest lookup warnings that might indicate network or authentication issues with base image registries
If environments are still slow to start:
  1. Check cache hit logs: Look for “Using pre-built dev container” in environment logs
  2. Check image size: Large images take longer to pull
  3. Check Dev Container mode: Docker Compose-based Dev Containers are not supported by the cache
  4. Review lifecycle hooks: Lifecycle hooks such as onCreateCommand are not cached and may install tools that increase startup time. Move stable setup steps into the Docker build where possible
  5. Verify project-based environment: Non-project environments do not use the cache