https://github.com/gitpod-io/run-gp

Run a local workspace using the .gitpod.yml
https://github.com/gitpod-io/run-gp

Last synced: about 1 year ago
JSON representation

Run a local workspace using the .gitpod.yml

• Host: GitHub
• URL: https://github.com/gitpod-io/run-gp
• Owner: gitpod-io
• License: agpl-3.0
• Created: 2022-06-15T10:26:27.000Z (about 4 years ago)
• Default Branch: main
• Last Pushed: 2024-06-09T03:56:26.000Z (about 2 years ago)
• Last Synced: 2025-03-29T11:34:34.606Z (about 1 year ago)
• Language: Go
• Size: 81.8 MB
• Stars: 52
• Watchers: 9
• Forks: 8
• Open Issues: 12
• Metadata Files:
  • Readme: README.md
  • License: LICENSE

Awesome Lists containing this project

README

          


  

    

    


    run-gp

  

  


  Run local workspaces using the .gitpod.yml





  

    

  

  

    

  



`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](https://github.com/gitpod-io/run-gp/issues/new?assignees=&labels=&template=bug_report.md&title=) so that we can improve this project.

> **Note**

> `run-gp` is **not the "real Gitpod experience"**. Gitpod offers remote development environments which sport many benefits compared to running things locally. Head over to https://www.gitpod.io to find out more.

## Features

- ✅ **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](https://github.com/gitpod-io/openvscode-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/id_rsa.pub` 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](https://open-vsx.org), much like on gitpod.io.

- ✅ **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.io](https://gitpod.io).

- ❌ **Gitpod Backups** are unsupported because this tool is completely disconnected from [gitpod.io](https://gitpod.io).

## Getting Started



  


    Download the [latest release](https://github.com/gitpod-io/run-gp/releases/latest). 

    

      If you're on MacOS you'll need to jump through hoops because the run-gp releases are not signed.

      MacOS requires that binaries downloaded using a browser must be [signed and notarized](https://developer.apple.com/developer-id/). Otherwise you won't be able to just execute the `run-gp` command. If you download the release using `curl` in a terminal, MacOS will just let you execute the binary. Alternatively, you can head over to the `Security` system settings and allow the binary to run once MacOS denied this on the first attempt.

    

  

  


  

  In a terminal navigate to a directory containing a `.gitpod.yml` file, e.g. a Git working copy of a repository, then execute `run-gp`.


  ```bash

  git clone https://github.com/gitpod-io/go-gin-app

  cd go-gin-app

  run-gp

  ```

  **Note:** The `run-gp` command will use the current working directory as context. To point it to a different directory, use the `-w` option.

  

  


  Once the workspace is ready, open the URL displayed in the terminal.

  



## Configuration

`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

```bash

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:

```bash

run-gp config set autoUpdate.enabled false

```

### Telemetry

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](https://github.com/gitpod-io/run-gp/blob/main/pkg/telemetry/telemetry.go#L84-L123). To disable telemetry run:

```bash

run-gp config set telemetry.enabled false

```

`run-gp` respects [Console Do Not Track](https://consoledonottrack.com/), i.e. `export DO_NOT_TRACK=1` will also disable telemetry.

## Frequently Asked Questions

- **This readme refers to `run-gp` as experiment. What does that mean?**

  

    This means that `run-gp` is not a polished product. Instead it's an attempt to [ship a 🛹](https://www.gitpod.io/blog/gitpod-core-values#ship-skateboards), i.e. an MVP that explores how local Gitpod-like workspaces would look like. This repository is not backed by a regular product team, but instead a product exploration effort.

- **The performacne on my M1 Mac is terrible, what can I do?** 

    Until the release of [MacOS 13](https://developer.apple.com/documentation/virtualization/running_intel_binaries_in_linux_vms_with_rosetta), Docker Desktop (and any other Linux VM) will be rather slow on arm64 hardware. It's unlikely we'll produce an arm64 version of Gitpod before (if ever) MacOS 13 comes out. Your best chance is to find an x86 machine, or wait for the release of MacOS 13.