VSCODE_CODE_CLI_TUNNEL_REFERENCE - TerrenceMcGuinness-NOAA/global-workflow GitHub Wiki

VS Code CLI Tunnel Command Reference

Comprehensive guide to code tunnel and related remote server commands
CLI Version: 1.107.1 | Last Updated: December 30, 2025

Table of Contents

Overview

The code tunnel command creates secure tunnels to access VS Code remotely through vscode.dev from anywhere. This enables:

  • Remote Development: Access your machine's VS Code from any browser
  • Port Forwarding: Securely expose local services
  • Persistent Connections: Run as a system service for always-on access
  • Multi-Machine Management: Register and manage multiple remote machines

Quick Start

# 1. Login with GitHub or Microsoft account
code tunnel user login --provider github

# 2. Start a tunnel (interactive)
code tunnel

# 3. Or start with a custom name
code tunnel --name my-dev-machine

# 4. Access via: https://vscode.dev/tunnel/<machine-name>

Command Hierarchy

code
├── tunnel                    # Main tunnel command
│   ├── prune                 # Delete stopped servers
│   ├── kill                  # Stop running tunnel
│   ├── restart               # Restart running tunnel
│   ├── status                # Check tunnel status
│   ├── rename <name>         # Rename machine
│   ├── unregister            # Remove machine registration
│   ├── user                  # Authentication management
│   │   ├── login             # Log in to service
│   │   ├── logout            # Log out
│   │   └── show              # Show current account
│   └── service               # System service management (Preview)
│       ├── install           # Install as system service
│       ├── uninstall         # Remove system service
│       └── log               # View service logs
├── serve-web                 # Run local web VS Code
├── ext                       # Extension management
│   ├── list                  # List installed extensions
│   ├── install               # Install extension
│   ├── uninstall             # Remove extension
│   └── update                # Update extensions
├── version                   # Version management
│   ├── use                   # Switch editor version
│   └── show                  # Show current version
├── status                    # Process diagnostics
└── update                    # Update CLI

Tunnel Commands

code tunnel

Create a tunnel accessible on vscode.dev from anywhere.

code tunnel [OPTIONS]

Options

Option Description
--name <NAME> Set machine name for the tunnel service
--random-name Generate a random machine name
--accept-server-license-terms Accept license without prompt
--no-sleep Prevent machine from sleeping while running
--install-extension <EXT> Preload extensions on connecting servers
--server-data-dir <DIR> Directory for server data
--extensions-dir <DIR> Root path for extensions
--reconnection-grace-time <SECS> Reconnection timeout (default: 10800 = 3 hours)

Examples

# Start tunnel with custom name
code tunnel --name dev-workstation

# Start with pre-installed extensions
code tunnel --install-extension ms-python.python --install-extension github.copilot

# Non-interactive start (CI/CD)
code tunnel --accept-server-license-terms --name ci-runner

# Prevent sleep during long sessions
code tunnel --no-sleep --name always-on

code tunnel prune

Delete all servers that are currently not running.

code tunnel prune

code tunnel kill

Stop any running tunnel on the system.

code tunnel kill

code tunnel restart

Restart any running tunnel on the system.

code tunnel restart

code tunnel status

Check if a tunnel is running on the current machine.

code tunnel status

code tunnel rename

Rename the machine's tunnel identifier.

code tunnel rename <NAME>
Argument Description
<NAME> New name for the machine

Example

code tunnel rename production-server

code tunnel unregister

Remove this machine's association with the port forwarding service.

code tunnel unregister

code tunnel user

Manage authentication for the tunnel service.

code tunnel user login

code tunnel user login [OPTIONS]
Option Description
--provider <PROVIDER> Auth provider: microsoft or github
--access-token <TOKEN> Provide access token directly (env: VSCODE_CLI_ACCESS_TOKEN)
--refresh-token <TOKEN> Provide refresh token (env: VSCODE_CLI_REFRESH_TOKEN)

Examples

# Interactive login with GitHub
code tunnel user login --provider github

# Non-interactive with token
export VSCODE_CLI_ACCESS_TOKEN="ghp_xxxxx"
code tunnel user login --provider github

# Login with Microsoft account
code tunnel user login --provider microsoft

code tunnel user logout

code tunnel user logout

code tunnel user show

Display the currently logged-in account.

code tunnel user show

code tunnel service

(Preview) Manage tunnel as a system service for persistent connections.

code tunnel service install

Install or reinstall the tunnel as a system service.

code tunnel service install [OPTIONS]
Option Description
--name <NAME> Set machine name
--accept-server-license-terms Accept license without prompt

Example

# Install service with custom name
code tunnel service install --name my-server --accept-server-license-terms

# Service auto-starts on boot

code tunnel service uninstall

Stop and remove the tunnel system service.

code tunnel service uninstall

code tunnel service log

View logs from the running service.

code tunnel service log

Related Commands

code serve-web

Run a local web version of VS Code (not tunneled).

