Benefits of Using Remote and Cloud Sessions with the Copilot SDK

Remote and cloud sessions expose Copilot SDK sessions through GitHub Mission Control, enabling real-time collaboration and scalable compute without requiring application code changes.

The Copilot SDK (github/copilot-sdk) provides two complementary mechanisms—remote sessions and cloud sessions—to make your agent sessions accessible beyond the local runtime. Remote sessions let you share live debugging sessions from your workstation, while cloud sessions offload execution to GitHub’s managed infrastructure for server-side automation.

Understanding Remote Sessions

Remote sessions keep the Copilot agent running on the same machine where you instantiate the SDK—whether that is a developer workstation, CI runner, or self-hosted server. Instead of moving the compute, the SDK publishes a shareable URL that points to the live session in Mission Control.

This architecture makes it possible to inspect, debug, or hand off a session to collaborators without interrupting local execution. Anyone with the URL or QR code can view real-time output while the session continues to run on your hardware. According to docs/features/remote-sessions.md, this approach is ideal when the execution environment must remain local but visibility needs to be shared.

How Remote Sessions Work

When you enable remote access, the SDK establishes a secure tunnel to GitHub Mission Control and emits a session.info event containing the public URL. The event model remains identical to local sessions—session.start, assistant.*, and other events fire as usual—so no refactoring is required to support remote observers.

Code Example: Enabling Remote Access

You can configure a client to always enable remote sessions at initialization:

import { CopilotClient } from "@github/copilot-sdk";

const client = new CopilotClient({ remote: true });
const session = await client.createSession({
  workingDirectory: "/path/to/github-repo",
  onPermissionRequest: async () => ({ allowed: true }),
});

session.on("session.info", (e) => {
  if (e.data.infoType === "remote") console.log("Remote URL:", e.data.url);
});

Alternatively, toggle remote access dynamically using the RPC interface:

from copilot import CopilotClient

client = CopilotClient()
session = await client.create_session(
    working_directory="/path/to/github-repo",
    on_permission_request=lambda _: {"allowed": True},
)

# Enable remote sharing later

result = await session.rpc.remote.enable()
print("Remote URL:", result.url)

# Disable when done

await session.rpc.remote.disable()

Understanding Cloud Sessions

Cloud sessions run the actual Copilot agent on GitHub-hosted compute rather than local infrastructure. By passing the cloud option to createSession, you offload the workload to GitHub’s servers while retaining access via Mission Control.

As documented in docs/features/cloud-sessions.md, this model provides the scalability and security of GitHub’s managed infrastructure, removes local resource constraints, and enables server-side, multi-tenant scenarios such as automated code review bots, CI pipelines, or SaaS integrations.

Cloud Session Architecture

Cloud sessions leverage the Copilot-Integration-Id header for routing, as detailed in docs/setup/multi-tenancy.md. They respect organization policies (for example, policy_blocked entitlements) and support fine-grained access controls that are enforced server-side. Because the compute runs in the cloud, you can serve multiple concurrent users without provisioning local machines for each session.

Code Example: Creating Cloud Sessions

To create a cloud-backed session in Go, specify the Cloud field in your session configuration:

client, _ := copilot.NewClient(nil)
session, _ := client.CreateSession(ctx, &copilot.SessionConfig{
    Cloud: &copilot.CloudSessionOptions{
        Repository: &copilot.CloudSessionRepository{
            Owner:  "github",
            Name:   "copilot-sdk",
            Branch: "main",
        },
    },
    OnPermissionRequest: func(_, _ copilot.PermissionInvocation) (rpc.PermissionDecision, error) {
        return &rpc.PermissionDecisionApproveOnce{}, nil
    },
})

You can retrieve the Mission Control URL from either session type using the same event listener pattern:

session.on("session.info", (e) => {
  if (e.data?.infoType === "remote") {
    console.log("Mission Control URL:", e.data.url);
  }
});

Comparing Benefits and Capabilities

Both session types share several core advantages, but they differ in scalability and policy enforcement.

Shared capabilities:

• Immediate access from GitHub UI – Generate a QR code or shareable link instantly via Mission Control.
• No code changes to switch modes – Toggle between local and remote by setting remote: true or cloud: {...} in your configuration.
• Consistent SDK event model – Events like session.info, session.start, and assistant.* work identically across both modes.
• Existing authentication – Both session types leverage your GitHub token or logged-in CLI identity for security.
• Resume support – Either kind of session can be resumed later using the standard SDK resume API described in docs/features/session-persistence.md.

Cloud-exclusive benefits:

• Scalable compute – Execution occurs on GitHub’s infrastructure, freeing local resources.
• Fine-grained entitlement control – Cloud sessions respect organization policies such as policy_blocked, enabling compliance in enterprise environments.

When to Use Each Session Type

Choose remote sessions when the execution environment is already appropriate for the workload—for example, when a developer is debugging locally on a workstation with specific dependencies—but you need to share the live view with teammates or stakeholders. Remote sessions are also useful in CI runners where the build environment must remain on-premises but logs need to be visible to remote team members.

Choose cloud sessions when the workload should run in a managed, scalable environment or when you need to execute code on behalf of many users without provisioning local machines. Cloud sessions excel in automated scenarios like code review bots, SaaS integrations, or multi-tenant applications where each user request spawns an isolated agent instance. For implementation patterns, refer to nodejs/docs/examples.md.

Summary

• Remote sessions run locally and publish a shareable Mission Control URL, enabling real-time collaboration without moving compute.
• Cloud sessions execute on GitHub-hosted infrastructure, providing scalability, policy enforcement, and support for server-side automation.
• Both modes use identical event models and authentication flows, allowing you to switch between them by changing configuration flags rather than application logic.
• Resume functionality works uniformly across both session types via the standard SDK API.

Frequently Asked Questions

What is the difference between remote and cloud sessions in the Copilot SDK?

Remote sessions execute on your local machine or self-hosted runner but expose a public URL through Mission Control, allowing others to view the session remotely. Cloud sessions run the Copilot agent on GitHub’s managed servers, offloading compute entirely while providing the same Mission Control interface. The choice depends on whether you need to preserve the local environment (remote) or require scalable, policy-controlled infrastructure (cloud).

How do I switch between local and remote sessions without changing code?

You can toggle between modes by passing configuration options to the CopilotClient constructor or session creation method. Set remote: true to enable remote tunneling, or provide a cloud: {...} object to move execution to GitHub’s servers. The SDK event model—session.info, session.start, and assistant.* events—remains unchanged, so your application logic requires no modification.

Can cloud sessions respect organization policies and entitlements?

Yes. Cloud sessions enforce fine-grained entitlement controls such as policy_blocked at the server level, ensuring compliance with enterprise security policies. This is documented in docs/features/cloud-sessions.md and leverages the Copilot-Integration-Id header for multi-tenant routing as described in docs/setup/multi-tenancy.md.

How do I resume a remote or cloud session later?

Both session types support the standard SDK resume API outlined in docs/features/session-persistence.md. You can persist session identifiers and later reconstruct the session state using the same resume methods regardless of whether the original session was local, remote, or cloud-based.

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