Supporting Remote Development and GitHub Codespaces | Visual Studio Code Extension API
AI agents: See llms.txt for documentation discovery and navigation. Documentation articles are also available as Markdown by appending .md to the article URL. Join VS Code at Microsoft Ignite or catch the sessions online. A year of VS Code, wrapped. Explore the highlights. Supporting Remote Development and GitHub Codespaces View as Markdown Ask in VS Code Ask in VS Code Insiders Visual Studio Code Remote Development allows you to transparently interact with source code and runtime environments sitting on other machines (whether virtual or physical).
GitHub Codespaces is a service that expands these capabilities with managed cloud-hosted environments that are accessible from both VS Code and a browser-based editor. To ensure performance, Remote Development and GitHub Codespaces both transparently run certain VS Code extensions remotely. However, this can have subtle impacts on how extensions need to work. While many extensions will work without any modifications, you may need to make changes so that your extension works properly in all environments, although these changes are often fairly minor.
This article summarizes what extension authors need to know about Remote Development and Codespaces including the extension architecture , how to debug your extension in remote workspaces or Codespaces, and recommendations on what to do if your extension does not work properly . Architecture and extension kinds In order to make working with Remote Development or Codespaces as transparent as possible to users, VS Code distinguishes two kinds of extensions: UI Extensions : These extensions contribute to the VS Code user interface and are always run on the user's local machine.
UI Extensions cannot directly access files in the remote workspace, or run scripts/tools installed in that workspace or on the machine. Example UI Extensions include: themes, snippets, language grammars, and keymaps. Workspace Extensions : These extensions are run on the same machine as where the workspace is located. When in a local workspace, Workspace Extensions run on the local machine. When in a remote workspace or when using Codespaces, Workspace Extensions run on the remote machine / environment.
Workspace Extensions can access files in the workspace to provide rich, multi-file language services, debugger support, or perform complex operations on multiple files in the workspace (either directly or by invoking scripts/tools). While Workspace Extensions do not focus on modifying the UI, they can contribute explorers, views, and other UI elements as well. When a user installs an extension, VS Code automatically installs it to the correct location based on its kind.
If an extension can run as either kind, VS Code will attempt to choose the optimal one for the situation; UI Extensions will run in VS Code's local Extension Host , while Workspace Extensions will run in a Remote Extension Host that sits in a small VS Code Server , if it exists in a remote workspace, otherwise will run in VS Code's local extension host if it exists locally. To ensure the latest VS Code client features are available, the server needs to match the VS Code client version exactly.
Therefore, the server is automatically installed (or updated) by the Remote Development or GitHub Codespaces extensions when you open a folder in a container, on a remote SSH host, using Codespaces, or in the Windows Subsystem for Linux (WSL). (VS Code also automatically manages starting and stopping the server, so users aren't aware of its presence.) The VS Code APIs are designed to automatically run on the correct machine (either local or remote) when called from both UI or Workspace Extensions.
However, if your extension uses APIs not provided by VS Code — such using Node APIs or running shell scripts — it may not work properly when run remotely. We recommend that you test that all features of your extension work properly in both local and remote workspaces. Execution location and access to client resources Running a workspace extension remotely does not isolate it from client resources. The client is the desktop VS Code application or browser that presents the UI.
Extension kind describes where extension code should run, not which resources it can access through VS Code APIs. A remote workspace extension's Node.js code and child processes run on the remote host. However, its API calls can route operations to the client. Contributing UI does not move the extension to the local extension host or give it arbitrary local Node.js execution. Available capabilities depend on the API, resource URI, client environment, and applicable permissions.
Operation from a remote workspace extension Execution or access model Node.js filesystem APIs, native modules, and child processes Operate in the remote extension host's environment, with that process's permissions. vscode.workspace.fs Routes by resource URI and filesystem provider. Access is not inherently limited to the remote workspace and can include client-local files. vscode.env.clipboard Uses the client clipboard service, subject to client capabilities and permissions.
Views, status bar items, and notifications Render in the client UI. Extension-side callbacks remain in the remote extension host. Webview scripts Run in a sandbox on the client, separate from the remote extension code. vscode.env.openExternal Delegates opening to the client, subject to opener behavior and applicable restrictions. vscode.commands.executeCommand Routes to the command's implementation, which can be local or remote.
Available effects depend on the command. For file operations, a file: URI in a remote Node.js extension host normally identifies a remote file. Constructing a URI with vscode.Uri.file(...) does not select a client-local file. VS Code can bridge client-local file operations when the resource URI and available filesystem provider identify those resources. Preserve resource URIs returned by VS Code APIs, including their scheme and authority, instead of converting them to filesystem paths and reconstructing them.
Desktop and browser clients do not offer identical capabilities. Browser permissions and sandboxing can limit clipboard, filesystem, and external-opening operations. Do not assume that a browser client has unrestricted access to the local filesystem. Webview sandboxing and resource-loading restrictions , including localResourceRoots and content security policies, govern webview content. They are not a general restriction on the extension's API calls.
Debugging Extensions While you can install a development version of your extension in a remote environment for testing, if you encounter issues, you will likely want to debug your extension directly in a remote environment. In this section, we will cover how to edit, launch, and debug your extension in GitHub Codespaces , a local container , an SSH host , or in WSL . Typically, your best starting point for testing is to use a remote environment that restricts port access (for example Codespaces, a container, or remote SSH hosts with a restrictive firewall) since extensions that work in these environments tend to work in less restrictive ones like WSL.
Debugging with GitHub Codespaces Debugging your extension in GitHub Codespaces preview can be a great starting point since you can use both VS Code and the Codespaces browser-based editor for testing and troubleshooting. You can also use a custom development container if preferred. Follow these steps: Navigate to the repository that contains your extension on GitHub and open it in a codespace to work with it in a browser-based editor.
You can also open the codespace in VS Code if you prefer. While the default image for GitHub Codespaces should have all the needed prerequisites for most extensions, you can install any other required dependencies (for example, using yarn install or sudo apt-get ) in a new VS Code terminal window ( ⌃⇧` (Windows, Linux Ctrl+Shift+` ) ). Finally, press F5 or use the
The rest of this page is on the live site.