Choose an agent harness

VS Code supports multiple agent harnesses, each with its own tools, customizations, and workflows. An agent harness coordinates the language model, context, and tools that an agent uses to complete your task.

Use this guide to compare the available options, identify which harness your session uses, select a harness or the Cloud execution target, and review its setup requirements.

For a deeper explanation of how harnesses work and differ from models and hosts, learn about agent harness concepts.

Compare agent harnesses

Start with the Copilot harness for day-to-day coding and agent tasks. Choose another harness or the Cloud target when you need different tools, customizations, or execution workflows.

For Agent Host sessions managed by desktop VS Code on your machine, keep the application running. Closing an editor window is different from quitting the application. Tools provided by a window also require that window to stay connected.

Changing the model or agent role does not change the harness. For example, selecting a Claude model in a Copilot harness session still uses the Copilot harness. Opening the same session in another supported interface also keeps its harness.

Local is a harness name, not a synonym for running on your machine. The Copilot, Claude, and Codex harnesses can also run on your machine.

Available models depend on the harness and how you access models, such as through a GitHub Copilot subscription, another supported account, or your own API key. Harness-specific customizations, including hooks, follow the selected harness.

Select a harness

Select a harness before you submit the first prompt for a session:

1. Open the Chat view or open the Agents window.

2. Select New Chat (+) in the Chat view, or select New in the Agents window.

3. In the Agents window, select the folder or GitHub repository for the session.

4. Open the Session Target UI control and select an available harness or the Cloud target.

   

The control only lists targets whose requirements are met in the current window.

Choose a built-in agent

After selecting a harness, choose an available built-in agent from the agent picker. The available built-in agents depend on the harness:

Switching agents doesn't change the harness. You can also select custom agents from the same picker. In the Copilot harness, Autopilot is a mode with its own workflow, not an additional built-in agent.

Your harness choice is separate from where the session changes code. In the Agents window, you can also choose between a folder and a worktree or run a session in a Dev Container.

Identify your current harness

To identify the current harness for a chat session, use one of the following methods:

• In the editor window, the active harness is shown as a prefix in the chat title.

• In the Agents window, the chat input box shows the active harness as the watermark.

• In the Agents window, hover over the session entry in the sessions list to see a tooltip showing the harness.

Requirements and setup

Check the accounts, extensions, and settings needed for your chosen harness or the Cloud target. If a choice does not appear in the Session Target UI control, start with its requirements below.

Your harness and model access are separate choices. Using a provider's model through Copilot is different from using that provider's own credentials. The access option you select determines which account's usage limits and billing apply.

If you're starting with an existing account or key:

• GitHub Copilot access: Start with the Copilot harness. The Anthropic Claude and OpenAI Codex integrations also offer Copilot-routed models, subject to their requirements.
• Anthropic Claude credentials: Follow the authentication options.
• ChatGPT account: Follow the Codex setup for your chosen integration.
• Another model API key or local model: Configure a model provider for Local sessions or supported Experimental Copilot harness workflows.

For access through a provider's own credentials, that provider's usage limits, billing, and data-handling terms apply. Organization policies can restrict the available routes, even when you have separate credentials.

Cloud target

Use a cloud session to work interactively with an agent on managed compute and return to the same session later, without keeping your own machine online. Cloud is an execution target, separate from your choice of language model.

Cloud sessions

With chat.agentHost.cloudSandbox.enabled Open in VS Code Open in VS Code Insiders on, new Cloud sessions use a managed environment running the Copilot runtime. In the Agents window, this replaces the Copilot cloud agent workflow on GitHub Actions for new Cloud sessions. You can send follow-ups and reconnect to the session without keeping your own machine online. Connections require chat.remoteAgentHostsEnabled Open in VS Code Open in VS Code Insiders and service access for your account.

The cloud environment has its own workspace and tools. Choosing another model doesn't change the harness. Enabling cloud sessions doesn't move a local conversation or local files into the cloud.

To get started, follow Run cloud sessions for creation, continuation, and lifecycle guidance. The Cloud creation experience depends on your settings and account availability.

Continue with a different harness

