Run and manage remote agent sessions

Use remote agent sessions to run tasks on another machine and interact with them from your current device. Connect to a host from the Agents window, then start a new task or continue an existing conversation.

The machines have two roles:

• Host machine: Runs the agent and contains the project, tools, and session.
• Client machine: Runs the application you use to connect and interact with the session.

Keep the host machine awake, online, and its Agent Host or owning application running. Connecting doesn't transfer the session or copy the project to the client machine.

Make a host available for remote access, then connect to an existing session or start a new remote session. To edit and debug the remote project alongside chat, see Use remote sessions in the Chat view.

Choose how to connect

Choose the workflow that matches what you want to do:

Opening a remote project in the editor is a separate workflow, described under Use remote sessions in the Chat view.

Make a host available for remote access

Enable remote access to start or continue agent sessions from another device while the project, tools, and execution stay on the host machine. Remote clients can access its Agent Host-backed sessions, such as a Copilot session. Local harness sessions The Local harness is deprecated and will be removed in February 2027. Move your workflows to the Copilot harness before then. Learn more about Local harness deprecation. and older extension-host sessions aren't shared this way.

Run these steps on the host machine to make it available for remote access.

1. On the host machine, open the Agents window, or use an Agent Host-backed session in the Chat view in an editor window.

2. Open Remote Connections (antenna icon) in the Agents window title bar or the Chat view input area.

   

3. Choose a connection method to start sharing.

   • GitHub Environments GitHub environments is in preview and might change before it becomes generally available. : Register the host as a GitHub environment for access from supported Copilot clients.
   • Dev Tunnels: Allow remote access from VS Code or the browser-based Agents window.

4. Complete any sign-in or confirmation prompts.

From the client machine, continue an existing session or start a remote session for a new task. To stop remote access, select Off in the same Remote Connections menu. This doesn't stop running agent tasks.

Continue an existing remote session

Connect to the host that owns the session through GitHub environments, SSH, or a dev tunnel. After connecting, select the existing session from the Agents window sessions list.

Connecting to a host doesn't by itself reopen a conversation. To continue a task, select its existing session rather than submitting the task as a new prompt.

To manage its customizations, keep the remote session selected and open Customizations. The editor uses that session's harness and remote workspace. It can show both host-owned customizations and supported customizations supplied by your connected client. Changes aren't necessarily limited to the selected session. See Manage customizations for remote sessions.

GitHub environments

Enable remote access on the host and select GitHub Environments to make it discoverable through your GitHub account. Registration doesn't create a new machine or copy your code.

On the client machine, where you want to interact with the remote session:

1. Sign in with the same GitHub account you used to register the host.

2. Open the Agents window. If needed, select New Session to show the chat input and its Environment picker.

3. Run the Agents: Manage Remote Environments command from the Command Palette.

4. Verify that the remote host appears in the list of available environments.

5. The sessions list in the Agents window shows available sessions from the remote host. Select the existing session list to continue the conversation.

The session's files, tools, and execution remain on the host machine. If you don't see the task, check the selected host and session filters.

For other supported Copilot clients, use that client's environment connection controls. Registration makes the machine discoverable; it doesn't guarantee that every client supports the same harnesses, sessions, or actions.

Start a remote session

Start a new remote session to run a task in a project folder on another machine.

Have the project folder and its required tools available on the host. For GitHub environments or dev tunnels, enable remote access with the antenna button first. You can also start a dev tunnel from the command line.

In the Agents window:

1. Select New Session or press ⌘N (Windows, Linux Ctrl+N).

2. Open the Environment picker in chat. Select an existing remote environment, or choose GitHub Environments, SSH, or Dev Tunnels to connect to a new one.

   

3. Choose a folder on the remote host when prompted, or select one in the workspace picker. Use the folder that contains the project you want the agent to work on.

4. Review the selected agent and permission level. Confirm the host and folder before sending your request.

5. Describe the task, any constraints, and how the agent should check its work. Press Enter to submit it. Review any tool approval requests before proceeding.

The agent uses the selected folder and tools on the host machine, not the client machine's local workspace. Review its edits before integrating the result.

Connect via SSH

Prerequisite: the remote machine must be accessible over SSH. VS Code installs the required CLI on the remote machine when needed.

Select SSH in the Environment picker, then select a configured host or enter a connection string, such as user@hostname. Complete any authentication prompts.

Connect via dev tunnel

Prerequisite: a dev tunnel is already running on the host machine. Enable Dev Tunnels through Remote Connections, or start a tunnel from the command line.

Select Dev Tunnels in the Environment picker, choose your account type, then select the active tunnel from the list.

Use the Agents window in the browser

Use the browser-based Agents window to access remote sessions from a device with a browser, without installing Visual Studio Code on that device. The agent and its project stay on the host machine.

