Copilot SDK Cloud Sessions and Remote Session Management: The Complete Developer Guide

The Copilot SDK enables three distinct remote session modes—"off", "export", and "on"—that determine whether session events stream to GitHub and whether remote servers can steer the session in real-time via JSON-RPC calls.

The GitHub Copilot SDK provides robust cloud session management capabilities that allow developers to control how AI sessions interact with remote infrastructure. By configuring the RemoteSessionMode enum defined in nodejs/src/types.ts, you can run sessions entirely locally, export telemetry to GitHub, or enable full remote steering via Mission Control.

Understanding RemoteSessionMode

The foundation of cloud session management in the Copilot SDK rests on the RemoteSessionMode enum. This type controls the session's relationship with GitHub's remote services throughout its lifecycle.

The Three Remote Session Modes

When creating or resuming a session, you specify one of three string literals that determine remote behavior:

• "off" – Runs the session completely locally. No events export to GitHub, and remote steering is disabled.
• "export" – Streams session events to GitHub (enabling telemetry and audit trails) but explicitly disables remote steering capabilities.
• "on" – Exports events and allows remote servers to steer the session, enabling human intervention via the Mission Control UI.

These modes are stored in the session options as the optional remoteSession?: RemoteSessionMode field, which the client passes to the underlying RPC layer during initialization.

Core Architecture of Cloud Sessions

Type Definitions and RPC Schema

The remote session contract begins in nodejs/src/types.ts, where the public SDK types define the RemoteSessionMode enum and the session configuration interface. The corresponding JSON-RPC schema resides in nodejs/src/generated/rpc.ts, which marks the remoteSession field as experimental and documents the three string literals. This generated file contains the method signatures that the RPC layer uses to serialize requests.

Session Object and RPC Namespace

The CopilotSession class in nodejs/src/session.ts instantiates a per-session RPC object (_rpc) that exposes a remote namespace for steering control. According to the source code, this namespace implements three critical methods:

• enable({ mode }) – Requests the remote server to begin steering the session.
• disable() – Terminates remote steering immediately.
• notifySteerableChanged({ remoteSteerable }) – Emits a local event when the remote side toggles steering capability.

These methods map directly to the JSON-RPC methods described in the generated schema, creating a type-safe bridge between the client and GitHub's control plane.

Event Flow for Remote Steering

State changes propagate through the event system defined in nodejs/src/generated/session-events.ts. When remote steerability changes, the SDK emits the session.remote_steerable_changed event. You can subscribe to this event using either the generic session.on(event => …) handler or the type-safe session.onTyped('session.remote_steerable_changed', …) method. The event payload contains a remoteSteerable boolean indicating whether the session currently accepts remote commands.

Client Configuration

The CopilotClient class in nodejs/src/client.ts forwards the remoteSession option from the user's configuration into the session-creation request. This flag persists when resuming a session via resumeSession(), ensuring continuity across application restarts. The client validates the mode before transmission, preventing invalid state transitions at the SDK boundary.

Testing Coverage

The end-to-end test suite validates remote behavior in nodejs/test/e2e/rpc_remote.e2e.test.ts. These tests verify that:

• Remote-off mode returns a no-op or "not implemented" error for steering commands.
• Remote-enable toggles the remoteSteerable flag and produces the corresponding event.
• Remote-disable resets the flag and terminates the control channel.

Additional error handling for unknown remote sessions appears in nodejs/test/e2e/rpc_server.e2e.test.ts.

Implementation Examples

Creating a Session with Remote Steering Enabled

To enable full remote control from session startup, pass "on" as the remoteSession mode:

import { CopilotClient, RemoteSessionMode } from "copilot-sdk";

const client = new CopilotClient({
  // …other client config
  remoteSession: "on" as RemoteSessionMode, // export & enable steering
});

const session = await client.createSession({ model: "gpt-4o" });

Enabling and Disabling Remote Control at Runtime

You can dynamically toggle remote steering even after session creation using the RPC remote namespace:

// Turn remote steering on (if it was started in "export" mode)
await session.rpc.remote.enable({ mode: "on" });

// Later, turn it off
await session.rpc.remote.disable();

Listening for Steering State Changes

Monitor remote steerability changes to update your UI or logging:

session.onTyped("session.remote_steerable_changed", event => {
  console.log("Remote steering is now", event.data.remoteSteerable ? "enabled" : "disabled");
});

Pure Export Mode Without Steering

For telemetry-only scenarios where remote intervention is prohibited:

await client.createSession({
  model: "gpt-4o",
  remoteSession: "export", // only export, no steering
});

Resuming Cloud Sessions

When resuming a previously exported session, the SDK restores the remote-session mode automatically:

const resumed = await client.resumeSession({ sessionId: "abc123" });
// The SDK restores the remote-session mode automatically.

Key Source Files Reference

File	Purpose
nodejs/src/types.ts	Defines RemoteSessionMode and the remoteSession option in the public SDK types.
nodejs/src/generated/rpc.ts	Contains the JSON-RPC schema for remote session control (remote.enable, remote.disable, etc.).
nodejs/src/session.ts	Implements CopilotSession, creates the per-session RPC object, and wires remote-control methods/events.
nodejs/src/client.ts	Passes the remoteSession flag from client configuration into session creation/resumption.
nodejs/src/generated/session-events.ts	Generates the session.remote_steerable_changed event type.
nodejs/test/e2e/rpc_remote.e2e.test.ts	Tests the remote-control lifecycle (enable, disable, event emission).
nodejs/test/e2e/rpc_server.e2e.test.ts	Ensures proper error handling for unknown remote sessions.

Summary

• Copilot SDK cloud sessions support three modes via RemoteSessionMode: "off" (local only), "export" (telemetry only), and "on" (full remote steering).
• The CopilotSession object in nodejs/src/session.ts exposes remote control through the session.rpc.remote namespace, providing enable(), disable(), and notification methods.
• State changes emit the session.remote_steerable_changed event defined in nodejs/src/generated/session-events.ts, which you can consume via session.onTyped().
• CopilotClient in nodejs/src/client.ts persists the remoteSession configuration across session creation and resumption operations.
• The end-to-end test suite in nodejs/test/e2e/rpc_remote.e2e.test.ts validates the complete remote control lifecycle.

Frequently Asked Questions

What is the difference between "export" and "on" modes in Copilot SDK remote sessions?

The "export" mode streams session events to GitHub for telemetry and audit purposes but explicitly disables remote steering capabilities. The "on" mode enables both event export and remote steering, allowing authorized users to intervene via the Mission Control interface while the session runs.

How do I listen for remote steering changes in a Copilot SDK session?

Use the session.onTyped('session.remote_steerable_changed', callback) method to subscribe to state changes. This event fires when the remote server toggles steering via the RPC layer, passing a payload with the remoteSteerable boolean indicating the current state.

Can I change the remote session mode after creating a session?

Yes, you can dynamically enable or disable remote steering at runtime using await session.rpc.remote.enable({ mode: "on" }) and await session.rpc.remote.disable(). These RPC calls communicate with the remote server to toggle steering regardless of the initial mode set during session creation.

Where are the remote session types defined in the Copilot SDK source code?

The RemoteSessionMode enum and session configuration options are defined in nodejs/src/types.ts. The JSON-RPC schema for remote control methods resides in nodejs/src/generated/rpc.ts, while the event types for steering changes are generated in nodejs/src/generated/session-events.ts.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}