后端与 headless runtime

后端可以独立运行 headless CLI，再让 SDK 通过 TCP 连接。runtime 不按每次 HTTP 请求重新启动，SDK client 也不负责创建该服务进程。多个客户端可共享服务，或放在不同容器中。

启动服务

copilot --headless --port 4321

省略 --port 会选择随机端口并打印 URL。默认仅接受 loopback（127.0.0.1）；需要其他主机连接时，官方支持：

copilot --headless --host 0.0.0.0 --port 4321

非 loopback 监听意味着可路由到该地址的客户端能接触服务，需由部署的私有网络、防火墙、代理与认证保护。不要把 GitHub 模型身份认证误认为已经为这个 TCP 服务提供了完整入口授权。

SDK 连接

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

const client = new CopilotClient({
    connection: RuntimeConnection.forUri("localhost:4321"),
    mode: "empty",
});

快速开始另使用 cliUrl，当前后端专题使用显式 RuntimeConnection.forUri。接入后按正常 API 创建、发送与恢复 session，但共享服务必须提供会话级身份和工具清单，详见多租户配置。

身份与进程配置

服务进程上的环境 token 会成为共享身份，只有产品确实采用服务账户语义时才使用。代表用户执行时，在每个 session 上提供用户 token 或 provider。BYOK 则在 session 中指定模型提供方。

连接已有 runtime 时，client baseDirectory 不会移动服务端状态；应在服务进程上设置 COPILOT_HOME。空闲清理同样需要在独立服务启动时配置，例如 --session-idle-timeout <seconds>。

部署与监测

后端专题说明没有官方预构建 CLI Docker 镜像；其 Dockerfile 演示从官方 release 制作自己的镜像。示例版本是部署样例，不应当作当前最新版或兼容性保证。

容器重启后需保留历史时，将 session state 放在持久存储。client.getStatus() 可用于探测服务；应用还应记录延迟、错误和活跃会话，并在关闭服务前排空在途工作。

清理与示例边界

默认没有 idle timeout，长期服务要显式设置，并按业务生命周期断开或删除会话。disconnect 用于释放活动会话连接；永久清理使用 deleteSession，并先校验用户归属。

官方简化 Express 示例省略部分认证与 resume 配置；正式实现不能信任请求体里的 session ID，也不能把所有 resume 错误都当作“不存在”后直接创建新会话。应用授权与共享边界按多租户专题落实。