Skip to main content

Sessions, host, and environment

Scope: ServerRpc (server-wide operations tied to the Client) For an overview of RPC and the list of all RPC pages, see RPC.

Runtime and host lifecycle (experimental)

host.unpublishSession() withdraws an application publication from a running host you own. Unpublishing doesn’t delete or stop the original session history, worktree, or running work. If the session is already unpublished, unpublished is false, and publications other than application raise an error.
host.dispose() disposes of a host listener by hostId.
host.setSessionCreationPolicy() toggles whether a running host accepts new remote sessions. The change doesn’t disconnect existing clients and applies only to later admissions.
For a stdio runtime started by the SDK, Client::stop() calls runtime.shutdown after disconnecting sessions and before closing the JSON-RPC connection and the process. Session detaches (session.detach) share a single 10-second deadline across all sessions; a detach that misses the deadline is included in the return value as an error, and shutdown continues. It also waits up to 10 seconds for runtime cleanup to finish; on failure, it includes the error in the return value and continues with the rest of the shutdown. For connections to an external runtime such as cli_url, this RPC isn’t called so the shared runtime isn’t terminated. If the CLI can’t identify the matching request and returns a JSON-RPC error with id: null, every in-flight request fails with a JsonRpcException. The exception includes a diagnostic message with quoted values removed and its length capped. The connection stays open. Because the CLI may already have processed the request, don’t retry automatically without confirming that it’s safe. The SDK rejects outgoing requests nested deeper than 127 levels, which the CLI can’t read, before sending them. It replaces handler responses that are nested too deeply with a JSON-RPC error.

cloudTasks (experimental: cloud agent tasks)

cloudTasks() creates, deletes, and gets cloud coding agent tasks, retrieves session logs and replays, changes sharing state, and resolves the session to open from a task ID. Each method accepts the matching Params type or an array and returns a typed DTO. When ok on a create result is false, check reason and message for why the service declined the request, and statusCode, errorMessage, and errorPayloadJson for a failed HTTP request.

taskAnalytics (experimental: classify recorded trajectories)

taskAnalytics()->classifyTrajectory() classifies recorded Copilot events or ATIF data without creating a session. Archived tools aren’t executed, and nothing is added to conversation history or classification telemetry. Pass events in their original order. You can also set classifiers, maxConcurrentRequests, judge, and previousResult. With validateOnly: true, the runtime skips inference and returns only the local validation result. A normal classification sends the event content to model processing that uses your GitHub CAPI credentials. There is no automatic redaction or prompt injection protection. Approve the upload, verify where the archive came from, and remove sensitive data first. Classification results aren’t trusted facts, so don’t use them for authorization or security decisions.
To open an authentication URL in the browser, use runtime()->openBrowser().
To get the sandbox path grant warning, use sandbox()->getPathGrantWarning().

sessions connect and Remote Control (TCP mode)

To connect the CLI server to an existing remote session, use sessions()->connect(). Pass the remote sessionId, and the result contains the SDK-side sessionId and the remote session’s metadata.
In TCP mode, you can also use sessions() to manage a single Remote Control for the whole runtime. Unlike the per-session remote()->enable(), these methods let you start, stop, and transfer Remote Control between sessions, and read its current status.
For details, see Remote Sessions.
Last modified on November 19, 2026