kiro-lan-remote

English · 中文

English

A standalone LAN gateway for viewing and interacting with local Kiro Agent sessions from a browser.

The project runs on a Windows host: the Node.js server connects to the local Kiro Agent Mux, while a phone or another browser on the LAN connects to the server over WebSocket. It provides session browsing, live conversations, history replay, task cancellation, permission approval, and reconnect recovery.

Security notice: This project can drive the local Kiro Agent to read and write files and execute commands. It is intended for trusted LAN environments only. Use a random access key and stop the server when it is not needed.

Features

• Access Kiro Agent sessions from a browser on the local network
• Session lists grouped by workspace
• Live streaming responses, reasoning progress, and tool calls
• Tool output, diffs, and terminal output
• Create sessions, send messages, and cancel the current task
• Forward permission requests for approval on a phone
• session.load history replay
• Incremental recovery after disconnects through events.resume
• Isolation between replay and live frames, preventing another connection's history load from polluting the current page
• Vue 3 + Pinia state projection architecture
• Single-file Vite build; runtime only requires one HTML artifact

Requirements

• Windows 10 or later
• Node.js 20 or later
• Kiro installed and running on the host machine
• Permission for the current user to inspect the Kiro extension host process

Installation

npm install

Build

The server serves the frontend from public/index.html. Rebuild after changing files under src/:

npm run build

The build produces a single-file artifact:

public/index.html

Start

Start the server directly:

npm start

The server automatically discovers the Kiro extension host and the local Agent Mux, then prints an access URL such as:

http://192.168.x.x:8790/?key=<access-key>

Configuration

Override the default configuration with environment variables:

$env:PORT = "8790"
$env:HOST = "0.0.0.0"
$env:ACCESS_KEY = "replace-with-a-random-secret"
npm start

Common environment variables:

Variable	Default	Description
PORT	8790	HTTP/WebSocket server port
HOST	0.0.0.0	Listen address
ACCESS_KEY	Generated at startup	Browser WebSocket access key; an explicit random value is recommended
PERMISSION_POLICY	ask	Permission policy: ask, allow-once, allow-always, or reject
AUTO_DISCOVER	true	Whether to discover the Kiro Agent Mux automatically
KIRO_MUX_PORT	Empty	Manually specified Mux port
KIRO_MUX_TOKEN	Empty	Manually specified Mux token
MODEL_ID	Empty	Model ID used for new sessions

To specify the Mux manually:

$env:KIRO_MUX_PORT = "64155"
$env:KIRO_MUX_TOKEN = "your-mux-token"
npm start

Development

Start the Vite development server:

npm run dev

The development server listens on port 5174 by default and proxies /ws and /healthz to the backend on port 8790. For normal runtime use, run npm run build followed by npm start.

Testing and checks

# TypeScript / Vue type checking
npm run typecheck

# Unit tests
npm run test:unit

# Build and check the single-file runtime artifact
npm run test:contract

# Integration projection tests
node --test test/integration/projection.test.mjs

# Permission and reconnect-resume contract tests
node --test test/contract-perm-resume.test.mjs

The test suite covers:

• Event routing and session filtering
• Replay / resume semantics
• Turn finalization and idempotency
• Tool-call and duration projections
• Markdown rendering and safe escaping
• Permission request queues
• Event recovery after disconnects
• Vue component SSR smoke rendering

Project structure

kiro-lan-remote/
├─ discover.ps1              # Discover the Kiro extension host and Mux port
├─ memscan.ps1               # Read-only scan for Mux token candidates in process memory
├─ server.mjs                # HTTP/WebSocket gateway
├─ index.html                # Vite source entry
├─ public/index.html         # Single-file runtime artifact generated by Vite
├─ lib/
│  ├─ discover.mjs           # Mux discovery logic
│  ├─ miniws.mjs             # Minimal WebSocket implementation
│  └─ muxClient.mjs          # ACP/Mux client and event normalization
├─ src/
│  ├─ app/                   # Application startup and business-action orchestration
│  ├─ components/            # Vue UI components
│  ├─ composables/           # WebSocket, scrolling, clipboard, and other composables
│  ├─ domain/                # Event routing, turn, and message domain models
│  ├─ protocol/              # Browser-side protocol types and parsing guards
│  ├─ stores/                # Pinia stores
│  └─ utils/                 # Markdown, path, time, and other utilities
├─ test/                     # Unit, integration, contract, and component tests
├─ package.json
├─ tsconfig.json
└─ vite.config.ts

Protocol and permissions

The server connects to the local Kiro Agent Mux as an observer. Browser commands are forwarded through the server. Kiro session/update events are normalized by the server and then projected into Pinia state by the frontend event reducer.

History replay frames are delivered only to the browser connection that requested the corresponding session.load; they are not written to the reconnect buffer. Live events are still broadcast by session, with the frontend filtering them by sessionId. Permission requests are placed in a FIFO queue for the phone by default and forwarded to Kiro after the user makes a choice.

License

This project is licensed under the MIT License.

---

中文

一个用于通过局域网浏览器查看和操作本机 Kiro Agent 会话的独立网关。

