The Extension Host: How Visual Studio Code Isolates and Communicates with Extensions

VS Code's extension ecosystem is the feature that transformed a text editor into a platform. But running thousands of third-party extensions inside the editor process would be a recipe for crashes, hangs, and security vulnerabilities. Instead, extensions run in isolated extension host processes, communicating with the workbench through a massive, typed RPC protocol. This article dissects that architecture.

Three Flavors of Extension Host

The ExtensionHostKind enum defines three extension host environments:

export const enum ExtensionHostKind {
    LocalProcess = 1,   // Node.js child process
    LocalWebWorker = 2, // Web Worker
    Remote = 3          // SSH/container/WSL
}

graph TD
    subgraph "Desktop VS Code"
        RENDERER["Renderer Process<br/>(Workbench UI)"]
        LP["<b>LocalProcess</b><br/>Node.js child process<br/>Full Node API access"]
        LW["<b>LocalWebWorker</b><br/>Web Worker<br/>Browser APIs only"]
    end
    
    subgraph "Remote Machine"
        SERVER["Remote Server"]
        REMOTE["<b>Remote</b><br/>Node.js process<br/>on SSH/container/WSL"]
    end
    
    RENDERER <-->|"Electron IPC /<br/>MessagePort"| LP
    RENDERER <-->|"Worker<br/>postMessage"| LW
    RENDERER <-->|"WebSocket"| SERVER
    SERVER <-->|"Node IPC"| REMOTE
    
    style LP fill:#e3f2fd
    style LW fill:#e8f5e9
    style REMOTE fill:#fff3e0

LocalProcess is the default for desktop VS Code. It runs extensions in a Node.js child process with full filesystem and network access — the most permissive environment. Extensions that declare "extensionKind": ["workspace"] in their manifest run here.

LocalWebWorker is used for lightweight, UI-focused extensions that only need browser APIs. It's also the only option on vscode.dev (web VS Code). Extensions declaring "extensionKind": ["ui"] run in this environment when possible.

Remote hosts extensions on a different machine entirely. When you connect via SSH, the Remote extension starts a headless VS Code server on that machine, which spawns its own extension hosts. Workspace extensions run remotely with access to the remote filesystem, while UI extensions stay local.

The assignment logic in determineExtensionHostKinds() considers each extension's declared kinds, whether it's installed locally or remotely, and development preferences to produce a final mapping.

The Protocol Contract: extHost.protocol.ts

The communication between the workbench (main thread side) and extension hosts is defined in a single, enormous file: src/vs/workbench/api/common/extHost.protocol.ts. At nearly 3,922 lines, it's the largest interface definition file in the codebase.

The file defines paired interfaces — for every MainThread*Shape interface (methods the extension host can call on the workbench), there's a corresponding ExtHost*Shape interface (methods the workbench can call on the extension host). Some examples:

MainThread (workbench)	ExtHost (extension host)
`MainThreadCommandsShape`	`ExtHostCommandsShape`
`MainThreadLanguageFeaturesShape`	`ExtHostLanguageFeaturesShape`
`MainThreadSCMShape`	`ExtHostSCMShape`
`MainThreadDebugServiceShape`	`ExtHostDebugServiceShape`
`MainThreadWebviewsShape`	`ExtHostWebviewsShape`

At the bottom of the file, two objects register all proxy identifiers:

src/vs/workbench/api/common/extHost.protocol.ts#L3757-L3840

The MainContext object registers ~83 proxy identifiers for workbench-side services. The ExtHostContext object registers ~60+ proxy identifiers for extension-host-side handlers. Together, they define over 140 RPC interfaces that make up the complete extension↔workbench communication surface.

Tip: When implementing a new extension API, start in extHost.protocol.ts. Add your MainThread*Shape and ExtHost*Shape interfaces, register proxy identifiers in both context objects, then implement both sides. The types enforce completeness.

RPC Proxy Pattern and IPC Transport

The createProxyIdentifier<T>() function creates a typed marker that the RPC system uses to auto-generate proxy objects. The flow works like this:

sequenceDiagram
    participant Ext as Extension Code
    participant EH as ExtHostCommands
    participant RPC as RPC Protocol
    participant MT as MainThreadCommands

    Ext->>EH: vscode.commands.executeCommand('myCmd')
    EH->>RPC: proxy.MainThreadCommands.$executeCommand('myCmd')
    Note over RPC: Serialize to MessagePort/IPC
    RPC->>MT: $executeCommand('myCmd')
    MT->>MT: Execute command in workbench
    MT-->>RPC: Return result
    RPC-->>EH: Deserialized result
    EH-->>Ext: Promise resolves

When the extension host boots, it receives an IExtHostRpcService — the RPC protocol instance. Each side calls rpcProtocol.set(identifier, handler) to register objects that handle incoming calls, and rpcProtocol.getProxy(identifier) to obtain a proxy that forwards method calls to the other side.

The underlying transport is abstracted by the IChannel/IServerChannel interfaces:

export interface IChannel {
    call<T>(command: string, arg?: any, cancellationToken?: CancellationToken): Promise<T>;
    listen<T>(event: string, arg?: any): Event<T>;
}

