Tutorial: Connect a remote machine to the Web IDE

Tier: Free, Premium, Ultimate Offering: GitLab.com, Self-managed, GitLab Dedicated
On self-managed GitLab, by default this feature is available. To hide the feature, an administrator can disable the feature flag named vscode_web_ide. On GitLab.com and GitLab Dedicated, this feature is available. This feature is not ready for production use.

This tutorial shows you how to:

  • Create a development environment outside of GitLab.
  • Connect a remote machine to the Web IDE.

To connect a remote machine to the Web IDE, you’ll:

  1. Generate Let’s Encrypt certificates.
  2. Connect a development environment to the Web IDE.


  • A remote virtual machine with root access
  • A domain address resolving to that machine
  • Docker installation

Generate Let’s Encrypt certificates

To generate Let’s Encrypt certificates:

  1. Create an A record to point a domain to your remote machine (for example, from example.remote.gitlab.dev to

    If you do not have access to a domain, you can use a service like DuckDNS.
  2. Install Certbot to enable HTTPS:

    sudo apt-get update
    sudo apt-get install certbot
  3. Generate the certificates:

    export EMAIL="YOUR_EMAIL@example.com"
    export DOMAIN="example.remote.gitlab.dev"
    certbot -d "${DOMAIN}" \
      -m "${EMAIL}" \
      --config-dir ~/.certbot/config \
      --logs-dir ~/.certbot/logs \
      --work-dir ~/.certbot/work \
      --manual \
      --preferred-challenges dns certonly
    With DuckDNS, you must use the Certbot DNS DuckDNS plugin.

Now that you’ve generated the certificates, it’s time to create and connect a development environment.

Connect a development environment to the Web IDE

To connect a development environment to the Web IDE:

  1. Create a development environment:

    export CERTS_DIR="/home/ubuntu/.certbot/config/live/${DOMAIN}"
    export PROJECTS_DIR="/home/ubuntu"
    docker run -d \
      --name my-environment \
      -p 3443:3443 \
      -v "${CERTS_DIR}/fullchain.pem:/gitlab-rd-web-ide/certs/fullchain.pem" \
      -v "${CERTS_DIR}/privkey.pem:/gitlab-rd-web-ide/certs/privkey.pem" \
      -v "${PROJECTS_DIR}:/projects" \
      registry.gitlab.com/gitlab-org/remote-development/gitlab-rd-web-ide-docker:0.2-alpha \
      --log-level warn --domain "${DOMAIN}" --ignore-version-mismatch

    The new development environment starts automatically.

  2. Fetch a token:

    docker exec my-environment cat TOKEN
  3. Configure a remote connection.

Configure a remote connection

To configure a remote connection from the Web IDE:

  1. Open the Web IDE.
  2. On the menu bar, select View > Terminal or press Control+`.
  3. In the terminal panel, select Configure a remote connection.
  4. Enter the URL for the remote host including the port (for example, yourdomain.com:3443).
  5. Enter the project path.
  6. Enter the token you’ve fetched.

Alternatively, you can pass the parameters from a URL and connect directly to the Web IDE:

  1. Run this command:

    echo "https://gitlab-org.gitlab.io/gitlab-web-ide?remoteHost=${DOMAIN}:3443&hostPath=/projects"
  2. Go to that URL and enter the token you’ve fetched.

You’ve done it! Your development environment now runs as a remote host that’s connected to the Web IDE.