<aside> 🌍 This page is public. Read about our take on public when possible, private when necessary.


<aside> 👐 Maintained ****by @Christian Weichel. Contribute to this page using following our contributor flow.


This page is meant as a tutorial on/description of Gitpod's architecture.

Basic Concepts

Gitpod is a rather (unfortunately) complex system. One of the primary tasks of engineering is continually strive to reduce this complexity. Things get complicated by themselves, and we have to do our best to keep things under control.

There are a few basic concepts in Gitpod that are found throughout the system and make working with Gitpod easier.

Workspaces and Workspace Instances

At the very heart of Gitpod are workspaces. Everything else is addendum built around them. Workspaces are the encapsulated environments in which work happens. This work can either be users (regular workspaces) or be done by a machine (headless workspaces).

Each workspace gets created exactly once from a workspace context. Such workspace context can come from a context URL e.g. a user opens gitpod.io/#github.com/gitpod-io/gitpod, but also from other sources, e.g. prebuilds. During workspace creation we download the workspace configuration from the context and store it in the database; if there's no config we use a default. The config contains e.g. the workspace image one wants to use, or the tasks that are to be executed.

Untitled 1.png

Whenever a workspace is started we create a workspace instance for that workspace. A workspace instance contains more runtime-related information, e.g. which cluster it runs on.

<aside> 💡 A workspace can have exactly zero or one running workspace instance at any given time.


Lifecycle and Phases

Once a workspace is created, and we've started an instance that instance goes through a fixed lifecycle which is separated into different phases.

// WorkspaceInstancePhase describes a high-level state of a workspace instance
export type WorkspaceInstancePhase =
    // unknown indicates an issue within the system in that it cannot determine the actual phase of
    // a workspace. This phase is usually accompanied by an error.
    "unknown" |

    // Preparing means that we haven't actually started the workspace instance just yet, but rather
    // are still preparing for launch. This means we're building the Docker image for the workspace.
    "preparing" |

    // Pending means the workspace does not yet consume resources in the cluster, but rather is looking for
    // some space within the cluster. If for example the cluster needs to scale up to accomodate the
    // workspace, the workspace will be in Pending state until that happened.
    "pending" |

    // Creating means the workspace is currently being created. That includes downloading the images required
    // to run the workspace over the network. The time spent in this phase varies widely and depends on the current
    // network speed, image size and cache states.
    "creating" |

    // Initializing is the phase in which the workspace is executing the appropriate workspace initializer (e.g. Git
    // clone or backup download). After this phase one can expect the workspace to either be Running or Failed.
    "initializing" |

    // Running means the workspace is able to actively perform work, either by serving a user through Theia,
    // or as a headless workspace.
    "running" |

    // Interrupted is an exceptional state where the container should be running but is temporarily unavailable.
    // When in this state, we expect it to become running or stopping anytime soon.
    "interrupted" |

    // Stopping means that the workspace is currently shutting down. It could go to stopped every moment.
    "stopping" |

    // Stopped means the workspace ended regularly because it was shut down.

Workspace (instance) types

Within a workspace cluster several types of workspaces exist: