Remote, Web, and Server

Purpose and Scope

Remote, web, and server experiences in VS Code are related but not interchangeable. The browser editor gives users a zero-install way to inspect repositories and make lighter edits. The server lets a client connect to source code and runtimes that live on another machine. Tunnels provide a command-line driven path for reaching a remote machine without making the user manage a direct SSH workflow. This page explains how those product concepts appear in this repository through package boundaries and sanity tests rather than through a single monolithic remote subsystem file. Sources: remote/package.json, remote/web/package.json, test/sanity/src/server.test.ts, test/sanity/src/serverWeb.test.ts, test/sanity/src/devTunnel.test.ts

The most important reader task is deciding which environment a change belongs to. A browser-only change should respect the constraints of code running in a web sandbox, where the package surface is intentionally smaller and centered on rendering, language highlighting, telemetry, and browser terminal UI pieces. A server or remote extension host change is different because it runs near the workspace and can rely on operating-system integrations, filesystem watching, process management, search, archive handling, and network plumbing. The repository makes that separation visible in the two package manifests under the remote area. Sources: remote/package.json, remote/web/package.json

Official remote-development guidance uses the distinction between user-interface extensions and workspace extensions to explain this split. User-interface extensions contribute visible editor features and normally run with the client, while workspace extensions run where the files, tools, language servers, and debuggers are available. The manifests here are a practical build-time reflection of the same idea. The web package carries dependencies that support the client-side editor experience, while the remote extension host package carries dependencies needed to operate beside a real workspace and its runtime. Sources: remote/package.json, remote/web/package.json

Relevant Source Files

• remote/package.json - Declares the private vscode-reh package and the dependency set for the remote extension host or server-side remote package, including terminal, search, file watching, proxy, SSH, native process, telemetry, TextMate, and Copilot-related runtime dependencies.
• remote/web/package.json - Declares the private vscode-web package and the dependency set for the browser-oriented web package, emphasizing browser-safe editor rendering, grammar, language detection, telemetry, icons, KaTeX, and xterm browser components.
• test/sanity/src/server.test.ts - Defines sanity coverage for standalone server artifacts across Alpine, Linux, macOS, and Windows architectures, starts each artifact with server command-line options, and verifies the version endpoint returns the expected commit.
• test/sanity/src/serverWeb.test.ts - Defines browser-tagged sanity coverage for server-web artifacts, starts each artifact, launches a browser, waits for the workbench shell, runs shared UI checks, and validates the result.
• test/sanity/src/devTunnel.test.ts - Defines Dev Tunnel sanity coverage through the CLI, including GitHub-account tagging, explicit tunnel logout for fresh authentication, browser automation, and the currently enabled macOS x64 artifact path.

System-to-Code Mapping

The remote extension host package is named vscode-reh and is private. Its dependencies include native and operating-system adjacent packages such as node-pty, ssh2, parcel watcher, native watchdog, ripgrep universal, sqlite, Windows process tree, Windows registry access, proxy agents, archive libraries, WebSocket support, and terminal packages. That combination describes a process that is expected to sit close to files and tools. It must support terminals, search, workspace state, proxy-aware networking, file watching, and platform-specific process behavior. The same manifest also includes Copilot and Copilot API dependencies, showing that remote-capable builds carry AI runtime pieces when those features participate in remote scenarios. Sources: remote/package.json

The web package is named vscode-web and is also private, but its dependency list is intentionally narrower. It keeps client-side pieces such as codicons, tree-sitter WebAssembly, language detection, Oniguruma, TextMate grammars, KaTeX, telemetry packages, character detection, and xterm browser add-ons. It does not show the server-side native process, SSH, file watching, registry, archive, or proxy-agent set that appears in the remote extension host manifest. That absence is a design signal, not just a smaller install size. The web artifact must be able to render and edit in a browser environment without assuming direct control over a remote operating system. Sources: remote/web/package.json, remote/package.json

This boundary matters for extension authors and product contributors because a feature can appear visually in the same workbench while executing in a different place. For example, syntax highlighting, icons, lightweight preview rendering, and many editor UI contributions can fit naturally in the browser surface. A feature that needs to spawn a shell, scan a large workspace using native search, inspect platform processes, or talk to SSH belongs closer to the remote server side. When a change crosses that boundary, the safest review question is whether the dependency or runtime assumption belongs in the browser package, the remote package, or both. Sources: remote/package.json, remote/web/package.json

Server Artifact Execution Flow

The standalone server sanity test validates packaged artifacts across a broad platform matrix. The visible cases cover Alpine arm64, Alpine x64, Darwin arm64, Darwin x64, Linux arm64, Linux x64, Windows arm64, and Windows x64. Each case downloads and unpacks the named server artifact, resolves the server entry point, and runs a shared server test routine unless the test context is in download-only mode. macOS artifacts are checked with code-signature validation before execution. Windows artifacts are checked with Authenticode signatures and version information before execution. These checks make packaging trust and platform metadata part of the remote-server quality gate. Sources: test/sanity/src/server.test.ts

The server process is launched with a concrete command-line shape. The test accepts server license terms, provides a random connection token, binds the host to all interfaces, chooses a unique port, and creates isolated temporary directories for server data and extensions. The callback watches process output for the message that the extension host agent is listening, extracts the reported port, builds a web server URL, fetches the version endpoint, and asserts that the returned text equals the expected commit from the test context. This prevents a stale or mismatched server binary from passing only because some process happened to start successfully. Sources: test/sanity/src/server.test.ts

A useful way to read this test is as executable documentation for the minimum server contract. The artifact must unpack, have a discoverable entry point, start without relying on preexisting user data, announce its listening port in the expected format, and serve a version response that identifies the build. If a change affects startup logging, token handling, data-directory layout, extension-directory initialization, HTTP routing, or commit stamping, this test is likely to expose the regression. It is intentionally simple at the feature level, but broad at the platform level, which makes it a strong packaging and bootstrap signal. Sources: test/sanity/src/server.test.ts

Server Web Execution Flow

The server-web sanity test uses a similar platform matrix, but every case is tagged for browser coverage and downloads an artifact whose name ends in a web variant. It covers Alpine, Darwin, Linux, and Windows on the same arm and x64 families visible in the standalone server test. Signature and version-info validation follow the same platform rules. The key difference is the validation target. Instead of stopping after an HTTP version response, the test launches a real browser, navigates to the generated URL, waits for the VS Code workbench shell, and then runs shared user-interface checks. Sources: test/sanity/src/serverWeb.test.ts

Before launching the web server, the test creates a random connection token and a UI test object. The server receives isolated server data, extension, and user-data directories, with the extension and user-data directories coming from the UI test helper. After the output line reports the extension host agent port, the test builds a tokenized web URL that also includes the workspace directory. Browser navigation waits until the network is idle, then waits for the monaco workbench selector. Only after that readiness signal does the shared UI test run. The browser is closed in a finally block so cleanup is attempted after both successes and failures. Sources: test/sanity/src/serverWeb.test.ts

This flow validates more than static web asset delivery. A passing result means the server-web artifact can start, advertise a connection endpoint, accept a tokenized browser connection, serve enough client code for the workbench to initialize, and support the shared UI scenario against isolated state. Failures can therefore point to multiple layers: artifact packaging, command-line parsing, token propagation, workspace URL generation, browser asset loading, workbench startup, or UI behavior. Contributors should resist treating this as only a browser smoke test; it is also a server and packaging integration test for the browser-hosted remote experience. Sources: test/sanity/src/serverWeb.test.ts

Dev Tunnel Sanity Coverage

The Dev Tunnel sanity test covers the CLI-based remote access journey. The visible source documents several platform cases in comments and notes that broader coverage is temporarily constrained by GitHub account throttling. The active case is dev-tunnel-darwin-x64, tagged with Darwin, x64, browser, and GitHub account. It downloads the macOS x64 CLI artifact, validates code signatures, resolves the CLI entry point, and runs the shared CLI test routine. The commented cases are still useful because they record the intended matrix for Alpine, Linux, macOS arm64, and Windows once account and flakiness concerns are addressed. Sources: test/sanity/src/devTunnel.test.ts

The test deliberately starts from a clean account state. It creates an isolated CLI data directory, logs that it is logging out of Dev Tunnel, and runs the CLI with that data directory to execute a tunnel user logout command. Then it constructs a UI test, a GitHub authentication helper, and a browser. The visible portion begins a run of the CLI named CLI with the isolated data directory and tunnel command. Even though the snippet is truncated, the structure shows that the sanity path is not a simple executable check. It combines CLI packaging, account state management, browser automation, and GitHub-backed authentication. Sources: test/sanity/src/devTunnel.test.ts

For maintainers, the tunnel test is also an operational warning. Remote tunnels depend on external authentication and service behavior in a way that local server startup does not. The test source keeps disabled cases nearby with explanations instead of erasing them, which helps reviewers distinguish intentionally reduced coverage from unknown coverage. If you change tunnel authentication, CLI data-directory handling, browser connection setup, or platform artifact naming, evaluate both the enforced macOS x64 path and the documented future matrix. The current test is the minimum visible gate, while the comments describe the expected direction for wider confidence. Sources: test/sanity/src/devTunnel.test.ts

Compact Reference

Area	Concrete source-level contract
Remote package	remote/package.json defines private package vscode-reh with dependencies such as node-pty, ssh2, @parcel/watcher, @vscode/ripgrep-universal, @vscode/sqlite3, ws, @github/copilot, and @vscode/copilot-api.
Web package	remote/web/package.json defines private package vscode-web with dependencies such as @vscode/codicons, @vscode/tree-sitter-wasm, vscode-oniguruma, vscode-textmate, @xterm/xterm, xterm add-ons, KaTeX, and telemetry packages.
Server launch options	--accept-server-license-terms, --connection-token, --host, --port, --server-data-dir, and --extensions-dir are used by the non-web server sanity test.
Server-web launch options	--accept-server-license-terms, --port, --connection-token, --server-data-dir, --extensions-dir, and --user-data-dir are used by the browser-backed server-web sanity test.
Readiness signal	Both server tests parse Extension host agent listening on <port> from process output before attempting HTTP or browser validation.
Version validation	The non-web server test fetches version from the generated server URL and asserts that it matches the expected commit.
Workbench validation	The server-web test opens a browser, navigates to the tokenized URL, waits for .monaco-workbench, runs UITest, and calls validation on the test helper.
Tunnel validation	The Dev Tunnel test uses CLI artifacts, an isolated --cli-data-dir, tunnel logout, browser automation, and GitHub authentication helpers for the visible active path.

Contributor Guidance and Next Steps

When working in this area, first classify the change by runtime location. If the change needs terminals, process control, SSH, filesystem watching, native search, proxy-aware server networking, or platform-specific metadata, review it against the remote extension host package and the standalone server sanity flow. If the change is browser-rendered, grammar-driven, icon-related, telemetry-facing, preview-oriented, or terminal-client-facing, review it against the web package and the server-web browser flow. When the change touches both, make the handoff explicit so reviewers can see why each package needs its dependency or behavior. Sources: remote/package.json, remote/web/package.json, test/sanity/src/server.test.ts, test/sanity/src/serverWeb.test.ts

Use the sanity tests as the final checklist for artifact behavior. Server artifacts should start from isolated data directories, announce the extension host agent port, and return the expected commit from the version endpoint. Server-web artifacts should load through a tokenized browser URL and reach the workbench readiness selector before UI validation runs. Tunnel changes should preserve clean CLI data isolation and avoid relying on hidden authentication state. After this page, read the command-line interface page for CLI entry points, the extension authoring overview for extension host placement, and the dev containers and Codespaces page for environment setup.