Remote Tunnels - Visual Studio Code

VS Code Remote Tunnels provide secure, authenticated access to your development machine from anywhere in the world. You can connect to your remote machine through vscode.dev or the VS Code desktop application without complex SSH or VPN configurations.

Overview

Remote Tunnels use Microsoft Dev Tunnels technology to create a secure connection between your local machine and the VS Code server. This allows you to:

Access your development environment from any device with a browser
Work on your home/office machine while traveling
Collaborate with others by sharing access to your machine
Develop on remote machines without SSH port forwarding
Use VS Code’s full feature set remotely

Remote Tunnels require authentication with either a Microsoft or GitHub account.

Quick Start

Start a tunnel

On your development machine, run:

code tunnel

Authenticate

Follow the prompts to log in with your Microsoft or GitHub account. You’ll be given a device code to enter on a web page.

Name your machine (optional)

Give your machine a memorable name, or let the CLI generate one randomly:

code tunnel --name my-dev-machine

Connect remotely

Open vscode.dev in any browser and connect to your tunnel, or use VS Code desktop with the Remote Tunnels extension.

Creating Tunnels

Basic Tunnel

Start a tunnel with default settings:

code tunnel

This will:

Prompt you to log in (if not already authenticated)
Generate a random machine name (or prompt for one)
Start the tunnel server
Display the URL to access your machine

Named Tunnel

Create a tunnel with a specific name:

code tunnel --name my-desktop

Machine names must be unique within your account and can only contain letters, numbers, and hyphens.

Random Name

Generate a random machine name automatically:

code tunnel --random-name

Useful for:

Temporary development environments
CI/CD runners
Testing scenarios

Prevent Sleep

Keep your machine awake while the tunnel is running:

code tunnel --no-sleep

This prevents the system from going to sleep, which would disconnect the tunnel.

Accept License Terms

Skip the interactive license acceptance prompt:

code tunnel --accept-server-license-terms

Required for:

Automated scripts
Non-interactive environments
CI/CD pipelines

Authentication

Authenticate with the tunnel service:

code tunnel user login

You’ll be prompted to:

Choose an authentication provider (Microsoft or GitHub)
Visit a URL and enter a device code
Authorize the application

GitHub
Microsoft

code tunnel user login --provider github

Authenticate using your GitHub account. This is recommended for developers who primarily use GitHub.

code tunnel user login --provider microsoft

Authenticate using your Microsoft account (work, school, or personal).

Token-Based Authentication

For automated workflows, you can provide access tokens directly:

code tunnel user login --provider github --access-token YOUR_TOKEN

Or use environment variables:

export VSCODE_CLI_ACCESS_TOKEN="your_access_token"
export VSCODE_CLI_REFRESH_TOKEN="your_refresh_token"
code tunnel user login --provider github

Never commit access tokens to version control. Use secure secret management for production deployments.

Check Authentication Status

Verify which account is currently logged in:

code tunnel user show

Output:

logged in with provider github

Logout

Remove stored credentials:

code tunnel user logout

Managing Tunnels

Check Status

Get information about running tunnels:

code tunnel status

Returns JSON output:

{
  "tunnel": {
    "name": "my-dev-machine",
    "cluster": "usw2",
    "id": "abc123...",
    "status": "running"
  },
  "service_installed": false
}

Rename Tunnel

Change the name of your machine:

code tunnel rename new-machine-name

This updates the machine name associated with the port forwarding service.

Restart Tunnel

Restart a running tunnel:

code tunnel restart

Useful after:

Configuration changes
Network connectivity issues
Extension updates

Stop Tunnel

Stop any running tunnel on the system:

code tunnel kill

This gracefully shuts down the tunnel server.

Unregister Machine

Remove this machine’s association with the tunnel service:

code tunnel unregister

This removes the machine from your account. You’ll need to create a new tunnel to connect again.

Clean Up Inactive Tunnels

Delete all tunnel servers that are not currently running:

code tunnel prune

This frees up disk space by removing:

Old server installations
Unused server data
Cached files

Running as a System Service

For always-on tunnel access, install the tunnel as a system service. The service runs in the background and starts automatically on system boot.

Install Service

Ensure you're logged in

code tunnel user login

Install the service

code tunnel service install

Or with a specific name:

code tunnel service install --name my-server

Accept license terms

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

Service installation requires administrator/root privileges on most systems.

Platform-Specific Service Management

Linux (systemd)
macOS (launchd)
Windows

The CLI creates a systemd service:

# Check service status
systemctl status code-tunnel

# View logs
journalctl -u code-tunnel -f

