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. 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 7 days inactive): Storage persists, can be unarchived
  • Deleted environment: Storage is permanently removed
See Archive & Auto-delete for details on automatic archival and deletion policies.

​
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.