Prepare the host using one of these methods (the browser doesn't connect directly over SSH):

• GitHub environments GitHub environments is in preview and might change before it becomes generally available. : Enable remote access on the host with GitHub Environments. If it's already registered, you don't need to start a dev tunnel.
• Dev tunnel: Enable Dev Tunnels through Remote Connections, start a tunnel from the command line, or use one that's already running.

Then, on the device you want to connect from:

1. Open the browser-based Agents window.

2. Sign in with Continue with GitHub when prompted. For a GitHub environment, use the same account that registered the host. For a dev tunnel, authenticate with the account that owns the tunnel when prompted for tunnel access.

3. Select the host in the sidebar's host picker. On mobile, the host picker is in the title bar of the new-session screen.

4. If the selected host is Disconnected, use its connection control to connect. On larger layouts, you can also select Connect from the host picker's menu.

5. Choose what you want to do:

   • Continue a task: Select its existing session from the sessions list, review the conversation, and send a follow-up.
   • Start a new task: Start a new session, choose a folder on the host and an available agent, then enter your task. Check the selected host and folder before sending the prompt.

Set up a dev tunnel

Skip this step if you use GitHub environments or already have a tunnel running.

On the host machine, open a terminal and run:

code tunnel

For VS Code Insiders, use code-insiders tunnel instead. Complete the GitHub or Microsoft authentication prompts if this is your first tunnel. Tunnels require authentication by default.

Leave the tunnel running, then follow the browser connection steps or start a session in the installed app. For more setup options, see Developing with Remote Tunnels.

Host management

The host picker scopes the sessions list to the selected machine. Selecting a host and connecting to it are separate actions.

Use Re-discover Hosts if a machine is missing. If a host is Disconnected, check that its tunnel or environment sharing is running and that the host is reachable, then reconnect. Disconnected doesn't necessarily mean that the remote machine is powered off.

In the browser, GitHub environments can connect automatically when available and chat.remoteAgentHostsAutoConnect Open in VS Code Open in VS Code Insiders is on. They don't require the prior connection history used by the installed app. Explicitly disconnecting suppresses automatic reconnection until you connect again.

If a connection drops during a session, let automatic recovery complete or reconnect through the host's connection control. Reopen the existing session to continue its conversation rather than starting a replacement.

Use remote sessions in the Chat view

Use the Chat view to work with an agent alongside the editor, terminal, and debugger. Open a remote workspace to work with code on another machine.

The Environment picker and connected-host list belong to the Agents window. The editor's Chat view uses the separate workflows below.

Work in a remote workspace

To edit and debug a remote project alongside chat, open the project through Remote Development, such as with the Remote - SSH extension, then start a chat in that editor window.

The chat uses the remote project's context and tools while the editor runs on the client machine.

Opening the remote project isn't the same as reopening an existing agent conversation. To continue a task, select its session from the sessions list if it is available in that window. Don't assume that opening the same repository starts or resumes a session from another application.

Share this machine from the Chat view

The Remote Connections control in the Chat view enables access to the machine running the agent. It doesn't connect the editor to another machine. In a local editor window with an Agent Host-backed session, follow Make a host available for remote access to use GitHub environments or dev tunnels.

Manage remote connections

Disconnect or stop sharing

• Disconnect a client to end that client's connection. This doesn't stop the host or its running tasks.

• Stop sharing the host by opening Remote Connections on the host and selecting Off. This stops sharing without changing the preferred connection method.

• Stop an agent task in its session when you want to halt active work. Disconnecting or turning sharing off is not a task-cancellation action.

The chat.agentHost.remoteConnections Open in VS Code Open in VS Code Insiders setting records your preferred connection method. Changing the setting directly turns sharing off. To start sharing, select the method in Remote Connections.

In the installed Agents window, discovering a machine doesn't connect to it for the first time. Connect explicitly. With chat.remoteAgentHostsAutoConnect Open in VS Code Open in VS Code Insiders on, previously connected online environments can reconnect for the same profile and account. Explicitly disconnecting suppresses automatic reconnection until you connect manually again.

Manage remote environments (Experimental)

Use the Remote Environments editor in the installed Agents window to find and manage your remote machines in one place. This editor is optional; you don't need to open it to follow the connection steps above.

To also manage how this computer is shared, enable sessions.chat.experimental.remoteEnvironmentsThisComputer Open in VS Code Open in VS Code Insiders . In This Computer, choose GitHub Environments (when available), Dev Tunnels, or Off, or select Rename Sharing Name to change the name other clients see. Local sessions continue to run on this computer whether sharing is on or off.

The table groups known SSH hosts, dev tunnels, and WSL distributions on Windows. When support for GitHub environments is available and enabled, the Environments group also lists your registered machines, including offline ones. These are user-shared machines, not the managed environments used by cloud sessions.

Remote environment management requires sessions.chat.experimental.environmentPicker Open in VS Code Open in VS Code Insiders , sessions.chat.experimental.environmentPickerManageRemotes Open in VS Code Open in VS Code Insiders , and chat.remoteAgentHostsEnabled Open in VS Code Open in VS Code Insiders . All three settings are on by default.

Open remote environment management

Run Agents: Manage Remote Environments from the Command Palette (⇧⌘P (Windows, Linux Ctrl+Shift+P)), or select Manage Remote Environments from the sessions list More Actions (...) menu.

You can also open the editor from the Environment picker:

1. Create a new chat or session in the Agents window.

2. Open the Environment picker and select Manage.

   

Find and organize remote machines

Use the table to search, connect, and organize your remote machines. Keep these behaviors in mind:

• Disconnecting doesn't stop running tasks. Refreshing discovers machines without connecting.

• Renaming or hiding a machine affects only this client. Hiding doesn't disconnect it or remove sessions. Leave a name empty to restore the default.

• Delete has different effects depending on the connection:

  • For a GitHub environment, it removes the registration and disconnects this client. The environment can reappear if its owning application registers it again.
  • For an eligible saved SSH connection, it forgets the saved connection and disconnects this client. It doesn't change your SSH configuration.
  • For a dev tunnel, it deletes the tunnel registration and disconnects its clients. Stop hosting a tunnel from this application before deleting it. A machine that starts hosting the tunnel again can recreate it.

  None of these actions deletes files on the remote machine.

Other remote workflows

Start a chat without a workspace on a remote host

In the installed Agents window, use a chat without a workspace when a task needs the resources or environment of a remote host but doesn't need a repository. The Chat workspace option isn't available in the browser-based interface.

To start a chat without a workspace:

1. Select New Session or press ⌘N (Windows, Linux Ctrl+N).

2. In the Environment picker, select the connected remote host.

3. In the workspace picker, select Chat instead of a project folder. This option requires a supported harness and environment.

4. Choose an agent harness, enter your prompt, and press Enter.

Select a folder on that host instead when the task needs an existing project.

Run a session in a remote Dev Container

Run agents inside your remote project's Dev Container to use its configured tools and dependencies without installing them directly on the remote machine. Starting in VS Code 1.139, this is supported for SSH, Tunnel, and WSL connections in the installed Agents window, not in the browser-based window.

Dev Container support ( chat.agentHost.devContainer.enabled Open in VS Code Open in VS Code Insiders ) is on by default. Docker must be installed and running on the remote host, and the project must contain a Dev Container configuration.

To run a session in a remote Dev Container:

1. Connect over SSH, through a tunnel, or to WSL, and select the project folder in the workspace picker.

2. Expand the menu for the remote folder and select Use Dev Container.

   The workspace label gains the - Dev Container suffix.

3. Choose an available agent harness, configure the session, and enter your prompt.

The Use Dev Container option appears only when the source machine advertises Dev Container support. It isn't available for unsupported machines or for folders whose source is nested inside another remote environment. For more information about prerequisites, switching back to the source machine, and troubleshooting, see Run a session in a Dev Container.

Preview a remote web app

In the installed Agents window, use the integrated browser to preview a web app running on a supported session host without forwarding its port. Enable workbench.browser.enableRemoteProxy Open in VS Code Open in VS Code Insiders , leave workbench.browser.dataStorage Open in VS Code Open in VS Code Insiders at default, and open the app's original localhost URL. Check that the remote indicator in the address bar identifies the intended host.

Select Share with Agent to let the agent interact with your page, or ask it to open the app and validate a user flow. See browsing through a remote agent host for supported hosts, storage behavior, and connection troubleshooting.

Delegate tasks to remote machines (Experimental)

Ask an agent in the installed Agents window to run work on another connected machine, such as testing a project on a different operating system. This starts remote work rather than resuming a session from the sessions list.

The originating chat must run on an Agent Host, and the connected target must advertise remote delegation support. Other chat providers aren't supported.

Turn on chat.remoteSessions.tools.enabled Open in VS Code Open in VS Code Insiders and chat.remoteAgentHostsEnabled Open in VS Code Open in VS Code Insiders , and connect the machines that the agent can use. You don't need to select the target machine in the workspace picker.

For example:

Run the tests in <remote-project-path> on the connected Windows host <host-name>.
Use the existing folder and send the results back to this chat when you finish.

The agent can discover connected hosts, start remote sessions, inspect their status, and send follow-up messages. You can name a host or ask the agent to choose one that matches requirements such as operating system, memory, CPU count, or model. If no connected host meets the criteria, the tool reports an error.

For repository work, specify an existing trusted folder on the target machine, either directly or in a new Git worktree. The tools don't clone or copy the coordinating session's workspace to the remote machine. If you don't specify a workspace, the remote session starts without one.

Normal approval requirements still apply to delegated work and messages. Review the selected host, folder, and worktree before you approve a tool call, especially when the agent uses automatic placement.

Keep the coordinating Agents window open and connected while delegated work runs so messages can flow between sessions. A remote session's final response isn't forwarded automatically. Ask the remote agent to send the result back to the originating chat, as in the example above.

Turning off chat.remoteSessions.tools.enabled Open in VS Code Open in VS Code Insiders removes the remote delegation tools, but doesn't disconnect remote machines or stop remote sessions that are already running.

Troubleshoot remote sessions

Troubleshoot GitHub environments

For host connectivity or missing sessions, start with the common checks.

Related resources

• Use the Agents window - agent-first workflows across multiple projects.
• Developing with Remote Tunnels - set up and manage dev tunnels.
• Agent Host architecture - technical details about remote connections and session execution.