Run and manage remote agent sessions
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. Run and manage remote agent sessions View as Markdown Ask in VS Code Ask in VS Code Insiders 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: Your task Start here What you need Continue an existing agent session from another machine. Use GitHub environments GitHub environments is in preview and might change before it becomes generally available. from the Agents window on the client machine.
Register the host machine as a GitHub environment and sign in with the same GitHub account on both machines. Run agent tasks on an SSH-accessible development server. Start a remote session in the Agents window, choosing SSH and a folder on that server. SSH access to the server. Connect through an existing dev tunnel or use a browser. Start a remote session with Dev Tunnels in the installed app, or follow the browser workflow .
For a dev tunnel, an authenticated tunnel running on the host. For browser access, either a registered GitHub environment or a dev tunnel. The browser doesn't connect directly over SSH. Edit and debug a remote project while using chat. Open the project through Remote Development , then use the Chat view. A remote workspace open in the editor. This is different from opening an existing agent conversation. Run agent tasks without keeping a development machine online.
Start a cloud session Cloud sessions is experimental and might change or be removed. . Managed cloud compute. Starting a cloud session doesn't move an existing session from your own host into the cloud. 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. If you're already connected to an SSH host, WSL distribution, or dev tunnel, you can instead share that remote as a GitHub environment from the client machine.
On the host machine, open the Agents window, or use an Agent Host-backed session in the Chat view in an editor window. Open Remote Connections (antenna icon) in the Agents window title bar or the Chat view input area. 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. 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. Important Remote connections enable access to the host's supported sessions, tools, and workspace resources, not just the current conversation.
With GitHub environments, session actions are mirrored to GitHub for catalog and history storage, and conversation content is not end-to-end encrypted. Review remote connection security before enabling access. 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: Sign in with the same GitHub account you used to register the host. Open the Agents window . If needed, select New Session to show the chat input and its Environment picker.
Run the Agents: Manage Remote Environments command from the Command Palette. Verify that the remote host appears in the list of available environments. 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: Select New Session or press ⌘N (Windows, Linux Ctrl+N ) . 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. 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.
Review the selected agent and permission level . Confirm the host and folder before sending your request. 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. Tip To verify the connection, ask the agent to report the operating system and current working directory without changing files.
Check that the result matches the intended host and project folder before requesting edits. 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, th
The rest of this page is on the live site.