Remote Tunnels - Visual Studio Code

Overview

VS Code Remote Tunnels enable you to securely connect to a remote machine and access VS Code through your browser via vscode.dev from anywhere, without requiring SSH or complex networking configuration.

Remote Tunnels create a persistent connection between your machine and Microsoft’s tunnel service, allowing browser-based access to your development environment.

How It Works

The tunnel feature:

Creates a secure tunnel from your machine to Microsoft’s tunnel service
Generates a unique URL accessible via vscode.dev
Allows you to code in your browser while commands execute on the remote machine
Maintains file synchronization and extension compatibility

# Start a tunnel
code tunnel

After authentication, you’ll receive a URL like:

https://vscode.dev/tunnel/<machine-name>/<workspace>

Getting Started

Starting a Tunnel

The simplest way to start a tunnel:

code tunnel

This will:

Prompt you to log in with GitHub or Microsoft account
Accept the server license terms (or use --accept-server-license-terms to skip)
Create a tunnel with an auto-generated machine name
Display the vscode.dev URL for access

code tunnel
# Logs you in and starts tunnel with random name

Tunnel Commands

tunnel (serve)

Start a tunnel (default subcommand):

code tunnel [options]

Options

--name

string

Set a custom machine name for the tunnel

code tunnel --name my-workstation

--random-name

boolean

Use a randomly generated machine name

code tunnel --random-name

--no-sleep

boolean

Prevent the machine from going to sleep while tunnel is active

code tunnel --no-sleep

--accept-server-license-terms

boolean

Accept server license terms without prompting

code tunnel --accept-server-license-terms

--server-data-dir

string

Directory where server data is kept

--extensions-dir

string

Directory for extensions

--install-extension

string[]

Pre-install extensions on the server

code tunnel --install-extension ms-python.python --install-extension dbaeumer.vscode-eslint

tunnel status

Check if a tunnel is currently running:

code tunnel status

{
  "tunnel": {
    "name": "my-dev-machine",
    "cluster": "usw2",
    "tunnel_id": "abc123...",
    "uri": "https://vscode.dev/tunnel/my-dev-machine"
  },
  "service_installed": false
}

tunnel kill

Stop any running tunnel on the system:

code tunnel kill

This immediately terminates the tunnel process.

tunnel restart

Restart the running tunnel:

code tunnel restart

Useful for applying configuration changes or recovering from errors.

tunnel rename

Change the machine name associated with the tunnel:

code tunnel rename <new-name>

code tunnel rename my-new-machine-name

Renaming requires an active tunnel or previous registration.

tunnel unregister

Remove this machine’s association with the tunnel service:

code tunnel unregister

This removes the machine from your tunnel list but doesn’t delete any local data.

tunnel prune

Delete all server data for tunnels that are no longer running:

code tunnel prune

This frees up disk space by removing unused server installations.

User Management

code tunnel user login [options]

code tunnel user login
# Opens browser for authentication

Options

--provider

github | microsoft

Authentication provider to use

--access-token

string

Access token for authentication (also via VSCODE_CLI_ACCESS_TOKEN env var)

--refresh-token

string

Refresh token for authentication (also via VSCODE_CLI_REFRESH_TOKEN env var)

tunnel user logout

Log out from the tunnel service:

code tunnel user logout

This removes stored credentials.

tunnel user show

Display the currently logged-in account:

code tunnel user show

code tunnel user show
logged in with provider github

Running as a Service

For production or always-on scenarios, run the tunnel as a system service.

tunnel service install

Install the tunnel as a system service:

code tunnel service install [options]

sudo code tunnel service install --accept-server-license-terms

This creates a system service that:

Starts automatically on boot
Restarts on failure
Runs in the background
Persists across reboots

Options

--accept-server-license-terms

boolean

Accept license terms without prompting

--name

string

Machine name for the tunnel

tunnel service uninstall

Remove the tunnel service:

sudo code tunnel service uninstall