# Restart service
sudo systemctl restart code-tunnel

The CLI creates a launchd service:

# Check service status
launchctl list | grep code-tunnel

# View logs
tail -f ~/Library/Logs/code-tunnel.log

The CLI creates a Windows service:

# Check service status
Get-Service vscode-tunnel

# View logs
code tunnel service log

View Service Logs

Display logs from the running service:

code tunnel service log

This shows:

Connection events
Error messages
Performance metrics
Authentication status

Uninstall Service

Remove the tunnel service:

code tunnel service uninstall

This:

Stops the running service
Removes service configuration
Cleans up service files

Advanced Configuration

Custom Server Data Directory

Specify where server data is stored:

code tunnel --server-data-dir ~/.custom-vscode-server

Custom Extensions Directory

Use a custom location for extensions:

code tunnel --extensions-dir ~/.custom-extensions

Pre-install Extensions

Install extensions when the tunnel starts:

code tunnel --install-extension ms-python.python --install-extension ms-vscode.cpptools

Reconnection Grace Time

Set how long the server waits for reconnection (in seconds):

code tunnel --reconnection-grace-time 7200  # 2 hours

Default is 10800 seconds (3 hours).

Using Existing Tunnels

Connect to an existing tunnel with specific credentials:

These are advanced options primarily for internal or debugging use.

code tunnel --tunnel-id TUNNEL_ID --cluster CLUSTER --host-token TOKEN

Connecting to Tunnels

Via Browser (vscode.dev)

Open vscode.dev

Navigate to https://vscode.dev in any modern browser.

Click Remote Tunnels

In the left sidebar, click the Remote Explorer icon or use the Command Palette (F1) and search for “Remote Tunnels”.

Select your machine

Choose your machine from the list of available tunnels.

Start coding

You now have full access to your remote development environment!

Via VS Code Desktop

Install Remote Tunnels extension

Install the “Remote - Tunnels” extension from the marketplace.

Open Remote Explorer

Click the Remote Explorer icon in the Activity Bar.

Connect to tunnel

Select “Remote Tunnels” from the dropdown and click on your machine.

Via VS Code Insiders

VS Code Insiders has built-in tunnel support:

code-insiders --remote tunnel://my-machine-name

Port Forwarding

The tunnel automatically handles port forwarding for development servers.

How It Works

