Skip to content

feat: support Windows SSH hosts - #5082

Draft
7Sageer wants to merge 9 commits into
mainfrom
kap-ssh-windows
Draft

7Sageer wants to merge 9 commits into
mainfrom
kap-ssh-windows

Conversation

@7Sageer

@7Sageer 7Sageer commented Nov 19, 2026 •

Copy link
Copy Markdown
Collaborator

Requirement or Bug

SSH Full-Remote(#4784)已经支持从 Desktop 和 Web 通过 SSH 在远端运行 KAP。Windows OpenSSH 主机此前会进入 POSIX 启动路径,无法完成连接。本 PR 支持预装兼容版本 Kimi 的 Windows SSH 主机,并保留现有 POSIX 主机的启动方式。

Bug Reproduction Steps

N/A

Root Cause

N/A

Code Changes

SSH bridge 只缓存探测确认的平台。平台无法确认时,bridge 会先尝试原来的 POSIX 启动命令,受限主机仍可沿用现有的命令白名单。探测遇到未分类的 SSH 错误时,如果回退启动只返回执行器找不到或不兼容,且未报告 Kimi 版本,bridge 会保留 SSH 失败并在重连时重新探测。Windows 通过 PowerShell 和 CIM 启动独立于 SSH 会话的 daemon,每个数据目录对应一个稳定的 named pipe。

flowchart LR
    Client[Desktop / Web] --> Bridge[本机 KAP Host Bridge]
    Bridge --> Detect{远端平台探测}
    Detect -->|确认 POSIX| Unix[原启动命令与私有 Unix socket]
    Detect -->|探测无结论| Fallback[尝试原 POSIX 启动命令]
    Fallback -->|握手成功| Unix
    Fallback -->|SSH 探测失败且回退启动未识别执行器| Retry[重连时重新探测]
    Retry --> Detect
    Detect -->|Windows| Win[PowerShell 与 CIM]
    Win --> Pipe[Named pipe 与预共享密钥 TLS]
    Unix --> Kap[远端 KAP]
    Pipe --> Kap
Loading

Windows 的 CLI 与 daemon 读取当前账户私有目录中的同一份随机 IPC 密钥。TLS 验证双方后才转发 Host RPC。CIM 命令从标准输入获取,所需环境由 PowerShell 进程直接提供。密钥通过同目录原子移动发布,初始化无需硬链接。

  • sshKapBridge.ts 包含平台探测、重试、POSIX 回退和 Windows 版本检查。
  • ensure-daemon.ts 与 windows-daemon.ts 包含 daemon 复用、Windows 私有密钥和 CIM 启动。
  • ipcTls.ts 与 stdioRpc.ts 将 TLS 接到现有 Host RPC。

Behavior Changes and Affected Users

行为 改动前 改动后 受影响人群 退路
Windows OpenSSH 连接 使用 POSIX 启动命令,Windows 主机无法建立会话 使用 PowerShell、默认 ~/.kimi-code/bin/kimi.exe 和 named pipe,支持自定义 remote_bin 在 Desktop 或 Web 配置 Windows SSH 主机的用户 升级远端 Kimi,或用 remote_bin 指向兼容版本
POSIX 连接及重连 直接执行原启动命令 首次连接先探测平台。探测被受限 shell 拒绝或无法识别平台时,仍尝试原启动命令,覆盖退出码 255 和 Permission denied Linux、macOS、自定义 remote_bin 或受限 shell 用户 受限 shell 继续允许原启动命令即可
Windows 瞬时 SSH 故障恢复 Windows 主机无法建立会话 首次探测遇到未分类的 SSH 错误时,回退路径不会缓存为 POSIX,后续重连可以识别 Windows 首次连接时网络暂时中断的 Windows SSH 主机用户 网络恢复后自动重连
Desktop 集成终端 Windows SSH 主机无法建立项目会话 可以打开远端项目,集成终端暂不支持该主机。中英文指南均说明系统终端的连接方式 使用 Desktop 打开 Windows SSH 项目的用户 在系统终端中通过 SSH 连接主机
旧版 Windows Kimi 通用启动失败 显示 executor_outdated 提示 使用旧版远端 Kimi 的 Windows 用户 在远端升级 CLI
Windows IPC SSH Host 启动没有 Windows IPC 路径 使用当前账户私有密钥双向认证并加密,握手成功后转发 RPC Windows daemon 与同账户的 SSH 启动进程 使用当前账户的私有目录初始化密钥
SSH agent forwarding POSIX 通过 socket symlink 转发 POSIX 继续转发,Windows 用户在远端配置 Git 等工具的凭据 使用 SSH agent 的 POSIX 用户与新增的 Windows 主机用户 Windows 使用远端账号自身的凭据

Desktop 和 Web 沿用现有 Host API。Windows 能力通过内部启动标记 windows_ipc 通告,会话和项目继续存放在远端。

Linux 测试覆盖 Windows 首次探测失败后的自动重连、受限 POSIX shell 返回 255 后的回退、Windows 平台签名、旧版升级提示,以及通过生产服务验证专用 IPC 密钥。新实现仍需在 Windows OpenSSH 真机复验双账户隔离、并发冷启动和 SSH 断连后的 daemon 复用。

验证详情
  • 本次修订运行 hosts.test.ts 和 web.test.ts,共 145 项通过,Windows 专用的并发密钥用例在 Linux 跳过。3 个新增用例在前一版复现了这两类问题。
  • 本次修订的 pnpm lint、kap-server 类型检查和双语文档构建通过。此前的 CLI 类型检查和 PowerShell 脚本语法检查通过。
  • 此前扩跑中的 Web token 轮换与并发登出单独复跑通过。搜索索引的只读刷新用例和两项延迟阈值用例复跑仍失败。
  • 此前的 Windows 11、PowerShell 5.1 和 OpenSSH 真机验收覆盖默认路径、含空格的 remote_bin、文件和 Bash 操作、并发连接及断连恢复。该轮验收早于 TLS 和密钥存储调整。

Checklist

  • I have read the CONTRIBUTING document.
  • Related context is linked in feat: run a full server on SSH hosts #4784.
  • I have added tests that prove my feature works.
  • The behavior-change table above is complete, and every removed behavior or flipped default is named in the changeset and either has an escape hatch or was explicitly approved by a maintainer in this PR.
  • Ran gen-changesets skill, or this PR needs no changeset.
  • Ran gen-docs skill, or this PR needs no doc update.

@changeset-bot

changeset-bot Bot commented Nov 19, 2026 •

Copy link
Copy Markdown

🦋 Changeset detected

Latest commit: 5a63ad1

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 3 packages
Name Type
kimi-code-app Minor
@moonshot-ai/kap-server Minor
@moonshot-ai/kimi-code Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

@7Hanrui

7Hanrui commented Nov 19, 2026

Copy link
Copy Markdown
Contributor

@codex review

@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Nov 19, 2026 •

Copy link
Copy Markdown
Codex Review Summary: ✅ Completed

This comment shows the latest Codex review activity on this pull request.

Review Status Commit Review trigger
📝 Code Review ✅ Completed 2026-11-20T07:35:59.228488Z 5a63ad1 Manual request
ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: dfe3820875

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

}

