Skip to main content
Early AccessPrebuilds are currently in early access. If you’re interested in trying this feature, please contact us.
Prebuilds reduce environment startup times by pre-executing your Dev Container lifecycle commands and automation tasks. Instead of waiting for dependencies to install and build steps to complete every time you create an environment, prebuilds prepare a snapshot that’s ready to use instantly.

​
What are Prebuilds?

A prebuild creates an environment and runs your Dev Container build process, lifecycle hooks (onCreateCommand and updateContentCommand), and automation tasks configured with the prebuild trigger. Once these commands complete successfully, Ona takes a snapshot of the environment. When you create a new environment from a project with prebuilds, it starts from this snapshot, skipping the time-consuming setup steps.

​
What Gets Executed

During prebuild creation, Ona runs:
  • Dev Container build: Builds your Dev Container image from the Dockerfile or docker-compose configuration. Prebuilds make use of and populate the Dev Container image cache, which can significantly speed up subsequent builds.
  • Dev Container lifecycle commands:
    • initializeCommand - Runs before the container is created
    • onCreateCommand - Runs when the container is created for the first time
    • updateContentCommand - Runs when the container is created or updated
  • Automation tasks: Any tasks in your automations.yaml configured with the prebuild trigger. Organization and project secrets are available during these tasks, but user secrets are not.

​
What Doesn’t Run

The following commands are not executed during prebuilds, as they’re intended to run when a user connects to the environment:
  • postCreateCommand - Runs after the container is created
  • postStartCommand - Runs every time the container starts
  • postAttachCommand - Runs when you attach to the container

​
Benefits

  • Faster environment startup: Skip dependency installation and build steps
  • Consistent environments: All team members start from the same pre-configured state
  • Reduced resource usage: Build once, use many times
  • Better developer experience: Get coding immediately without waiting for setup

​
How Prebuilds Work

  1. Trigger: A prebuild is triggered based on your configuration (daily schedule or manual trigger)
  2. Environment creation: Ona creates a temporary environment using your project’s configuration
  3. Command execution: Dev Container lifecycle commands and prebuild automation tasks run
  4. Snapshot creation: Once commands complete, Ona creates a snapshot of the environment
  5. Cleanup: The temporary environment is deleted after successful completion
  6. Usage: When you create a new environment, it starts from the most recent successful prebuild snapshot

​
Prebuild Lifecycle

Prebuilds go through several phases:
  • Pending: Prebuild created, waiting to start
  • Starting: Environment is being created
  • Running: Commands and tasks are executing
  • Stopping: Commands completed, environment is stopping
  • Snapshotting: Creating a snapshot of the environment
  • Completed: Prebuild successful, snapshot available
  • Failed: Prebuild encountered an error

​
Secrets and Authentication

During prebuild execution:
  • Organization secrets: Available to all prebuilds
  • Project secrets: Available to prebuilds for that project
  • User secrets: Not available (prebuilds run without user context)
This ensures prebuilds can access shared credentials while maintaining security boundaries.

​
Prebuild User Context

Prebuilds currently run as a user:
  • Scheduled prebuilds: Run as the user who created the project
  • Manual prebuilds: Run as the user who triggered the prebuild
Note: Service account support for running prebuilds is coming soon, which will allow prebuilds to run with dedicated credentials independent of any user.

​
Timeouts

  • Prebuild execution timeout: Default 1 hour (configurable per project)
    • Minimum: 5 minutes
    • Maximum: 2 hours
    • Applies to running the prebuild environment to completion
  • Overall timeout: 3 hours (fixed)
    • Catch-all timeout for the entire prebuild process
    • Includes environment creation, command execution, and snapshotting
    • Prevents prebuilds from getting stuck indefinitely
If a prebuild exceeds its timeout, it’s marked as failed. Failed prebuild environments remain available for debugging and are cleaned up after 7 days (or earlier based on environment archival settings).

​
Prebuild Retention

  • Prebuilds are automatically deleted after 7 days
  • Only the most recent successful prebuild per environment class is used
  • Failed prebuilds are retained for debugging but don’t affect environment creation

​
Environment Class Matching

When you create an environment, Ona selects the most recent successful prebuild that matches your environment class. This ensures the prebuild was created with the same compute resources (CPU, memory, storage) as your target environment. If no matching prebuild exists, the environment starts normally without a prebuild.

​
Pricing

​
Ona Cloud

  • Environment usage: Standard usage-based billing applies for the time the prebuild environment runs
  • Storage: Prebuild snapshots are currently free (this may change in the future)

​
Enterprise (Your Cloud)

  • Environment usage: You pay for the compute resources used to run the prebuild environment
  • Storage: You pay only for the actual data stored in the prebuild snapshot. For example, if you use 50GB of a 100GB volume, you’re billed for 50GB. Snapshots are stored as volume snapshots in your cloud provider (backed by S3).
For detailed pricing information, see Billing.

​
Runner Availability

Prebuilds are currently available on:
  • AWS Enterprise runners: Fully supported (requires updating your CloudFormation stack to the latest version)
  • Ona Cloud: Fully supported
  • GCP Enterprise runners: Coming soon

​
Limitations

  • Prebuilds are tied to a specific environment class on a runner
  • Only one prebuild per environment class is active at a time
  • Currently only daily scheduling is available (more trigger options coming soon)
  • Prebuilds cannot currently be triggered on every commit (coming soon)
  • Service accounts for running prebuilds are not yet available (coming soon)

​
Next Steps