Add cloud session config support (#1306)

* Add cloud session config support

Expose the session.create cloud option across SDK clients and forward repository metadata to the runtime.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* Address cloud session review feedback

Remove the manual changelog entry and standardize Rust doc examples on the published crate name.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

---------

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: tiagonbotelho

docs/features/remote-sessions.md

@@ -97,7 +97,7 @@ session.On((SessionEvent e) =>
 
 <!-- docs-validate: skip -->
 ```rust
-use copilot_sdk::{Client, ClientOptions};
+use github_copilot_sdk::{Client, ClientOptions, PermissionRequestResult, SessionConfig};
 
 let client = Client::start(
     ClientOptions::new().with_remote(true)
@@ -119,6 +119,92 @@ while let Ok(event) = events.recv().await {
 
 <!-- tabs:end -->
 
+### Cloud sessions
+
+Set the create-session `cloud` option to create a remote session in the cloud instead of a local session. You can include repository metadata to associate the cloud session with a GitHub repository.
+
+<!-- tabs:start -->
+
+#### TypeScript
+
+<!-- docs-validate: skip -->
+```typescript
+const session = await client.createSession({
+  onPermissionRequest: async () => ({ allowed: true }),
+  cloud: {
+    repository: { owner: "github", name: "copilot-sdk", branch: "main" },
+  },
+});
+```
+
+#### Python
+
+<!-- docs-validate: skip -->
+```python
+from copilot import CloudSessionOptions, CloudSessionRepository
+
+session = await client.create_session(
+    on_permission_request=PermissionHandler.approve_all,
+    cloud=CloudSessionOptions(
+        repository=CloudSessionRepository(
+            owner="github",
+            name="copilot-sdk",
+            branch="main",
+        )
+    ),
+)
+```
+
+#### Go
+
+<!-- docs-validate: skip -->
+```go
+session, err := client.CreateSession(ctx, &copilot.SessionConfig{
+    Cloud: &copilot.CloudSessionOptions{
+        Repository: &copilot.CloudSessionRepository{
+            Owner:  "github",
+            Name:   "copilot-sdk",
+            Branch: "main",
+        },
+    },
+})
+```
+
+#### C#
+
+<!-- docs-validate: skip -->
+```csharp
+var session = await client.CreateSessionAsync(new SessionConfig
+{
+    Cloud = new CloudSessionOptions
+    {
+        Repository = new CloudSessionRepository
+        {
+            Owner = "github",
+            Name = "copilot-sdk",
+            Branch = "main"
+        }
+    }
+});
+```
+
+#### Rust
+
+<!-- docs-validate: skip -->
+```rust
+use github_copilot_sdk::{CloudSessionOptions, CloudSessionRepository, SessionConfig};
+
+let session = client.create_session(
+    SessionConfig::default().with_cloud(
+        CloudSessionOptions::with_repository(
+            CloudSessionRepository::new("github", "copilot-sdk").with_branch("main"),
+        ),
+    ),
+).await?;
+```
+
+<!-- tabs:end -->
+
 ### On-demand (per-session toggle)
 
 Use `session.rpc.remote.enable()` to start remote access mid-session, and `session.rpc.remote.disable()` to stop it. This is equivalent to the CLI's `/remote on` and `/remote off` commands.
@@ -199,5 +285,6 @@ The remote URL can be rendered as a QR code for easy mobile access. The SDK prov
 ## Notes
 
 * The `remote` client option only applies when the SDK spawns the CLI process. It is ignored when connecting to an external server via `cliUrl`.
+* The `cloud` session option applies only to new sessions created with `session.create`; it is not used when resuming an existing session.
 * If the working directory is not a GitHub repository, remote setup is silently skipped (always-on mode) or returns an error (on-demand mode).
 * Remote sessions require authentication. Ensure `gitHubToken` or `useLoggedInUser` is configured.

dotnet/src/Client.cs

@@ -632,6 +632,7 @@ public async Task<CopilotSession> CreateSessionAsync(SessionConfig config, Cance
                 ModelCapabilities: config.ModelCapabilities,
                 GitHubToken: config.GitHubToken,
                 RemoteSession: config.RemoteSession,
+                Cloud: config.Cloud,
                 InstructionDirectories: config.InstructionDirectories);
 
             var rpcTimestamp = Stopwatch.GetTimestamp();
@@ -2001,6 +2002,7 @@ internal record CreateSessionRequest(
         ModelCapabilitiesOverride? ModelCapabilities = null,
         string? GitHubToken = null,
         RemoteSessionMode? RemoteSession = null,
+        CloudSessionOptions? Cloud = null,
         IList<string>? InstructionDirectories = null);
 
     internal record ToolDefinition(

dotnet/src/Types.cs

@@ -1988,6 +1988,32 @@ public class InfiniteSessionConfig
     public double? BufferExhaustionThreshold { get; set; }
 }
 
+/// <summary>
+/// GitHub repository metadata to associate with a cloud session.
+/// </summary>
+public class CloudSessionRepository
+{
+    /// <summary>Repository owner.</summary>
+    public required string Owner { get; set; }
+
+    /// <summary>Repository name.</summary>
+    public required string Name { get; set; }
+
+    /// <summary>Optional branch name.</summary>
+    public string? Branch { get; set; }
+}
+
+/// <summary>
+/// Options for creating a remote session in the cloud.
+/// </summary>
+public class CloudSessionOptions
+{
+    /// <summary>
+    /// Optional GitHub repository metadata to associate with the cloud session.
+    /// </summary>
+    public CloudSessionRepository? Repository { get; set; }
+}
+
 /// <summary>
 /// Configuration options for creating a new Copilot session.
 /// </summary>
@@ -2037,6 +2063,7 @@ protected SessionConfig(SessionConfig? other)
         CreateSessionFsHandler = other.CreateSessionFsHandler;
         GitHubToken = other.GitHubToken;
         RemoteSession = other.RemoteSession;
+        Cloud = other.Cloud;
         SessionId = other.SessionId;
         SkillDirectories = other.SkillDirectories is not null ? [.. other.SkillDirectories] : null;
         InstructionDirectories = other.InstructionDirectories is not null ? [.. other.InstructionDirectories] : null;
@@ -2272,6 +2299,12 @@ protected SessionConfig(SessionConfig? other)
     /// </summary>
     public RemoteSessionMode? RemoteSession { get; set; }
 
+    /// <summary>
+    /// Creates a remote session in the cloud instead of a local session.
+    /// The optional repository is associated with the cloud session.
+    /// </summary>
+    public CloudSessionOptions? Cloud { get; set; }
+
     /// <summary>
     /// Creates a shallow clone of this <see cref="SessionConfig"/> instance.
     /// </summary>

dotnet/test/Unit/CloneTests.cs

@@ -96,6 +96,15 @@ public void SessionConfig_Clone_CopiesAllProperties()
             McpServers = new Dictionary<string, McpServerConfig> { ["server1"] = new McpStdioServerConfig { Command = "echo" } },
             CustomAgents = [new CustomAgentConfig { Name = "agent1", Model = "claude-haiku-4.5" }],
             Agent = "agent1",
+            Cloud = new CloudSessionOptions
+            {
+                Repository = new CloudSessionRepository
+                {
+                    Owner = "github",
+                    Name = "copilot-sdk",
+                    Branch = "main"
+                }
+            },
             DefaultAgent = new DefaultAgentConfig { ExcludedTools = ["hidden-tool"] },
             SkillDirectories = ["/skills"],
             InstructionDirectories = ["/instructions"],
@@ -121,6 +130,7 @@ public void SessionConfig_Clone_CopiesAllProperties()
         Assert.Equal(original.CustomAgents.Count, clone.CustomAgents!.Count);
         Assert.Equal(original.CustomAgents[0].Model, clone.CustomAgents[0].Model);
         Assert.Equal(original.Agent, clone.Agent);
+        Assert.Same(original.Cloud, clone.Cloud);
         Assert.Equal(original.DefaultAgent!.ExcludedTools, clone.DefaultAgent!.ExcludedTools);
         Assert.Equal(original.SkillDirectories, clone.SkillDirectories);
         Assert.Equal(original.InstructionDirectories, clone.InstructionDirectories);

dotnet/test/Unit/SerializationTests.cs

@@ -113,6 +113,31 @@ public void CreateSessionRequest_CanSerializeInstructionDirectories_WithSdkOptio
         Assert.Equal("C:\\more-instructions", root.GetProperty("instructionDirectories")[1].GetString());
     }
 
+    [Fact]
+    public void CreateSessionRequest_CanSerializeCloudOptions_WithSdkOptions()
+    {
+        var options = GetSerializerOptions();
+        var requestType = GetNestedType(typeof(CopilotClient), "CreateSessionRequest");
+        var request = CreateInternalRequest(
+            requestType,
+            ("Cloud", new CloudSessionOptions
+            {
+                Repository = new CloudSessionRepository
+                {
+                    Owner = "github",
+                    Name = "copilot-sdk",
+                    Branch = "main"
+                }
+            }));
+
+        var json = JsonSerializer.Serialize(request, requestType, options);
+        using var document = JsonDocument.Parse(json);
+        var repository = document.RootElement.GetProperty("cloud").GetProperty("repository");
+        Assert.Equal("github", repository.GetProperty("owner").GetString());
+        Assert.Equal("copilot-sdk", repository.GetProperty("name").GetString());
+        Assert.Equal("main", repository.GetProperty("branch").GetString());
+    }
+
     [Fact]
     public void CreateSessionRequest_CanSerializeModeRequestFlags_WithSdkOptions()
     {

go/client.go

@@ -646,6 +646,7 @@ func (c *Client) CreateSession(ctx context.Context, config *SessionConfig) (*Ses
 	req.InfiniteSessions = config.InfiniteSessions
 	req.GitHubToken = config.GitHubToken
 	req.RemoteSession = config.RemoteSession
+	req.Cloud = config.Cloud
 
 	if len(config.Commands) > 0 {
 		cmds := make([]wireCommand, 0, len(config.Commands))

go/client_test.go

@@ -865,6 +865,55 @@ func TestCreateSessionRequest_Commands(t *testing.T) {
 	})
 }
 
+func TestCreateSessionRequest_Cloud(t *testing.T) {
+	t.Run("forwards cloud options in session.create RPC", func(t *testing.T) {
+		req := createSessionRequest{
+			Cloud: &CloudSessionOptions{
+				Repository: &CloudSessionRepository{
+					Owner:  "github",
+					Name:   "copilot-sdk",
+					Branch: "main",
+				},
+			},
+		}
+		data, err := json.Marshal(req)
+		if err != nil {
+			t.Fatalf("Failed to marshal: %v", err)
+		}
+		var m map[string]any
+		if err := json.Unmarshal(data, &m); err != nil {
+			t.Fatalf("Failed to unmarshal: %v", err)
+		}
+		cloud, ok := m["cloud"].(map[string]any)
+		if !ok {
+			t.Fatalf("Expected cloud to be an object, got %T", m["cloud"])
+		}
+		repository, ok := cloud["repository"].(map[string]any)
+		if !ok {
+			t.Fatalf("Expected cloud.repository to be an object, got %T", cloud["repository"])
+		}
+		if repository["owner"] != "github" {
+			t.Errorf("Expected owner 'github', got %v", repository["owner"])
+		}
+		if repository["name"] != "copilot-sdk" {
+			t.Errorf("Expected name 'copilot-sdk', got %v", repository["name"])
+		}
+		if repository["branch"] != "main" {
+			t.Errorf("Expected branch 'main', got %v", repository["branch"])
+		}
+	})
+
+	t.Run("omits cloud from JSON when unset", func(t *testing.T) {
+		req := createSessionRequest{}
+		data, _ := json.Marshal(req)
+		var m map[string]any
+		json.Unmarshal(data, &m)
+		if _, ok := m["cloud"]; ok {
+			t.Error("Expected cloud to be omitted when unset")
+		}
+	})
+}
+
 func TestResumeSessionRequest_Commands(t *testing.T) {
 	t.Run("forwards commands in session.resume RPC", func(t *testing.T) {
 		req := resumeSessionRequest{

go/types.go

@@ -98,6 +98,18 @@ type ClientOptions struct {
 	Remote bool
 }
 
+// CloudSessionRepository is GitHub repository metadata associated with a cloud session.
+type CloudSessionRepository struct {
+	Owner  string `json:"owner"`
+	Name   string `json:"name"`
+	Branch string `json:"branch,omitempty"`
+}
+
+// CloudSessionOptions configures creation of a remote session in the cloud.
+type CloudSessionOptions struct {
+	Repository *CloudSessionRepository `json:"repository,omitempty"`
+}
+
 // TelemetryConfig configures OpenTelemetry integration for the Copilot CLI process.
 type TelemetryConfig struct {
 	// OTLPEndpoint is the OTLP HTTP endpoint URL for trace/metric export.
@@ -689,6 +701,9 @@ type SessionConfig struct {
 	//   - "export" — export session events to GitHub without enabling remote steering
 	//   - "on" — export to GitHub AND enable remote steering
 	RemoteSession rpc.RemoteSessionMode
+	// Cloud creates a remote session in the cloud instead of a local session.
+	// The optional repository is associated with the cloud session.
+	Cloud *CloudSessionOptions
 }
 type Tool struct {
 	Name                 string         `json:"name"`
@@ -1155,6 +1170,7 @@ type createSessionRequest struct {
 	RequestElicitation             *bool                          `json:"requestElicitation,omitempty"`
 	GitHubToken                    string                         `json:"gitHubToken,omitempty"`
 	RemoteSession                  rpc.RemoteSessionMode          `json:"remoteSession,omitempty"`
+	Cloud                          *CloudSessionOptions           `json:"cloud,omitempty"`
 	Traceparent                    string                         `json:"traceparent,omitempty"`
 	Tracestate                     string                         `json:"tracestate,omitempty"`
 }

nodejs/src/client.ts

@@ -836,6 +836,7 @@ export class CopilotClient {
                 infiniteSessions: config.infiniteSessions,
                 gitHubToken: config.gitHubToken,
                 remoteSession: config.remoteSession,
+                cloud: config.cloud,
             });
 
             const { workspacePath, capabilities } = response as {

nodejs/src/index.ts

@@ -21,6 +21,8 @@ export type {
     CommandContext,
     CommandDefinition,
     CommandHandler,
+    CloudSessionOptions,
+    CloudSessionRepository,
     AutoModeSwitchHandler,
     AutoModeSwitchRequest,
     AutoModeSwitchResponse,