Gitpod Local Companion - localhost is going remote

Jun 9, 2021

Gitpod Local Companion - localhost is going remote

Avatar of akosyakov Anton Kosyakov Avatar of csweichel Christian Weichel Avatar of rl-gitpod Robert Leftwich

While Gitpod can seamlessly integrate into your workflow in the vast majority of cases, there are times where you may want to access a workspace from localhost and were required to workaround some limitations, particularly with respect to framework features such as live reload.

Gitpod is pleased to announce a preview release of the Gitpod Local Companion app that is designed to allow localhost access to any TCP port in a remote workspace regardless of protocol.

The app runs locally and enables automatically tunneled connections to your workspace, either privately or, if required, publicly (on your laptops IP for example).

In particular, this opens up any environment or framework that assumes localhost access i.e. web frameworks such as Svelte and enables bundlers such as Parcel or Webpack hot reloading without requiring any changes. It also enables the use of non-HTTP protocols, most notably MQTT based brokers or the AMQP based services.

As a preview release, not all of the features are implemented, most notably the tunneling is 1-way only: local -> workspace.

See it in action

As a simple example, with the Gitpod Local Companion app installed and running, open the standard Svelte template in Gitpod, using this link or the Gitpod button directly. This will create an ephemeral environment for you without requiring any local setup or installation. As per the template instructions, run the following:

npm install && npm run dev

VS Code will detect the service on port 5000 and offer 3 options. Click on the ‘Open Browser’ icon or navigate to directly to localhost to see ‘Hello world!‘. Edit app.svelte and the page will live reload with your changes!

We love feedback here at Gitpod, so please give it a try and let us know what you think!


To get started, download the preview release of the Gitpod Local Companion app for your platform (right click, ‘Save (Link) As’)

Alternatively, in a terminal run the following:

  # mac
  curl -OL
  chmod +x ./gitpod-local-companion-*

  # linux
  curl -OL
  chmod +x ./gitpod-local-companion-*

  # windows
  curl -OL


To run it using your local keyring for long term storage of the access token:


To run it without storing the access token (it will generate a new token every time);

  ./gitpod-local-companion-[darwin|linux|windows] --mock-keyring

If you are not logged in to Gitpod, it will take you through that flow. If you haven’t run the local app previously it will also ask you to approve access to the control data of all your workspaces, returning a token that grants the access. This token will be stored in your local keyring for future use (unless you specify otherwise).

Once approval has been granted it will connect to your currently active workspaces and allow VSCode to control the tunnelling between the remote workspace and your local environment using the Remote Explorer Ports View.

Note that it currently requires a reload of the workspace VS Code page if the companion app is started after the workspace is open to synchronize the ports view - this is temporary.

Remote Explorer Ports View

Gitpod has extended the Remote Explorer Ports view to allow more control of how ports are exposed. As shown below there is an additional toggle on each port to switch between Tunnel on localhost exposure i.e. nothing outside of your laptop

tunnel on localhost

and Tunnel on all interfaces to make that port available on and, depending on your firewall settings, to anyone that can access your laptop externally.

tunnel on all

By default it will attempt to tunnel on the same port, but it will pick a random port if the local port is unavailable. This is reflected in the Remote Explorer Ports view below where local port 3000 is tunneled via port 49605:

tunnel on random

SSH Access

Additionally, the Gitpod Local Companion preview release also has basic support for SSH access into your workspace. It currently requires that you have a default SSH key setup in the ~/.ssh directory i.e. & id_rsa. The public key will be copied to the workspace to permit access.

This opens up all the usual SSH-based features, such as secure copying, tunneling and remote execution.

Once you have installed the Gitpod Local Companion app and connected it to your workspaces, it dynamically creates entries for each workspace in the /tmp/gitpod_ssh_config file. You can use this to SSH into your workspace as follows:

ssh -F /tmp/gitpod_ssh_config <your-workspace-id e.g.apricot-harrier-####>

You will be prompted to add the address to your known hosts file and you will be connected to your workspace!

What is next?

We have big plans for the Gitpod Local Companion App! Future features may include:

  • 2-way tunnelling
  • Listing what workspaces are running
  • Listing what ports are currently tunneled and in which direction (workspace to/from local)
  • Starting/stopping port forwarding from the command line
  • Connecting a local VS Code instance to a workspace
  • SSH into a workspace from the command line in a simple, straight forward way

Stay updated

Sign up now for our newsletter.

More articles

Blog post: I said goodbye to local development and so can you

I said goodbye to local development and so can you

Stop maintaining your local development environment. Instead, automate the setup once and use a new environment for each task you work on - available in seconds and always ready-to-code.

Avatar of mikenikles Jun 30, 2021

Blog post: DevX Conf wrap & distributing $10k of open-source funding

DevX Conf wrap & distributing $10k of open-source funding

As part of Gitpod’s Open-Source Sustainability Fund initiative attendees of DevX Conf were able to decide where $10,000 USD of funds (the profits from DevX Conf plus an additional donation by Gitpod) were to be distributed. Here's the breakdown how the fund was split and our retrospective on running our first-ever conference.

Avatar of christinfrohne Avatar of ghuntley Jun 3, 2021

Blog post: Journey to Site Reliability Engineering at Gitpod

Journey to Site Reliability Engineering at Gitpod

The SRE team at Gitpod is making the first moves to implement Site Reliability Engineering best practices. We document our approach to implement our very first Service Level Objective.

Avatar of arthursens May 23, 2021