Start a web server on your remote machine (e.g., localhost:3000)
VS Code detects the server automatically
A forwarded URL is created (e.g., https://abc123.tunnel.dev:3000)
Access your app from anywhere via the forwarded URL

Manual Port Forwarding

You can also manually forward ports:

Open the Command Palette (F1)
Run “Forward a Port”
Enter the port number
Access via the provided URL

Security Considerations

Authentication & Authorization

All tunnel connections require authentication
Only you can access your tunnels (unless explicitly shared)
Connections use TLS encryption
Tokens are stored securely in the system keychain

Network Security

Tunnels use encrypted WebSocket connections
No inbound firewall rules required
All traffic goes through Microsoft’s Dev Tunnels service
Connection tokens are SHA-256 hashed

Data Privacy

Your code stays on your machine
Only connection metadata passes through the tunnel service
You control what is accessible remotely
Can be completely unregistered at any time

Best Practices

Use strong authentication (GitHub/Microsoft)
Don’t share access tokens
Regularly rotate credentials
Use --no-sleep judiciously (power consumption)
Monitor active connections via code tunnel status
Unregister unused tunnels

Use Cases

Remote Development

# On your powerful office desktop
code tunnel --name office-desktop --no-sleep

# From your laptop at home
# Access via vscode.dev or VS Code desktop

Continuous Development Environment

# Install as service for 24/7 access
code tunnel service install --name always-on-dev

Collaborative Debugging

# Start tunnel with pre-installed extensions
code tunnel --name debug-session \
  --install-extension ms-vscode.cpptools \
  --install-extension ms-vscode.cmake-tools

# Share access with team members

CI/CD Integration

# In your CI pipeline
export VSCODE_CLI_ACCESS_TOKEN="${GITHUB_TOKEN}"
code tunnel user login --provider github
code tunnel --random-name --accept-server-license-terms

Troubleshooting

Tunnel won't start

Common causes:

Not authenticated: Run code tunnel user login
Port 31545 already in use: Check for existing tunnel processes
Network restrictions: Ensure HTTPS/WSS traffic is allowed

Solutions:

# Check for running tunnels
code tunnel status

# Kill existing tunnel
code tunnel kill

# Check authentication
code tunnel user show

# Start with verbose logging
code tunnel --verbose

Can't connect to tunnel

Common causes:

Tunnel server stopped
Different authentication account
Network connectivity issues

Solutions:

# Verify tunnel is running
code tunnel status

# Restart tunnel
code tunnel restart

# Check you're using the same account
code tunnel user show

Service won't install

Common causes:

Insufficient permissions
Existing service installation
System service manager unavailable

Solutions:

# Run with elevated privileges
sudo code tunnel service install  # Linux/macOS

# Or as Administrator on Windows

# Uninstall existing service first
sudo code tunnel service uninstall

Tunnel keeps disconnecting

Common causes:

Machine going to sleep
Network instability
Firewall blocking connections

Solutions:

# Prevent sleep
code tunnel --no-sleep

# Install as service (more stable)
code tunnel service install

# Check logs
code tunnel service log

Extensions not working

Common causes:

Extensions not installed on server
Extension incompatibility with remote
Extension data directory issues

Solutions:

# Pre-install extensions
code tunnel --install-extension EXTENSION_ID

# Use custom extensions directory
code tunnel --extensions-dir ~/.custom-extensions

Performance Tips

Network Optimization

Use a wired connection when possible
Close bandwidth-heavy applications
Consider increasing reconnection grace time
Enable compression for large file transfers

Resource Management

Pre-install frequently used extensions
Use custom server data directory on fast storage
Regularly prune unused tunnel servers
Monitor system resources with code status

Comparison with SSH

Feature	Tunnels	SSH
Setup complexity	Simple	Moderate
Firewall config	Not required	Required
Web browser access	✅ Yes	❌ No
Built-in auth	✅ Yes	Manual
Port forwarding	Automatic	Manual
Cross-platform	✅ Yes	✅ Yes
Always-on service	✅ Yes	Requires setup
Free tier	✅ Yes	N/A

Limits and Quotas

Microsoft Dev Tunnels has usage limits for the free tier. See the Dev Tunnels documentation for current limits.

Typical limits:

Maximum concurrent tunnels per account
Bandwidth limits
Connection timeout periods
Data transfer quotas

Next Steps

Configuration

Configure tunnels for your workflow

Commands Reference

See all tunnel commands

Installation

Install the CLI

Overview

Back to CLI overview

​Overview

​Quick Start

​Creating Tunnels

​Basic Tunnel

​Named Tunnel

​Random Name

​Prevent Sleep

​Accept License Terms

​Authentication

​Login

​Token-Based Authentication

​Check Authentication Status

​Logout

​Managing Tunnels

​Check Status

​Rename Tunnel

​Restart Tunnel

​Stop Tunnel

​Unregister Machine

​Clean Up Inactive Tunnels

​Running as a System Service

​Install Service

​Platform-Specific Service Management

​View Service Logs

​Uninstall Service

​Advanced Configuration

​Custom Server Data Directory

​Custom Extensions Directory

​Pre-install Extensions

​Reconnection Grace Time

​Using Existing Tunnels

​Connecting to Tunnels

​Via Browser (vscode.dev)

​Via VS Code Desktop

​Via VS Code Insiders

​Port Forwarding

​How It Works

​Manual Port Forwarding

​Security Considerations

​Use Cases

​Remote Development

​Continuous Development Environment

​Collaborative Debugging

​CI/CD Integration

​Troubleshooting

​Performance Tips

Network Optimization

Resource Management

​Comparison with SSH

​Limits and Quotas

​Next Steps

Configuration

Commands Reference

Installation

Overview

Overview

Quick Start

Creating Tunnels

Basic Tunnel

Named Tunnel

Random Name

Prevent Sleep

Accept License Terms

Authentication

Login

Token-Based Authentication

Check Authentication Status

Logout

Managing Tunnels

Check Status

Rename Tunnel

Restart Tunnel

Stop Tunnel

Unregister Machine

Clean Up Inactive Tunnels

Running as a System Service

Install Service

Platform-Specific Service Management

View Service Logs

Uninstall Service

Advanced Configuration

Custom Server Data Directory

Custom Extensions Directory

Pre-install Extensions

Reconnection Grace Time

Using Existing Tunnels

Connecting to Tunnels

Via Browser (vscode.dev)

Via VS Code Desktop

Via VS Code Insiders

Port Forwarding

How It Works

Manual Port Forwarding

Security Considerations

Use Cases

Remote Development

Continuous Development Environment

Collaborative Debugging

CI/CD Integration

Troubleshooting

Performance Tips

Comparison with SSH

Limits and Quotas

Next Steps