cplieger/web-terminal-kiro

Kiro的Web终端

一个极简的Kiro CLI浏览器终端：在浏览器标签页（桌面或手机）中运行kiro-cli。每个标签页通过实时PTY流拥有独立的kiro-cli会话，并原生渲染其终端UI，无聊天层、历史存储或中间转换，与SSH会话体验一致。

⚠️ 注意：这是远程shell

浏览器标签页是一个交互式shell，可访问/workspace下的文件和kiro-cli存储的凭据。任何能访问端口的人都可使用，且无内置认证。对外暴露前，建议：

• 置于带认证的反向代理后（如Caddy forward-auth、oauth2-proxy、Authentik）；
• 将端口绑定到本地回环或私有网络。 服务器启动时若绑定非回环地址，会记录警告日志。

运行方式

yaml
# compose.yaml
services:
  web-terminal-kiro:
    image: ***-ghcr.xuanyuan.run/cplieger/web-terminal-kiro:latest
    ports:
      - "9848:9848"
    volumes:
      - ./config:/config        # kiro-cli认证、工具、设置
      - ./workspace:/workspace  # 你的代码仓库
    restart: unless-stopped

打开http://localhost:9848。首次启动时，kiro-cli会引导设备码登录流程：打印URL和一次性代码，在任意浏览器（如手机）中打开URL并输入代码即可登录。每个标签页是独立会话。

该镜像以root用户运行，确保git、gh和SSH正常工作；不要添加user:配置，挂载目录下的文件会是root所有。

配置说明

镜像默认配置已可用，多数场景只需设置端口和卷。

• 端口：9848（HTTP + WebSocket）；
• 卷：/config持久化认证、工具和设置；/workspace为工作目录；
• 健康检查：仅当服务器启动且kiro-cli可运行时，健康状态为正常。

kiro-cli在首次启动时下载（未内置）；更新版本需拉取新镜像标签。

反向代理设置

无内置认证，建议通过反向代理终止TLS并添加登录验证。以下是Caddy基础认证配置：

caddyfile
webterm.example.com {
    basic_auth {
        # 使用`caddy hash-password`生成哈希
        alice $2a$14$...
    }
    reverse_proxy 127.0.0.1:9848
}

代理后需设置TRUSTED_PROXIES以记录真实客户端IP（如TRUSTED_PROXIES=10.0.0.0/8）。

核心功能

• 真实终端体验：支持16/256/24位真彩色、文本属性、鼠标操作、OSC 8超链接；
• 触摸优化：多标签管理、屏幕键盘（Tab/Esc/箭头等）、原生文本选择；
• 会话恢复：网络中断或睡眠后自动重连，重播屏幕和滚动历史；
• 全功能兼容：支持vim/htop等全屏应用，保留滚动历史；
• 工具管理：通过/config/tools.json配置工具，自动安装依赖（如语言服务器）。

工具管理

镜像内置kiro-cli、git和基础工具，其他工具通过/config/tools.json配置：

jsonc
{
  "version": 2,
  "tools": {
    "typescript-language-server": { "disabled": false }, // 启用TypeScript LSP
    "gh": { "disabled": true } // 禁用GitHub CLI
  }
}

启用的工具会安装到/config/tools/，语言服务器自动被kiro-cli代码智能功能识别。

许可证

GPL-3.0。详见https://github.com/cplieger/web-terminal-kiro/blob/main/LICENSE。