export interface IServerChannel<TContext = string> {
    call<T>(ctx: TContext, command: string, arg?: any, cancellationToken?: CancellationToken): Promise<T>;
    listen<T>(ctx: TContext, event: string, arg?: any): Event<T>;
}

The IChannel abstraction is transport-agnostic. The same interface works over Electron IPC (ipc.electron.ts), Node named pipes (ipc.net.ts), MessagePort (ipc.mp.ts), and WebSockets. The RPC protocol layer above it adds automatic serialization, cancellation propagation, and event subscription management with the RequestType/ResponseType enum protocol.

Constructing the vscode.* Namespace

The public API that extensions import as import * as vscode from 'vscode' is constructed at runtime by createApiFactoryAndRegisterActors().

This function is the wiring hub. It:

Resolves ~30 ExtHost service instances from the extension host's DI container — extHostWorkspace, extHostConfiguration, extHostCommands, extHostTerminalService, etc.
Registers them as RPC handlers by calling rpcProtocol.set(ExtHostContext.ExtHostCommands, extHostCommands) for each. This enables the workbench to call methods on these objects across the process boundary.
Creates additional ExtHost objects that aren't DI-managed — ExtHostDocuments, ExtHostNotebookController, etc.
Returns a factory function that, given an extension description, constructs the complete typeof vscode object tailored to that extension's permissions.

flowchart TD
    A["createApiFactoryAndRegisterActors()"] --> B["Resolve ~30 ExtHost<br/>services from DI"]
    B --> C["Register as RPC handlers<br/>rpcProtocol.set()"]
    C --> D["Create additional<br/>ExtHost objects"]
    D --> E["Return factory function"]
    E --> F["factory(extension)"]
    F --> G["Check proposed API access"]
    G --> H["Assemble vscode.* namespace"]
    H --> I["Extension receives<br/>typed API object"]

The factory function returned is called once per extension activation. This per-extension call is what enables proposed API gating — the factory checks whether each extension has access to unstable APIs before including them in the namespace.

Proposed APIs and Extension Trust

The public vscode.d.ts type definition is the stable API contract. But VS Code also maintains dozens of proposed API files under src/vscode-dts/vscode.proposed.*.d.ts. These are unstable APIs available only to:

Extensions listed in product.json's extensionEnabledApiProposals (Microsoft and partner extensions).
Extensions running in extension development mode with --enable-proposed-api.

The gating is enforced by checkProposedApiEnabled(), which is called throughout extHost.api.impl.ts whenever a proposed API is accessed:

// Example from the authentication namespace
checkProposedApiEnabled(extension, 'authLearnMore');
checkProposedApiEnabled(extension, 'authIssuers');

Built-in extensions (in the extensions/ directory) are special. They ship with VS Code, have access to internal APIs, and are updated with the product — not through the marketplace. They include critical functionality: TypeScript language support, Git integration, markdown rendering, theme defaults, and more.

The IExtensionHostInitData interface defines everything sent to an extension host at startup:

export interface IExtensionHostInitData {
    version: string;
    quality: string | undefined;
    commit?: string;
    parentPid: number | 0;
    environment: IEnvironment;
    workspace?: IStaticWorkspaceData | null;
    extensions: IExtensionDescriptionSnapshot;
    telemetryInfo: { ... };
    logLevel: LogLevel;
    remote: { isRemote: boolean; authority: string | undefined; ... };
    uiKind: UIKind;
    // ...
}

This payload includes the complete extension list with activation events, the workspace identity, log level, and remote connection data. The extension host uses this to determine which extensions to activate and when.

The Extension↔Workbench Data Flow

Let's trace a concrete example: when an extension registers a DocumentSymbolProvider. The flow crosses four boundaries:

sequenceDiagram
    participant Ext as Extension
    participant API as vscode.languages
    participant EH as ExtHostLanguageFeatures
    participant RPC as RPC Protocol  
    participant MT as MainThreadLanguageFeatures
    participant EditorModel as Editor Model

    Ext->>API: registerDocumentSymbolProvider(selector, provider)
    API->>EH: $registerDocumentSymbolProvider(handle, selector)
    EH->>RPC: proxy.$registerDocumentSymbolProvider(handle, selector)
    RPC->>MT: $registerDocumentSymbolProvider(handle, selector)
    MT->>EditorModel: Register provider adapter
    
    Note over EditorModel: User opens a file...
    
    EditorModel->>MT: Request symbols
    MT->>RPC: $provideDocumentSymbols(handle, uri)
    RPC->>EH: $provideDocumentSymbols(handle, uri)
    EH->>Ext: provider.provideDocumentSymbols(document)
    Ext-->>EH: SymbolInformation[]
    EH-->>RPC: Serialized symbols
    RPC-->>MT: Deserialized symbols
    MT-->>EditorModel: Display in outline

The registration flows toward the workbench. The actual provider calls flow toward the extension host. This bidirectional nature is why both MainContext and ExtHostContext proxy identifiers exist.

What's Next

We've now covered the full service infrastructure: how services are declared and wired (Article 3), how processes communicate (this article), and how extensions plug in. The final article brings it all together by examining the two main UI layers — the Monaco editor engine and the Workbench shell — and how features use the contribution system to compose the full IDE experience.

The Extension Host: How VS Code Isolates and Communicates with Extensions

Prerequisites