Understand the VS Code Agent Host
VS Code runs AI coding agents in a dedicated process called the Agent Host, which it communicates with through the Agent Host Protocol (AHP). The host owns agent sessions independently of the clients that display and control them.
The Agent Host and AHP are under active development, and new capabilities continue to roll out.
Why a dedicated Agent Host?
A dedicated Agent Host process for agents provides the following capabilities:
- Shared sessions: multiple clients can observe and control the same session, staying in sync.
- Remote execution: the host can run next to the workspace on another machine while clients connect from elsewhere.
- Independent execution: an agent session can continue when no editor or other client is connected.
- Multiple agent implementations: different agent runtimes plug into one host-facing interface and present common session concepts to clients.
- Dedicated process: agents run in their own process, where they won't be blocked by busy extensions.
Earlier versions ran agent logic in the extension host, alongside the Copilot Chat extension. The extension host remains important for extensibility, but it is designed around the lifecycle and APIs of extensions, and long-running autonomous work has different needs. Extensions can still contribute chat customizations such as tools, MCP servers, and custom agents, but the agent runtime itself runs in the Agent Host process. By default, tools from extensions are only available in chats in an editor window where the extension is running.
Process architecture
The Agent Host can run as a local utility process or as a standalone server on a remote machine. VS Code uses a message port for local IPC and AHP JSON-RPC over WebSocket for remote connections.
The first-party agent adapters run inside the Agent Host process. An adapter translates between its agent runtime and the common AHP session model.
The Agent Host lives next to the workspace. It can run on your machine, inside a Dev Container, or on a remote machine. File edits and commands run in the environment that contains the host.
Agent Host Protocol
Agent Host Protocol is an open, agent-agnostic protocol between a host and its clients. It uses JSON-RPC for communication and immutable state with pure reducers for synchronized session data.
The host is the source of truth. Each client subscribes to URI-addressed channels for resources such as sessions, chats, terminals, and changesets. The client receives an initial state snapshot followed by ordered actions. If the connection drops, the client reconnects and receives missed actions or a fresh snapshot.
Self-contained, with optional client tools
The defining Agent Host principle is that the agent can run without a client. A client is a viewer and controller that can come and go. The host therefore includes the baseline capabilities needed to manage sessions and work with the workspace.
Agent sessions are not tied to the lifetime of the window for their workspace. You can close the window and reopen the session later from another window. While the Agent Host remains running, an active turn can continue without a connected client.
Connected clients can also contribute tools. For example, VS Code can advertise tools that are provided by the client (like the browser tools) or by installed extensions. The Agent Host adds those definitions to the active session and routes a tool call back to the client that contributed it.
Local and remote hosts
The desktop Agents window can connect to an Agent Host on the same machine or on a connected SSH, Tunnel, or WSL host. The browser-based Agents window connects to your development machine through a dev tunnel. The browser is a client, not the host that runs the session.
Clients display and control sessions. The Agent Host owns them. Desktop and browser clients can connect to the same tunnel host.
For a Dev Container session, the Agent Host runs inside the project's container. The container can run on your machine or on a supported SSH, Tunnel, or WSL host, while the desktop Agents window remains on your machine. Workspace file edits and commands use the tools and dependencies inside the container, rather than those installed directly on the source host.
Dev Container execution is an environment choice, not a different harness. See the session execution options diagram for how local, connected-host, container, and cloud execution relate. For setup steps, see Run an agent session in a Dev Container.
Like VS Code Remote Development, the user interface stays on the client while workspace operations run close to the source code and development tools.
To run your own standalone Agent Host, use code agent host. By default, the command starts a server on localhost and protects it with a connection token. Use the --tunnel option to expose it through a dev tunnel.
Behavior on the extension host
Agent sessions that don't run on the Agent Host run in the extension host. Existing extension-host sessions continue to run there.
There are some differences in behavior for agent sessions that run on the extension host:
| Behavior | Difference |
|---|---|
| Reviewing changes | Agent Host sessions apply edits directly to the session folder or worktree. Review the resulting diffs and then commit, merge, or discard the changes. Extension-host sessions track edits as pending until you keep or undo them. Learn more about reviewing AI-generated code edits. |
| Customizations | The Agent Host reads user-level customizations from harness-agnostic folders like ~/.copilot and ~/.claude. Customizations stored only in your VS Code profile user data are a legacy location that the Copilot agent doesn't read. Learn more about customizing agent behavior. |
| Hooks | Agent Host does not define one shared hook schema for every agent. The selected Copilot, Claude, or Codex harness executes its provider hook implementation. Extension-host sessions use the Local hook implementation and Local settings. Learn how to choose the hook implementation for a session. |
| Autopilot | On the Agent Host, Autopilot is an agent mode. On the extension host, it's a permission level. |
| Assisted permissions Assisted permissions is experimental and might change or be removed. | The Assisted permissions level is available only for supported Agent Host sessions and is off by default in Stable. |
| Session capabilities | Shared multi-window sessions, multiple chats per session, quick chats, and remote hosting are available only on the Agent Host. |
| Extension-provided tools | Tools from extensions are only available in chats in an editor window where the extension is running. |
| MCP configuration | The Agent Host reads harness-agnostic MCP config from .mcp.json (workspace) and ~/.copilot/mcp-config.json (user). It doesn't read .vscode/mcp.json directly, but VS Code forwards servers you configure in VS Code to the Agent Host, except servers that require interactive input (for example, ${input:...} variables). Learn more about configuring MCP servers. |