项目运行在 Windows 本机上：Node.js 服务端连接本机 Kiro Agent Mux，手机或局域网内其他浏览器通过 WebSocket 连接服务端，完成会话列表、实时对话、历史回放、取消任务、权限确认和断线恢复。

安全提示： 本项目可以驱动本机 Kiro Agent 读写文件和执行命令，仅适合在可信局域网中使用。请使用随机访问密钥，并在不使用时停止服务。

功能

• 通过局域网浏览器访问 Kiro Agent 会话
• 按工作区分组的多会话列表
• 实时流式回答、思考过程和工具调用展示
• 查看工具输出、diff 和终端输出
• 新建会话、发送消息和取消当前任务
• 将权限请求转交手机端确认
• session.load 历史回放
• 通过 events.resume 在断线后增量恢复
• 隔离回放帧与实时帧，避免其他连接的历史加载污染当前页面
• Vue 3 + Pinia 状态投影架构
• Vite 单文件构建，运行时只需要一个 HTML 产物

环境要求

• Windows 10 或更高版本
• Node.js 20 或更高版本
• 本机已安装并运行 Kiro
• 当前用户有权限读取 Kiro 扩展宿主进程信息

安装

npm install

构建

服务端通过 public/index.html 提供前端页面。修改 src/ 后需要重新构建：

npm run build

构建会生成单文件产物：

public/index.html

启动

直接启动：

npm start

服务端会自动发现 Kiro 扩展宿主和本地 Agent Mux，并在控制台输出访问地址，例如：

http://192.168.x.x:8790/?key=<access-key>

自定义配置

可通过环境变量覆盖默认配置：

$env:PORT = "8790"
$env:HOST = "0.0.0.0"
$env:ACCESS_KEY = "请替换为随机密钥"
npm start

常用环境变量：

变量	默认值	说明
PORT	8790	HTTP/WebSocket 服务端口
HOST	0.0.0.0	监听地址
ACCESS_KEY	启动时随机生成	浏览器 WebSocket 访问密钥；建议显式设置随机值
PERMISSION_POLICY	ask	权限策略：ask、allow-once、allow-always 或 reject
AUTO_DISCOVER	true	是否自动发现 Kiro Agent Mux
KIRO_MUX_PORT	空	手动指定 Mux 端口
KIRO_MUX_TOKEN	空	手动指定 Mux token
MODEL_ID	空	新建会话使用的模型 ID

如果手动指定 Mux：

$env:KIRO_MUX_PORT = "64155"
$env:KIRO_MUX_TOKEN = "你的 mux token"
npm start

开发

启动 Vite 开发服务：

npm run dev

开发服务默认监听 5174，并将 /ws 与 /healthz 代理到 8790 后端。正式运行仍应使用 npm run build 后的 npm start。

测试与检查

# TypeScript / Vue 类型检查
npm run typecheck

# 单元测试
npm run test:unit

# 构建并检查单文件运行产物
npm run test:contract

# 集成投影测试
node --test test/integration/projection.test.mjs

# 权限与断线补发契约测试
node --test test/contract-perm-resume.test.mjs

当前代码包含以下主要验证范围：

• 事件路由与会话过滤
• replay / resume 语义
• 回合收尾与幂等性
• 工具调用和耗时投影
• Markdown 渲染与安全转义
• 权限请求队列
• 断线事件补发
• Vue 组件 SSR 冒烟渲染

项目结构

kiro-lan-remote/
├─ discover.ps1              # 发现 Kiro 扩展宿主和 Mux 端口
├─ memscan.ps1               # 只读扫描进程内存中的 Mux token 候选
├─ server.mjs                # HTTP/WebSocket 网关
├─ index.html                # Vite 源入口
├─ public/index.html         # Vite 生成的单文件运行产物
├─ lib/
│  ├─ discover.mjs           # Mux 发现逻辑
│  ├─ miniws.mjs             # 极简 WebSocket 实现
│  └─ muxClient.mjs          # ACP/Mux 客户端和事件归一化
├─ src/
│  ├─ app/                   # 应用启动和业务动作编排
│  ├─ components/            # Vue UI 组件
│  ├─ composables/           # WebSocket、滚动、剪贴板等组合逻辑
│  ├─ domain/                # 事件路由、回合和消息领域模型
│  ├─ protocol/              # 浏览器端协议类型与解析守卫
│  ├─ stores/                # Pinia 状态
│  └─ utils/                 # Markdown、路径、时间等工具
├─ test/                     # 单元、集成、契约和组件测试
├─ package.json
├─ tsconfig.json
└─ vite.config.ts

协议与权限说明

服务端以 observer 角色连接本机 Kiro Agent Mux。浏览器端命令通过服务端转发，Kiro 下发的 session/update 会先在服务端归一化，再由前端事件 reducer 投影到 Pinia 状态。

历史回放帧只投递给发起对应 session.load 的浏览器连接，不写入断线补发缓冲；实时事件仍按会话广播，由前端按 sessionId 过滤。权限请求默认进入手机端 FIFO 队列，由用户选择后转交 Kiro。

许可证

本项目使用 MIT License。