Skip to main content
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 entire Dev Container filesystem. When you create a new environment from a project with prebuilds, it starts from this snapshot, skipping the time-consuming setup steps.

​
Using Prebuilds

When you create an environment, Ona automatically uses a prebuild if one is available. The selection uses a best-effort approach:
  • Matches your environment class (CPU, memory, storage)
  • Uses the most recent successful prebuild
  • Prebuilds are deleted after 7 days
If no matching prebuild is available, your environment starts normally without one.

​
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

​
What Gets Included in the Snapshot

The prebuild snapshot captures the entire Dev Container filesystem, including:
  • Installed dependencies and packages
  • Built artifacts and compiled code
  • Downloaded assets and data
  • File system changes made during prebuild execution
  • All files in the container (not limited to specific directories)
This means everything in your Dev Container is preserved in the snapshot, providing a complete ready-to-use environment.

​
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

Timeout TypeDefaultRangeDescription
Prebuild execution1 hour5 minutes - 2 hoursTime allowed for running the environment with Dev Container build/lifecycle commands and automation prebuild tasks (configurable per project)
Snapshotting1 hourFixedTime allowed for creating the snapshot after prebuild execution completes
Overall timeout3 hoursFixedCatch-all timeout for the entire prebuild process, including environment creation, command execution, and snapshotting
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

​
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