How to Install the Local Preview of Gitpod Self-Hosted

Intended for: The Local Preview allows you to experience Gitpod Self-Hosted on your local machine without having to set up a Kubernetes cluster. It is purely intended for testing purposes. Please see getting started guide for recommended sustainable installation methods.
Limitations: - Performance is bound by the capabilities of your machine. Your experience is likely to be better when using the SaaS version ( or when running on one of our reference architectures
- Minimum of 4 cores and 6GB of ram required. Macs with Apple Silicon (e.g. M1) are currently not supported. See the relevant issue for more information
- Prebuilds are not supported because they require webhooks
- Local Preview is currently in alpha

The Local Preview of Gitpod Self-Hosted is the easiest way to try out Gitpod locally in situations where you cannot use the SaaS version ( and cannot easily spin up a Kubernetes cluster to use the Proof-of-Value reference architecture (coming soon). It allows you to try Gitpod Self-Hosted locally with minimal effort and resource requirements. As a result, this is not intended for production nor continuous usage. Please refer to the Getting Started page for instructions on how to install Gitpod for continuous usage.

This install method runs a K3s cluster inside a Docker container. Self-signed certificates are automatically created and a Gitpod instance using these certificates will be installed into the k3s cluster. See our TLS page for more information about Gitpod and certificates.

1. Running the Docker container

Run the following command to get the local-preview Docker container up and running:

language icon language: 
docker run -p 443:443 --privileged --name gitpod --rm -it  --mount type=volume,source=gitpod,destination=/var/gitpod

Unpacking the above command:

  • -p 443:443 to map the 443 container port to host.
  • --privileged to be able to run docker (and hence k3s) inside the container. This is necessary.
  • --name gitpod to set the name of the docker container for further access.
  • --rm to delete the Docker container after stopping.
  • --mount type=volume,source=gitpod,destination=/var/gitpod to create a volume called gitpod, and mounting it to the container.

Note: By default, is the DOMAIN to access Gitpod which routes to localhost IP address. To use another host network IP Address, the DOMAIN environment can be set accordingly via an -e flag in the above command. This is useful to share access to the Gitpod Self-Hosted instance running on your machine within your local network. For Example, Host Network IP would be, set by appending -e

2. Accessing Gitpod

As this is a self-signed instance of Gitpod, the Gitpod root CA cert has to be imported into your browser manually to access the full functionality of Gitpod. The certificate can be retrieved by running the following:

language icon language: 
docker cp gitpod:/var/gitpod/gitpod-ca.crt $HOME/gitpod-ca.crt

This certificate is saved at $HOME/gitpod-ca.crt and can then be loaded into your browser. Most browsers also require a restart before they can start to use the imported certificate. For instructions on how to load the certificate, choose your setup below:

Chrome on Windows
Edge on Windows
Firefox on Windows
Google Chrome on MacOS
Mozilla Firefox on MacOS

Once the certificate is loaded, the URL to access the Gitpod instance would be unless the DOMAIN environment is overridden in which case the same has to be used.

You should be greeted by the following screen:

welcome screen

You will then be asked to configure a git integration:

git integration setup

This git integration will also serve as the way that you and your users get authenticated against your Gitpod installation. You can find out more in the Integrations section.

Important: Public (SaaS) Source Control Management Systems (SCMs) (i.e., and are not integrated by default with a Self-Hosted Gitpod instance because OAuth apps are tied to domains. Therefore, these public SCMs need to be integrated manually with an OAuth application you specifically create for your domain. This is done similarly to how it is done for the private/self-hosted versions of each SCM. As such their respective guides also apply here:

  • Follow these steps to integrate with your self-hosted Gitpod instance. You will need to enter as the Provider Host Name in the New Git Integration Modal.
  • Follow these steps to integrate with your self-hosted Gitpod instance. You will need to enter as the Provider Host Name in the New Git Integration Modal.
  • Follow these steps to integrate with your self-hosted Gitpod instance. Select Bitbucket as the Provider Type in the New Git Integration Modal. For this requires configuring an “OAuth consumer” on a “workspace”. This is slightly different from the documented Bitbucket Server integration. See gitpod PR #9894 for an example.

Note: Your first workspace start can take a bit of time because the workspace image first needs to be built and then downloaded. Subsequent workspace starts should be much quicker.

Once you are all set up, you can visit the getting started with Gitpod page to start learning about using Gitpod.

Was this helpful?