rungp Logo run-gp Run local workspaces using the .gitpod.yml

Gitpod ready-to-code Discord

run-gp is a CLI tool for running workspaces based on a .gitpod.yml file locally on your machine. Using a local working copy it produces a workspace image, and starts that workspace. This provides an experience akin to a regular Gitpod workspace.

Warning This is an experiment. When you find an issue, please report it so that we can improve this project.


  • Image Build: run-gp produces a workspace image based on the image section in the .gitpod.yml. If no such section exists, gitpod/workspace-full:latest is used.
  • Browser Access: by default we’ll start Open VS Code server to provide an experience akin to a regular Gitpod workspace. This means that a run-gp workspace is accessible from your browser.
  • SSH Access: if your user has an SSH key (~/.ssh/ file) present, the run-gp workspace will sport an SSH server with an appropriate entry in authorized_keys. This means that you can just SSH into the run-gp workspace, e.g. from a terminal or using VS Code.
  • ✅ VS Code extension installation: VS Code extensions specified in the .gitpod.yml will be installed when the workspace starts up. Those extensions are downloaded from Open VSX, much like on
  • Tasks configured in the .gitpod.yml will run automatically on startup.
  • Ports configured in the .gitpod.yml will be made available on startup. There is no dynamic port exposure you might expect from a Gitpod workspace.
  • Airgapped startup so that other the image that’s configured for the workspace no external assets need to be downloaded. It’s all in the run-gp binary.
  • Auto-Update which keeps run-gp up to date without you having to worry about it. This can be disabled – see the Config section below.
  • ⚠️ Docker-in-Docker depends on the environment you use run-gp in. It does not work yet on MacOS and when run-gp is used from within a Gitpod workspace.
  • ⚠️ JetBrains Gateway support also depends on the environment run-gp is used in. It is known NOT to work on arm64 MacOS.
  • gp CLI is coming in a future release.
  • Gitpod Prebuilds are unsupported because this tool is completely disconnected from
  • Gitpod Backups are unsupported because this tool is completely disconnected from

Getting Started

  1. Download the latest release
  2. In a terminal, navigate to a directory which has a .gitpod.yml file, e.g. a Git working copy of your repository.
  3. Run run-gp
  4. Once the workspace is ready, open the URL displayed in the terminal.


run-gp does not have a lot of configuration settings, as most thinsg are determined by the .gitpod.yml. You can find the location of the configuration file using

run-gp config path

Auto Update behaviour

By default run-gp will automatically update itself to the latest version. It does that by checking the GitHub releases of the run-gp repository for a new release. To disable this behaviour run:

run-gp config set autoUpdate.enabled false


By default run-gp will send anonymous telemetry. We never send identifiable details such as usernames, URLs or the like. You can review all data ever being transmitted in the sources. To disable telemetry run:

run-gp config set telemetry.enabled false


View Github