A handoff continues an ongoing task with a different harness or execution environment and carries the conversation history and context with it. The tools, permissions, and models might change because the new configuration provides different capabilities.

Hand off from a Local harness session

From a Local harness session, you can select another supported harness after work starts. Sessions that use the Copilot or Claude harness, and sessions that use the experimental Codex integration, can receive these handoffs but can't hand off to another harness or to a cloud session.

To hand off a Local harness session:

1. Open the session.

2. In the chat input, open the Session Target dropdown.

3. Select Copilot, Claude, or Codex to continue the work.

VS Code carries the conversation history and context to the destination session. To implement a plan or continue it with another supported session, see planning with agents.

Changing a harness is different from starting another conversation or opening the same session in another interface. Learn more about sessions, forks, and handoffs.

Use canvases with the Copilot harness

Canvases are interactive visual surfaces shared by you and the agent in supported local Copilot sessions. For prerequisites and steps to find, open, and manage canvases, see Use canvases with agents.

Frequently asked questions

What is the difference between Local and Copilot?

Both harnesses can run on your machine. Local uses VS Code's built-in proprietary agent harness and works in VS Code's extension host. Copilot uses the Microsoft Copilot SDK, which is the agent experience shared consistently across GitHub Copilot products.

Both harnesses support tools, model selection, and agent customizations, but the available capabilities and configuration differ.

The Copilot harness provides these benefits:

• A shared runtime across Copilot products: core capabilities and behavior are more consistent across VS Code, GitHub Copilot CLI, and the GitHub Copilot app.

• Continuity between interfaces and machines: you can continue the same live session in the Chat view, the Agents window, and other GitHub Copilot interfaces. You can also connect remotely from another machine while the session continues to run on its host. Local sessions are available only in the editor's Chat view.

• Work independent of an editor window: ongoing work can continue after you close the editor window, while the Agent Host remains running. Closing a Local harness session's editor window stops its ongoing work.

Which harness should I choose?

Start with Copilot for day-to-day coding and agent tasks, especially when you want to continue work between the Chat view and Agents window, or keep work running after closing an editor window.

If your workflow depends on specific tools or customizations that aren't supported by the Copilot harness, please let us know. Before moving an existing workflow, check tool availability, MCP configuration compatibility, and hook compatibility.

Can I keep Local available while migrating?

Yes. Local remains an editor harness option while you adapt integrations that depend on it. Start a new session in the editor's Chat view and select Local from Session Target. Local is not available in the Agents window.

For an unmanaged editor, the following experimental settings make Local visible and turn off automatic Copilot preference:

{
  "chat.editor.localAgent.enabled": true,
  "chat.defaultToCopilotHarness": false,
  "chat.editor.preferCopilotHarness": false
}

An organization policy can override user settings. Starting with version 1.142, administrators can set vscode.temporaryDefaultToLocalHarness to true in enterprise-managed settings. This temporary control keeps Local available and suppresses automatic Copilot routing, including routing triggered by managed sandbox and permission settings. It preserves explicit, remembered, and current harness choices.

For customization-specific blockers and next steps, see the migration FAQ.

Does running locally mean the language model runs on my machine?

No. The harness coordinates the session and its tools, but the language model can run elsewhere. A session that edits files and runs commands on your machine can still send model requests to a hosted service. The Local harness name does not mean that the model runs locally or that the session works offline. Learn how harnesses differ from models and execution environments.

Does selecting a different model change the harness?

No. Selecting a model changes the model used within the current harness. For example, selecting a Claude model in a Copilot session does not switch to the Claude harness. Changing the agent role, such as Ask or Agent, also does not change the harness. To check which harness you are using, see Identify your current harness.

Can I continue an existing Local session with Copilot?

Yes. In the Local session's chat input, open the Session Target dropdown and select Copilot. The handoff carries the conversation history and context to the destination session, but the available tools, permissions, and models might change. See Hand off from a Local harness session.

Related resources

• Manage agent sessions, including continuing in the terminal.
• Remote agent access through GitHub Environments, SSH, or dev tunnels
• Approvals and permissions