code serve-web [OPTIONS]
Option Description
--host <HOST> Listen host (default: localhost)
--port <PORT> Listen port (default: 8000, use 0 for random)
--socket-path <PATH> Unix socket path
--connection-token <TOKEN> Required secret for requests
--connection-token-file <FILE> File containing connection secret
--without-connection-token Disable token (use only if secured otherwise)
--server-base-path <PATH> Base path for web UI
--server-data-dir <DIR> Server data directory
--commit-id <SHA> Specific commit SHA for client
--accept-server-license-terms Accept license without prompt

Examples

# Start local web server on port 3000
code serve-web --port 3000

# Bind to all interfaces (remote access)
code serve-web --host 0.0.0.0 --port 8080 --connection-token mysecret

# Use random port
code serve-web --port 0

code ext

Manage VS Code extensions.

code ext list

code ext list [OPTIONS]
Option Description
--show-versions Display version numbers
--category <CAT> Filter by category

code ext install

code ext install [OPTIONS] <ext-id | path>...
Option Description
--pre-release Install pre-release version
--force Update to latest if already installed
--donot-include-pack-and-dependencies Skip pack/dependency installation

Examples

# Install by ID
code ext install ms-python.python

# Install specific version
code ext install [email protected]

# Install from VSIX file
code ext install ./my-extension.vsix

# Install pre-release
code ext install github.copilot --pre-release

# Force update
code ext install ms-python.python --force

code ext uninstall

code ext uninstall <ext-id>...

code ext update

code ext update

code version

Manage VS Code editor versions.

code version show

code version show

code version use

code version use <stable | insiders | x.y.z | path>

Examples

# Use stable channel
code version use stable

# Use insiders
code version use insiders

# Use specific version
code version use 1.85.0

# Use custom installation
code version use /opt/vscode-custom

Global Options

These options apply to all code commands:

Option Description
--cli-data-dir <DIR> CLI metadata directory (env: VSCODE_CLI_DATA_DIR)
--verbose Enable verbose output (implies --wait)
--log <LEVEL> Log level: trace, debug, info, warn, error, critical, off
-h, --help Print help information
-V, --version Print version

Environment Variables

Variable Description Used By
VSCODE_CLI_DATA_DIR CLI metadata storage directory All commands
VSCODE_CLI_ACCESS_TOKEN Authentication access token tunnel user login
VSCODE_CLI_REFRESH_TOKEN Authentication refresh token tunnel user login

Use Cases & Examples

1. Development Server Setup

# Initial setup on dev server
code tunnel user login --provider github
code tunnel service install --name dev-server --accept-server-license-terms

# Access from anywhere at: https://vscode.dev/tunnel/dev-server

2. CI/CD Pipeline Access

#!/bin/bash
# Non-interactive tunnel for CI debugging

export VSCODE_CLI_ACCESS_TOKEN="${GITHUB_TOKEN}"
code tunnel user login --provider github
code tunnel --name "ci-${BUILD_ID}" --accept-server-license-terms &

echo "Debug at: https://vscode.dev/tunnel/ci-${BUILD_ID}"

3. HPC Cluster Node Access

# On HPC login node
code tunnel --name hera-login --no-sleep

# On compute node (via job script)
code tunnel --name hera-compute-${SLURM_JOB_ID} --accept-server-license-terms

4. Multi-Machine Management

# Machine 1: workstation
code tunnel --name workstation

# Machine 2: server
code tunnel --name prod-server

# Machine 3: laptop
code tunnel --name laptop

# Access any at: https://vscode.dev/tunnel/<name>

5. Cleanup Old Tunnels

# Stop current tunnel
code tunnel kill

# Remove stale servers
code tunnel prune

# Unregister from service
code tunnel unregister

Troubleshooting

Common Issues

Tunnel Not Connecting

# Check status
code tunnel status

# View verbose logs
code tunnel --verbose --log debug

# Restart tunnel
code tunnel restart

Authentication Issues

# Check current login
code tunnel user show

# Re-authenticate
code tunnel user logout
code tunnel user login --provider github

Service Not Starting

# Check service logs
code tunnel service log

# Reinstall service
code tunnel service uninstall
code tunnel service install --name my-server

Port Conflicts

# For serve-web, use random port
code serve-web --port 0

Log Levels

For debugging, increase verbosity:

code tunnel --log trace --verbose 2>&1 | tee tunnel.log

Quick Reference Card

Task Command
Start tunnel code tunnel --name <name>
Stop tunnel code tunnel kill
Check status code tunnel status
Rename machine code tunnel rename <name>
Login code tunnel user login --provider github
Logout code tunnel user logout
Install service code tunnel service install
Uninstall service code tunnel service uninstall
View service logs code tunnel service log
Clean up code tunnel prune && code tunnel unregister
Local web server code serve-web --port 8000
Install extension code ext install <id>
List extensions code ext list --show-versions

See Also

Generated from code tunnel --help on VS Code CLI 1.107.1

⚠️ **GitHub.com Fallback** ⚠️