tunnel service log

View logs from the tunnel service:

code tunnel service log

This displays the service’s output and any errors.

Service management requires administrative privileges (sudo on Linux/macOS, Administrator on Windows).

Setup and Configuration

Initial Setup

Install VS Code CLI

Ensure the VS Code CLI is installed and available in your PATH:

code --version

Authenticate

code tunnel user login

Start Tunnel

Launch your first tunnel:

code tunnel --name my-dev-machine

Access via Browser

Open the provided vscode.dev URL in your browser and start coding!

Automated Setup

For headless servers or CI/CD environments:

#!/bin/bash
# Automated tunnel setup script

# Set authentication via environment variables
export VSCODE_CLI_ACCESS_TOKEN="your-token-here"

# Login non-interactively
code tunnel user login --provider github --access-token $VSCODE_CLI_ACCESS_TOKEN

# Install as service
sudo code tunnel service install \
  --name ci-build-server \
  --accept-server-license-terms

# Check status
code tunnel status

Configuration Files

The tunnel stores configuration in:

Linux/macOS: ~/.vscode-cli/
Windows: %USERPROFILE%\.vscode-cli\

You can customize this with --cli-data-dir:

code tunnel --cli-data-dir /custom/path

Connection and Usage

Accessing Your Tunnel

Once a tunnel is running, access it via:

Direct URL: https://vscode.dev/tunnel/<machine-name>
vscode.dev: Go to vscode.dev → Remote Explorer → Select your machine
Desktop VS Code: Use Remote-Tunnels extension

Working with Files

The browser interface provides full VS Code functionality:

File explorer with remote file system
Integrated terminal running on remote machine
Extension marketplace (extensions run remotely)
Source control integration
Debugging support

Multiple Tunnels

You can run tunnels on multiple machines:

# Machine 1
code tunnel --name dev-laptop

# Machine 2  
code tunnel --name build-server

# Machine 3
code tunnel --name testing-vm

All machines appear in vscode.dev’s Remote Explorer.

Security Considerations

Authentication

Always use secure authentication methods. Never share access tokens in plain text.

Tunnels require authentication via:

GitHub account
Microsoft account
Access tokens (for automation)

Connection Security

The tunnel connection:

Uses TLS encryption
Routes through Microsoft’s secure tunnel service
Validates authentication on each connection
Supports token-based access control

Best Practices

Secure Token Storage

When using access tokens for automation:

# Store in environment variables, not scripts
export VSCODE_CLI_ACCESS_TOKEN=$(cat ~/.secrets/vscode-token)

# Or use secret management tools
export VSCODE_CLI_ACCESS_TOKEN=$(vault kv get -field=token secret/vscode)

Network Isolation

The tunnel only exposes VS Code’s development interface. It does NOT:

Open arbitrary ports
Expose your entire file system
Allow direct shell access (only via VS Code’s integrated terminal)

Service Hardening

When running as a service:

# Run as dedicated user
sudo useradd -r -s /bin/false vscode-tunnel

# Limit file system access
# Configure service to only access necessary directories

Audit and Monitoring

Monitor tunnel usage:

# Check tunnel status regularly
code tunnel status

# Review service logs
code tunnel service log

# Monitor for unauthorized access
# Check vscode.dev account settings for connected machines

Firewall Requirements

Tunnels require outbound HTTPS (443) access to:

global.rel.tunnels.api.visualstudio.com
*.tunnels.api.visualstudio.com

No inbound firewall rules needed.

Advanced Usage

Port Forwarding

Tunnels automatically support port forwarding. When your app listens on a port:

# On remote machine
npm run dev  # Starts server on localhost:3000

VS Code detects this and offers to forward the port, making it accessible via vscode.dev.

Custom Server Arguments

Configure the remote server:

code tunnel \
  --server-data-dir /data/vscode \
  --extensions-dir /data/extensions \
  --install-extension ms-python.python

