Gitpod brings a new way to think about your development environment. Rather than a single local environment that you keep up-to-date, with Gitpod you can have as many workspaces as you need. Workspaces are ephemeral by design, which means they are temporary and designed to be disposable. When a Workspace is stopped, content on /workspace directory gets backed up and the container and contents are removed. When you restart a workspace, the content of /workspace is restored to a new ephemeral container. It’s also important to consider the workspace deletion behaviour.

Workspace Lifecycle

​
Workspace Statuses

The state of the workspace is indicated by the color of the workspace indicator. For example, in the Gitpod dashboard, workspace state is shown on the workspace list.
  1. 🟠 Starting - Workspace provisioning, inaccessible to the user.
  2. 🟢 Running - Workspace loaded, accessible to the user.
  3. 🟠 Stopping - Workspace being stopped, backup is being taken.
  4. 🔴 Stopped - Workspace no longer accessible. File system preserved for restart.
  • Only files in the /workspace directory are kept between state transitions.
  • Any changes made to /workspace from a custom Dockerfile will be overwritten/overlaid by a mount.
The following describes each workspace status in detail, including what can cause a workspace to transition from one status to another.

​
Workspace Starting

When you open a workspace, it will be in the “starting” state. This means that the workspace is being created and the initialization process is running.
  • Where a workspace is being provisioned and initialized.
  • If configured and available, a prebuild snapshot is used.
  • Otherwise, source control is downloaded into the workspace.
In the open dashboard modal, this state can be shown as:
  • Preparing: The system is preparing for the workspace start and transferring the necessary data to the workspace cluster.
  • Building: The system is building a Docker image for the workspace.
  • Pending: Looking for available resources and scaling up workspace resources if needed.
  • Creating: The workspace is being created, including downloading the image.
  • Initializing: The workspace is being initialized.

​
Workspace Running

  • An active workspace is provisioned within Gitpod.
  • The workspace can be accessed by the user.

​
Workspace Stopped

  • No provisioned workspace is running (e.g. ports and URLs are not accessible).
  • Only files and directories inside /workspace are preserved.
  • If the workspace is restarted, the URL is preserved.
  • A start is required before the workspace can be used.

​
Workspace Deleted

Workspaces are deleted after 14 days. Pinned workspaces are never deleted automatically. After being soft-deleted, the workspace is kept in a state that allows administrators to restore the workspace if needed for an additional 21 days.
For workspaces with dirty git working trees (like a repository with uncommitted or unpushed changes), the workspace deletion is postponed and the workspace will be deleted after 28 days after they’re last stopped.

​
Workspace Actions

​
Workspace Pinning

A pinned workspace is never deleted. You can pin a workspace from your workspace list in the Gitpod dashboard.

​
Workspace Snapshotting

You can create a snapshot of a workspace to save its state. This is useful if you want to keep a workspace around for a longer period of time, than the default. Read more about Snapshots.

​
Workspace Deletion

Stopped workspaces are automatically deleted 14 days since the last workspace start. Pinned workspaces are never deleted. You can pin a workspace from your workspace list in the Gitpod dashboard. Workspace deletion behavior:
  1. 14 days after the last active date (or after manually deleting the workspace) -> soft deleted state (users can’t view them in the UI, but it allows administrators to restore the workspace if needed)
    • This changes to 28 days if there are uncommitted changes in the workspace
  2. 21 days after soft deleted state -> Full deletion of workspace and its contents
  3. 365 days after full deletion -> delete internal db records of workspace

​
Workspace Timeouts

Running workspaces stop automatically after a period of inactivity.

​
Workspace Inactivity

By default, workspaces stop following 30 minutes without user input (e.g. keystrokes or terminal input commands). You can increase the workspace timeout up to a maximum of 24 hours.

​
Extend Inactivity Timeouts

Free plan users cannot update their default workspace inactivity timeout (see pricing).
Current workspace - You can extend the inactivity timeout of their current workspace using the gp timeout set command from the Workspaces CLI (installed in all gitpod workspaces by default), through the Command Palette in VS Code, or the Backend Control Center in JetBrains Gateway. Extending the workspace inactivity timeout only applies to the currently running workspace. Default - You can set a default workspace inactivity timeout for all new workspaces opened via the preferences page. The timeout default cannot currently be set by an organization owner.

​
Workspace lifetime

Workspace have a maximum lifetime. This means that workspaces will be shut down after this period even if the inactivity timeout has not been reached yet. Currently the lifetime of a workspace if you are a free plan user is 8 hours and 36 hours if you are on a paid plan.

​
Editor or IDE Disconnect

All inactivity timeouts are dependent on an active editor or IDE connection. Closing your Gitpod connected editor or IDE will reduce the workspace timeout to 5 minutes unless an explicit workspace inactivity timeout is set via user preference, or via the Gitpod CLI.

​
Timeout Examples

Example Scenarios + Outcome (how long the workspace keeps running):
  • Default: 60 minutes, Override: 45 minutes
    • Closing IDE tab: 45 minutes
    • Inactivity with IDE tab still open: 45 minutes
  • Default: 60 minutes (no override)
    • Closing IDE tab: 5 minutes
    • Inactivity with IDE tab still open: 60 minutes