Field noteNov 20, 20265 min read1 source

Multi-tenancy and Server Deployments (Copilot SDK docs)

In one minute

GitHub’s Copilot SDK documentation sets out how to run the SDK in a backend serving multiple users, tenants, or workspaces. Its practical guidance centers on explicit tool access, session-scoped identity, and deliberate separation of runtime and session storage—decisions that shape whether an embedded agent can be safely operated as a shared service.

What changed: The documentation adds multi-tenant server deployment patterns and security guidance for the Copilot SDK.

What happened

GitHub’s guide, “Multi-tenancy and server deployments,” defines multi-user server mode as running the Copilot SDK from backend code that serves more than one human, tenant, workspace, or integration account. The application owns request routing and authorization; the SDK and runtime provide per-session state, per-session authentication, and explicit tool registration. GitHub identifies SaaS products, partner integrations, internal platforms, and concurrent-user backends as intended settings. It distinguishes this SDK-level guide from its companion scaling guide, which covers topology, load balancing, and storage patterns.

The recommended baseline for a shared server is mode: "empty". GitHub says this disables optional CLI-style behavior and requires the application to decide which tools, MCP servers, skills, and workspace paths each session can access. It warns against mode: "coding-agent" on shared servers because that mode can expose ambient host filesystem capabilities. Examples in TypeScript, Python, Go, .NET, Java, and Rust create sessions with unique identifiers, a selected model, an explicit tool allowlist, and user-scoped GitHub credentials. The documented sample tools include custom:lookupOrder and custom:createTicket.

Authentication and runtime configuration have separate scopes. GitHub recommends setting a token on each session when GitHub access should represent the requesting user; a client-level token instead authenticates the runtime process. For short-lived credentials, the guide prefers a rotating provider over a static token when rotation is needed. A RuntimeConnection.forTcp(host, port) connection lets SDK clients attach to an already-running runtime. In that arrangement, process-level settings—including storage location and idle timeout—belong on the runtime server, while user-specific tokens can be passed when creating or resuming sessions.

The guide also describes storage and cleanup choices. sessionIdleTimeoutSeconds cleans up inactive sessions; GitHub suggests 15 to 30 minutes as a starting point for chat backends, while workflow agents may need a longer timeout and explicit deletion when the workflow finishes. baseDirectory sets COPILOT_HOME for a runtime instance and can isolate runtime state, credentials, and session data by process, pod, worker, or tenant boundary. A sessionFs provider routes session file I/O through application storage rather than local disk, useful when disks are ephemeral or tenant-aware storage paths are required. The guide stresses that consent files and session transcripts need the same isolation care as other tenant data; sessions sharing a provider namespace can share remembered grants.

What the archive adds

New Runtime’s earlier coverage on 2026-10-31 described the SDK’s transition to Microsoft Copilot SDK and a phased migration. This guide is a new operational fact on that story: it spells out how the SDK should be configured for multi-user server deployments.

Trend signal

This supports agent security moves to runtime boundaries: GitHub’s guidance puts safety in runtime mode, tool registration, session-scoped credentials, storage namespaces, and authorization—not merely in instructions to the agent. The guide is prescriptive documentation rather than evidence that deployments using these controls have been independently tested at scale.

Why now

The guide’s GitHub page identifies a Copilot SDK 2.0.1-preview.0 snapshot updated on November 17, 2026. The multi-tenancy guidance gives teams building on the SDK a more explicit deployment frame as they move from single-user or CLI-like use toward shared backends.

Why it matters

A shared agent backend is not made multi-tenant simply by assigning each request a different conversation ID. Credentials, tools, filesystem access, remembered approvals, session transcripts, and runtime-level configuration can all cross boundaries if they are scoped incorrectly. GitHub’s guide makes those boundaries concrete: begin with an empty capability set, grant tools per session, bind identity to the requesting user, and decide whether state is isolated per runtime, session, or tenant.

The advice also clarifies the operational trade-off between isolation and reuse. A shared runtime can reduce deployment overhead, but it does not remove the application’s responsibility for routing, authorization, storage namespaces, or coordinating concurrent updates to shared approval files. Teams can use these choices as a design checklist before exposing an embedded agent to multiple customers or internal workspaces.

What happens next

  • SDK examples and deployment templates will increasingly treat explicit tool allowlists and session-scoped credentials as the default for shared Copilot backends. (6 months, 70%). Watch for: official samples that continue to use mode: "empty" and per-session identity.

Limits and uncertainty

This is implementation guidance, not a deployment case study: it does not establish that a particular multi-tenant service has adopted the patterns or quantify their security, latency, or cost effects. The application remains responsible for authorization and tenant routing, and the guide’s warnings make clear that storage-provider boundaries require host-side controls in some configurations. Teams should validate isolation in their own runtime topology, especially where multiple processes share backing files or where shell execution can reach storage outside the session filesystem provider.

Skill to build now

Draw a boundary map for one agent-backed endpoint before shipping it to multiple users. Mark which component owns request authorization, runtime-level credentials, per-session tokens, tool allowlists, session state, approval metadata, and transcripts. Then implement the shared-server baseline: an empty mode, a unique session identifier, only the required tools, and a token scoped to the requesting user. If sessions share filesystem storage, test whether approval state can cross the intended tenant boundary.

Reader takeaway

For a multi-user Copilot backend, treat isolation as a set of explicit runtime and storage decisions. Start with mode: "empty", scope identity and tools per session, and ensure session state and remembered approvals use namespaces that match your tenant model.

Evidence / sources

  1. 1github.com/github/copilot-sdk/blob/main/docs/setup/multi-tenancy.md
All Field Notes

Next reads

Read next

Open the graph
  1. 01topicGithubExplore the github topic hub.
  2. 02archiveField NotesOpen the latest editorial analysis.
  3. 03sourcesSourcesSee the original sources this archive cites.
Who read this page?Machine requests, hidden until opened

Loading the privacy-safe route aggregate...

Open the JSON contract