Reconnection Grace Period

The tunnel maintains sessions even if connection drops:

code tunnel --reconnection-grace-time 10800  # 3 hours in seconds

Integration with CI/CD

# GitHub Actions example
- name: Start Tunnel
  run: |
    code tunnel user login --provider github --access-token ${{ secrets.VSCODE_TOKEN }}
    code tunnel --random-name --accept-server-license-terms &
    sleep 10
    code tunnel status

Troubleshooting

Tunnel Won’t Start

Authentication Issues

# Clear credentials and re-login
code tunnel user logout
code tunnel user login

Port Conflicts

Check if another tunnel is running:

code tunnel status
code tunnel kill  # Stop existing tunnel

Network Issues

Verify connectivity to tunnel service:

curl -I https://global.rel.tunnels.api.visualstudio.com

Check firewall allows outbound HTTPS.

Service Issues

Service Won't Start

Check service logs:

code tunnel service log

# Or system logs
# Linux
journalctl -u code-tunnel

# macOS
log show --predicate 'process == "code"' --last 1h

Permission Errors

Ensure service has necessary permissions:

# Reinstall with proper permissions
sudo code tunnel service uninstall
sudo code tunnel service install --accept-server-license-terms

Performance Optimization

# Enable verbose logging for diagnosis
code tunnel --verbose --log trace

# Check system resources
code status

Comparison with Other Remote Solutions

Feature	Remote Tunnels	SSH + Remote-SSH	GitHub Codespaces
Setup Complexity	Low	Medium	Low
Browser Access	Yes	No	Yes
Firewall Config	None	Port forwarding	None
Cost	Free	Free	Paid
Machine Control	Full	Full	Limited
Network Required	Internet	Any	Internet

Next Steps

CLI Commands

Explore all CLI commands and options

CLI Overview

Learn more about VS Code CLI basics

Extensions

Manage extensions for your tunnel

Web Server

Alternative: Run local web server

Command Line

​Overview

​How It Works

​Getting Started

​Starting a Tunnel

​Tunnel Commands

​tunnel (serve)

​Options

​tunnel status

​tunnel kill

​tunnel restart

​tunnel rename

​tunnel unregister

​tunnel prune

​User Management

​tunnel user login

​Options

​tunnel user logout

​tunnel user show

​Running as a Service

​tunnel service install

​Options

​tunnel service uninstall

​tunnel service log

​Setup and Configuration

​Initial Setup

​Automated Setup

​Configuration Files

​Connection and Usage

​Accessing Your Tunnel

​Working with Files

​Multiple Tunnels

​Security Considerations

​Authentication

​Connection Security

​Best Practices

​Firewall Requirements

​Advanced Usage

​Port Forwarding

​Custom Server Arguments

​Reconnection Grace Period

​Integration with CI/CD

​Troubleshooting

​Tunnel Won’t Start

​Service Issues

​Performance Optimization

​Comparison with Other Remote Solutions

​Next Steps

CLI Commands

CLI Overview

Extensions

Web Server

Build docs developers (and LLMs) love

Overview

How It Works

Getting Started

Starting a Tunnel

Tunnel Commands

tunnel (serve)

Options

tunnel status

tunnel kill

tunnel restart

tunnel rename

tunnel unregister

tunnel prune

User Management

tunnel user login

Options

tunnel user logout

tunnel user show

Running as a Service

tunnel service install

Options

tunnel service uninstall

tunnel service log

Setup and Configuration

Initial Setup

Automated Setup

Configuration Files

Connection and Usage

Accessing Your Tunnel

Working with Files

Multiple Tunnels

Security Considerations

Authentication

Connection Security

Best Practices

Firewall Requirements

Advanced Usage

Port Forwarding

Custom Server Arguments

Reconnection Grace Period

Integration with CI/CD

Troubleshooting

Tunnel Won’t Start

Service Issues

Performance Optimization

Comparison with Other Remote Solutions

Next Steps