Skip to main content
Ona environments use persistent storage attached to the underlying VM. Your workspace directory, home folder, installed packages, and any other files persist across environment stops and starts.

​
What persists

Everything on the VM’s disk persists by default:
  • /workspaces/<repository-name> - your cloned repository and any changes
  • /home/gitpod - your home directory, shell history, installed tools
  • System packages installed during setup
  • Files created anywhere on the filesystem
This means you can stop an environment, come back later, and continue where you left off.

​
Dev Container rebuilds

When you rebuild your Dev Container, most of the filesystem is recreated from the image. However, your repository at /workspaces/<repository-name> persists via a bind mount - your code and uncommitted changes remain intact. To persist other directories across rebuilds, add bind mounts in your devcontainer.json: 
{
  "mounts": [
    "source=/workspaces/.cache,target=/home/gitpod/.cache,type=bind"
  ]
}

​
Prebuilds and storage

Prebuilds capture a snapshot of the entire Dev Container filesystem - installed dependencies, built artifacts, and all files. When you start an environment from a prebuild, it loads from this snapshot instead of running setup from scratch. Prebuilds use the same persistent storage model as regular environments.

​
Storage size

Storage size is configured through environment classes. Each runner type (Ona Cloud, AWS, GCP) provides environment classes with different disk sizes. When creating a custom environment class, you specify the disk size alongside the instance type. The recommendation is to use storage larger than RAM.

​
Environment lifecycle

Persistent storage is tied to the environment’s lifecycle:
  • Stopped environment: Storage persists, you can resume later
  • Archived environment (after 2-7 days inactive, depending on plan): Storage persists, can be unarchived
  • Deleted environment: Storage is permanently removed
See Archive & Auto-delete for details on automatic archival and deletion policies.

​
Troubleshooting: “No space left on device”

If you encounter this error (e.g. during yarn install), your environment has run out of disk space. Check usage with df -h. On the Free plan, select the Regular environment class when creating an environment. It provides 80GB of storage. For larger projects, the Core plan offers access to bigger environment classes.

​
Ephemeral vs persistent

While storage persists within an environment, the recommended workflow for agents is ephemeral environments - one fresh environment per task. This provides isolation and avoids state conflicts. With properly configured prebuilds, starting a fresh environment is fast enough that persistence isn’t needed. For human developers, persistent environments can be useful for longer-running work where you want to maintain state across sessions.