private platform(): Promise<SshPlatform> {
this.platformValue ??= this.detectPlatform();

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P1 Badge Clear rejected platform probes before reconnecting

When the first platform probe fails with a retryable SSH error such as connection_refused or connect_timeout, platformValue permanently retains the rejected promise. Although establish() starts the reconnect loop, every retry reuses that rejection instead of executing detectPlatform() again, so an SSH host that was temporarily unavailable during its first connection can never recover without recreating the bridge. Clear the cached promise on rejection so the existing reconnect behavior can perform a fresh probe.

AGENTS.md reference: AGENTS.md:L115-L117

Useful? React with 👍 / 👎.

}

private async detectPlatform(): Promise<SshPlatform> {
const probes = ['uname -s', powerShellCommand("[Console]::WriteLine('KIMI_WINDOWS')")];

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P1 Badge Preserve POSIX hosts that reject platform probes

Every SSH host must now successfully run either uname -s or the PowerShell probe before the previously supported Kimi bootstrap command is attempted. A hardened POSIX host whose authorized_keys wrapper or restricted shell permits the existing kimi --version; kimi server ensure-daemon command but rejects arbitrary commands will therefore fail in detectPlatform() and become completely unreachable after this upgrade. Fall back to the former POSIX bootstrap path when neither probe identifies Windows, rather than making these new probes mandatory for existing hosts.

AGENTS.md reference: AGENTS.md:L115-L117

Useful? React with 👍 / 👎.

@7Hanrui

7Hanrui commented Nov 19, 2026

Copy link
Copy Markdown
Contributor

@codex review

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 32cdc33ced

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

const report = (payload: Record<string, unknown>): void => {
process.stdout.write(
`${ENSURE_DAEMON_MARKER}${JSON.stringify({ protocol: HOST_PROTOCOL_VERSION, api_level: HOST_API_LEVEL, version: getVersion(), ...payload })}\n`,
`${ENSURE_DAEMON_MARKER}${JSON.stringify({ protocol: HOST_PROTOCOL_VERSION, api_level: HOST_API_LEVEL, version: getVersion(), windows_ipc: process.platform === 'win32' ? true : undefined, ...payload })}\n`,

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Keep the probe assertion valid on Windows

When this test suite runs on Windows, the newly added windows_ipc field serializes as true, but apps/kimi-code/test/cli/web/web.test.ts still uses an exact equality assertion expecting only protocol, api_level, and version. The Windows test run therefore fails at that assertion before exercising the new SSH support; update the expected payload conditionally or add a Windows-specific assertion.

Useful? React with 👍 / 👎.

@7Hanrui

7Hanrui commented Nov 19, 2026

Copy link
Copy Markdown
Contributor

@codex review

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 390f5e772b

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

Comment on lines +85 to +88
const handle = await open(tokenPath, 'wx', 0o600);
try {
const token = randomBytes(32).toString('base64url');
await handle.writeFile(token);

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Create the IPC token atomically

When two first-time Windows SSH connections start concurrently, the second process can observe EEXIST after the first creates the token file but before writeFile completes, then read an empty token and fail before the daemon lock is acquired. A process interruption in the same interval leaves a permanently empty file, causing every subsequent connection to fail. Write a temporary file and rename it atomically, or retry/recover when the existing file is empty.

Useful? React with 👍 / 👎.

@@ -0,0 +1,5 @@
---
"@moonshot-ai/kimi-code": minor

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Add the kap-server release entry

This changes runtime source in @moonshot-ai/kap-server, including SSH bootstrap and IPC transport behavior, but the changeset versions only @moonshot-ai/kimi-code. The repository's changeset policy requires a library entry whenever library source changes, so omitting this package prevents its version history from recording the new behavior.

AGENTS.md reference: AGENTS.md:L113-L113

Useful? React with 👍 / 👎.

Comment on lines +71 to +73
if (platform === 'win32') {
const hash = createHash('sha256').update(homeDir).digest('hex').slice(0, 16);
return `\\\\.\\pipe\\kimi-daemon-${hash}`;

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P1 Badge Authenticate the named-pipe server

On Windows, another local account can bind this predictable pipe name before the real daemon starts; connectUnixSocket then sends that endpoint the persistent IPC token before receiving any proof of the server's identity. A squatting process can reply with ipc.auth.ok, capture the token, and impersonate or later access the daemon while controlling the relayed Host RPC stream. Use mutual challenge-response or verify the pipe server's Windows identity instead of relying only on client-to-server authentication.

Useful? React with 👍 / 👎.

Comment thread packages/kap-server/src/start.ts Outdated
app,
wssV1,
wssDebug,
validateCredential: process.platform === 'win32' ? validateCredential : undefined,

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Match the IPC token before bcrypt validation

When the Windows host has KIMI_CODE_PASSWORD configured, a valid IPC token first misses the ordinary bearer token and runs the cost-12 bcrypt password comparison before createCredentialValidator checks rpcToken. The new IPC handshake has a hard two-second timeout, so a slow or busy host can reject the correct persistent token and make every SSH connection fail; check the dedicated RPC token synchronously before invoking password validation.

AGENTS.md reference: AGENTS.md:L115-L117

Useful? React with 👍 / 👎.

@7Hanrui

7Hanrui commented Nov 19, 2026

Copy link
Copy Markdown
Contributor

@codex review

@chatgpt-codex-connector

Copy link
Copy Markdown

Codex Review: Didn't find any major issues. You're on a roll.

Reviewed commit: 892a584f9b

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

@7Hanrui

7Hanrui commented Nov 19, 2026

Copy link
Copy Markdown
Contributor

@codex review

@chatgpt-codex-connector

Copy link
Copy Markdown

Codex Review: Didn't find any major issues. Already looking forward to the next diff.

Reviewed commit: e063cd8349

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

@7Hanrui

7Hanrui commented Nov 19, 2026

Copy link
Copy Markdown
Contributor

@codex review

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 9cbfcf6caa

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

@@ -0,0 +1,5 @@
---
"@moonshot-ai/kimi-code": minor

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Add a desktop changeset for the embedded feature

This feature is explicitly documented for Desktop (docs/en/guides/web.md:71), whose server embeds @moonshot-ai/kap-server via apps/desktop/src/main/server/embedded-server.ts:62, so the user-perceivable library change also requires a separate kimi-code-app changeset. With only the CLI package listed here, Desktop release notes omit the new Windows SSH capability.

AGENTS.md reference: AGENTS.md:L113-L113

Useful? React with 👍 / 👎.

@7Hanrui

7Hanrui commented Nov 19, 2026

Copy link
Copy Markdown
Contributor

@codex review

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 0d7a49f03d

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

Comment on lines +343 to +346
if (result.code === null || result.code === 255) {
const error = sshFailure(result);
if (error.failure !== 'unknown') throw error;
break;

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P1 Badge Retry unknown SSH transport failures before caching POSIX

When an initial Windows probe ends with an unclassified SSH transport error using exit code 255, such as kex_exchange_identification: read: Connection reset by peer, this break converts the failure into a successful POSIX detection. The rejection handler therefore never clears platformValue, and every reconnect reuses posix and sends shell syntax that the Windows host cannot execute, preventing recovery until the bridge is recreated. Avoid caching the POSIX fallback reached through an unknown 255 exit, or rerun detection after the resulting bootstrap failure. This is fresh evidence beyond the prior rejected-promise issue: the current catch only handles probe failures that are thrown.

Useful? React with 👍 / 👎.

@7Hanrui

7Hanrui commented Nov 20, 2026

Copy link
Copy Markdown
Contributor

@codex review

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 5a63ad119b

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

Comment on lines +70 to +71
const hash = createHash('sha256').update(homeDir).digest('hex').slice(0, 16);
return `\\\\.\\pipe\\kimi-daemon-${hash}`;

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Prevent other users from reserving the daemon pipe

On multi-user Windows hosts, this deterministic name is derived only from the generally guessable data-directory path and lives in the machine-wide named-pipe namespace. Another local account can bind it before Kimi starts; connectDaemonSocket then reaches that server, fails the PSK handshake, and rejects immediately, so findOrStart never launches the legitimate daemon. The TLS change prevents token theft but still permits a persistent denial of Windows SSH connections; make the pipe name secret-derived or enforce an owner-only pipe ACL/creation mechanism.

Useful? React with 👍 / 👎.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants