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

> Master Copilot SDK cloud sessions and remote session management. Explore 'off', 'export', and 'on' modes to control event streaming and real-time steering for seamless development.

- Repository: [GitHub/copilot-sdk](https://github.com/github/copilot-sdk)
- Tags: how-to-guide
- Published: 2026-08-02

---

**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`](https://github.com/github/copilot-sdk/blob/main/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`](https://github.com/github/copilot-sdk/blob/main/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`](https://github.com/github/copilot-sdk/blob/main/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`](https://github.com/github/copilot-sdk/blob/main/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`](https://github.com/github/copilot-sdk/blob/main/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`](https://github.com/github/copilot-sdk/blob/main/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`](https://github.com/github/copilot-sdk/blob/main/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`](https://github.com/github/copilot-sdk/blob/main/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:

```typescript
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:

```typescript
// 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:

```typescript
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:

```typescript
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:

```typescript
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`](https://github.com/github/copilot-sdk/blob/main/nodejs/src/types.ts) | Defines `RemoteSessionMode` and the `remoteSession` option in the public SDK types. |
| [`nodejs/src/generated/rpc.ts`](https://github.com/github/copilot-sdk/blob/main/nodejs/src/generated/rpc.ts) | Contains the JSON-RPC schema for remote session control (`remote.enable`, `remote.disable`, etc.). |
| [`nodejs/src/session.ts`](https://github.com/github/copilot-sdk/blob/main/nodejs/src/session.ts) | Implements `CopilotSession`, creates the per-session RPC object, and wires remote-control methods/events. |
| [`nodejs/src/client.ts`](https://github.com/github/copilot-sdk/blob/main/nodejs/src/client.ts) | Passes the `remoteSession` flag from client configuration into session creation/resumption. |
| [`nodejs/src/generated/session-events.ts`](https://github.com/github/copilot-sdk/blob/main/nodejs/src/generated/session-events.ts) | Generates the `session.remote_steerable_changed` event type. |
| [`nodejs/test/e2e/rpc_remote.e2e.test.ts`](https://github.com/github/copilot-sdk/blob/main/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`](https://github.com/github/copilot-sdk/blob/main/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`](https://github.com/github/copilot-sdk/blob/main/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`](https://github.com/github/copilot-sdk/blob/main/nodejs/src/generated/session-events.ts), which you can consume via `session.onTyped()`.
- **`CopilotClient`** in [`nodejs/src/client.ts`](https://github.com/github/copilot-sdk/blob/main/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`](https://github.com/github/copilot-sdk/blob/main/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`](https://github.com/github/copilot-sdk/blob/main/nodejs/src/types.ts). The JSON-RPC schema for remote control methods resides in [`nodejs/src/generated/rpc.ts`](https://github.com/github/copilot-sdk/blob/main/nodejs/src/generated/rpc.ts), while the event types for steering changes are generated in [`nodejs/src/generated/session-events.ts`](https://github.com/github/copilot-sdk/blob/main/nodejs/src/generated/session-events.ts).