Skip to main content
Ona environments use persistent storage attached to the underlying VM. Everything on disk persists across environment stops and starts.

​
What persists

  • /workspaces/<repository-name> - your cloned repository and any changes
  • /home/gitpod - home directory, shell history, installed tools
  • System packages installed during setup
  • Files created anywhere on the filesystem
Stop an environment, come back later, and continue where you left off.

​
Dev Container rebuilds

Rebuilding your Dev Container recreates most of the filesystem from the image. Your repository at /workspaces/<repository-name> persists via a bind mount - 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 snapshot the entire Dev Container filesystem - installed dependencies, built artifacts, and all files. New environments load from this snapshot instead of running setup from scratch.

​
Storage size

Storage size is configured through environment classes. Each runner type (Ona Cloud, AWS, GCP) provides classes with different disk sizes. Use storage larger than RAM.

​
Storage lifecycle

StateStorage
StoppedPersists - resume anytime
Archived (after 2–7 days inactive, by plan)Persists - can be unarchived
DeletedPermanently removed

​
Troubleshooting: “No space left on device”

Check usage with df -h. On the Free plan, select the Regular environment class (80 GB). The Core plan provides access to larger classes.

​
Ephemeral vs persistent

For agents, the recommended workflow is ephemeral environments - one fresh environment per task for isolation. With prebuilds, starting fresh is fast enough that persistence is not needed. For human developers, persistent environments work well for longer-running tasks where you want to maintain state across sessions.