With Tailscale you can automatically and securely connect your Gitpod workspace to other development resources, whether in the cloud or on prem, such as a production database behind your company’s firewall. You can also spin up several Gitpod workspaces that can talk to each other.

Tailscale is built on top of the point-to-point open-source WireGuard protocol which powers an encrypted mesh network or tailnet. At Gitpod we are big fans of their product and recently announced an official partnership with them.


Using Tailscale ssh to a workspace is not supported right now and from requires Tailscale 1.32 or later. If your workspace image was created before 1.32 was available you can force a rebuild without having to update your .gitpod.Dockerfile.

If you’re already using Tailscale, the following steps need to be done (see https://github.com/gitpod-io/demo-tailscale-with-gitpod for a working example):

  1. Install tailscale through a custom .gitpod.Dockerfile by adding the following layer to it.
language icon dockerfile
RUN curl -fsSL https://pkgs.tailscale.com/stable/ubuntu/focal.gpg | sudo apt-key add - \
     && curl -fsSL https://pkgs.tailscale.com/stable/ubuntu/focal.list | sudo tee /etc/apt/sources.list.d/tailscale.list \
     && sudo apt-get update -q \
     && sudo apt-get install -yq tailscale jq \
     && sudo update-alternatives --set ip6tables /usr/sbin/ip6tables-nft
  1. Start tailscale on workspace start and maintain the machine state across workspaces by adding the following tasks to your .gitpod.yml.
language icon yml
    - name: tailscaled
      command: |
          if [ -n "${TAILSCALE_STATE_MYPROJECT}" ]; then
            # restore the tailscale state from gitpod user's env vars
            sudo mkdir -p /var/lib/tailscale
            echo "${TAILSCALE_STATE_MYPROJECT}" | sudo tee /var/lib/tailscale/tailscaled.state > /dev/null
          sudo tailscaled
    - name: tailscale
      command: |
          if [ -n "${TAILSCALE_STATE_MYPROJECT}" ]; then
            sudo -E tailscale up
            sudo -E tailscale up --hostname "gitpod-${GITPOD_GIT_USER_NAME// /-}-$(echo ${GITPOD_WORKSPACE_CONTEXT} | jq -r .repository.name)"
            # store the tailscale state into gitpod user
            gp env TAILSCALE_STATE_MYPROJECT="$(sudo cat /var/lib/tailscale/tailscaled.state)"

This configuration will register a Tailscale node based on the following name scheme: gitpod-{user-name}-{repo-name}. On first workspace start you will get asked to login through the terminal. When this was successful a Tailscale machine state will be stored in your Gitpod’s account. On subsequent starts of workspaces on this project this machine state will be restored.

IF you enable Tailscale’s Magic DNS you get a stable domain for your project’s services that you can reach from any other Tailscale node (e.g. another workspace or your local machine).

Warning: Be aware that starting and connecting multiple workspaces for the same project in parallel results in unreliable network connections.

Was this helpful?