> ## Documentation Index
> Fetch the complete documentation index at: https://ccb.agent-aura.top/llms.txt
> Use this file to discover all available pages before exploring further.

# Lan pipes

# LAN Pipes — 局域网多机器群控指南

## 什么是 LAN Pipes

LAN Pipes 让多台机器上的 Claude Code 实例通过局域网自动发现并协作。你可以在一台机器（main）上操控其他机器（sub）上的 Claude Code，发送 prompt、查看执行结果、审批权限请求——全程零配置。

基于本机 Pipe IPC（`UDS_INBOX`）扩展，新增 TCP 传输层 + UDP Multicast 发现。

## 前置条件

* 两台或以上机器在同一局域网
* 每台机器安装了 CCB 并能 `bun run dev`
* Feature flag `LAN_PIPES`（dev/build 默认开启）
* 防火墙允许 UDP 7101 + TCP 动态端口（见下方配置）

## 快速开始

### 第一步：配置防火墙

**每台机器都需要执行。**

**Windows**（管理员 PowerShell）：

```powershell theme={null}
New-NetFirewallRule -DisplayName "CCB LAN Beacon (UDP)" -Direction Inbound -Protocol UDP -LocalPort 7101 -Action Allow -Profile Private
New-NetFirewallRule -DisplayName "CCB LAN Pipes (TCP)" -Direction Inbound -Protocol TCP -LocalPort 1024-65535 -Program (Get-Command bun).Source -Action Allow -Profile Private
New-NetFirewallRule -DisplayName "CCB LAN Beacon Out (UDP)" -Direction Outbound -Protocol UDP -RemotePort 7101 -Action Allow -Profile Private
```

验证网络为"专用"（非公共）：`Get-NetConnectionProfile`

**macOS**：
首次运行时系统弹出"允许接受传入连接"对话框，点击"允许"。

如果使用 pf 防火墙：

```bash theme={null}
echo "pass in proto udp from any to any port 7101" | sudo pfctl -ef -
```

**Linux**（firewalld）：

```bash theme={null}
sudo firewall-cmd --zone=trusted --add-port=7101/udp --permanent
sudo firewall-cmd --zone=trusted --add-port=1024-65535/tcp --permanent
sudo firewall-cmd --reload
```

**Linux**（iptables）：

```bash theme={null}
sudo iptables -A INPUT -p udp --dport 7101 -j ACCEPT
sudo iptables -A INPUT -p tcp --dport 1024:65535 -m owner --uid-owner $(id -u) -j ACCEPT
```

### 第二步：启动

```bash theme={null}
# 机器 A（例如 192.168.50.22）
bun run dev

# 机器 B（例如 192.168.50.27）
bun run dev
```

启动后等待 3-5 秒（beacon 广播间隔），两边自动发现并连接。

### 第三步：查看和操作

在任一台机器上：

```
/pipes
```

输出示例：

```
pipe: cli-a91bad56 (main) 192.168.50.22  2/3 selected

Main machine: 205d6c3a... (this machine)
  [main] cli-a91bad56  XC/192.168.50.22  [alive] (you)
  ☑ [sub-1] cli-da029538  XC/192.168.50.22  [alive] [connected]

LAN Peers:
  ☐ [main] cli-04d67950  vmwin11/192.168.50.27  tcp:192.168.50.27:58853  [LAN]
```

### 第四步：选中目标并发送任务

1. 按 `Shift+↓` 展开选择面板
2. `↑↓` 移动到 LAN peer
3. `Space` 选中
4. `Enter` 确认
5. 输入 prompt，自动路由到远端执行

远端执行结果会流式回传到你的消息列表：

```
[main vmwin11/192.168.50.27 / cli-04d67950] 正在检查 git status...
[main vmwin11/192.168.50.27 / cli-04d67950] Completed
```

## 完整命令参考

| 命令                          | 说明                                  |
| --------------------------- | ----------------------------------- |
| `/pipes`                    | 显示所有实例（本机 + LAN），Shift+↓ 展开选择面板     |
| `/pipes select <name>`      | 选中某实例                               |
| `/pipes all`                | 全选                                  |
| `/pipes none`               | 取消全选                                |
| `/attach <name>`            | 手动 attach（自动识别 LAN peer 并通过 TCP 连接） |
| `/detach <name>`            | 断开连接                                |
| `/send <name> <msg>`        | 向指定 pipe 发送消息                       |
| `/send tcp:host:port <msg>` | 直接通过 TCP 地址发送                       |
| `/claim-main`               | 强制声明为 main                          |
| `/pipe-status`              | 显示详细状态                              |
| `/peers`                    | 列出所有已发现的 peer                       |

## 快捷键

| 快捷键       | 场景         | 作用           |
| --------- | ---------- | ------------ |
| `Shift+↓` | 状态栏可见时     | 展开/收起选择面板    |
| `↑ / ↓`   | 面板展开时      | 移动光标         |
| `Space`   | 面板展开时      | 选中/取消        |
| `Enter`   | 面板展开时      | 确认关闭         |
| `Esc`     | 面板展开时      | 取消关闭         |
| `← / →`   | 有选中 pipe 时 | 切换路由模式       |
| `M`       | 面板展开时      | 同 ←/→ 切换路由模式 |

## 路由模式

| 模式                    | 显示 | 行为                        |
| --------------------- | -- | ------------------------- |
| `selected pipes only` | 绿色 | prompt 仅发送到选中的 pipe，本地不执行 |
| `local main`          | 灰色 | prompt 仅在本地执行，不转发         |

切换路由模式不会清空选择。

## 权限转发

当远端 slave 执行需要权限的工具（如 BashTool）时：

1. slave 发送 `permission_request` 到 main
2. main 弹出权限确认对话框，显示 `[role hostname/ip / pipeName]`
3. 用户确认/拒绝
4. 结果发回 slave，继续或中断

## 工作原理

### 发现机制

* 每台机器启动时创建 UDP multicast beacon
* 组地址 `224.0.71.67`，端口 `7101`，TTL=1（不跨路由器）
* 每 3 秒广播一次自身信息（pipeName、IP、TCP 端口、角色）
* 15 秒未收到广播则标记 peer 丢失

### 通信机制

* 本机实例：UDS（Unix Domain Socket / Named Pipe）
* 跨机器：TCP（动态端口，通过 beacon 发现）
* 协议：NDJSON（每行一个 JSON 对象）
* 消息类型：ping/pong、attach/detach、prompt/stream/done/error、permission

### 角色模型

| 角色       | 说明                     |
| -------- | ---------------------- |
| `main`   | 首个启动的实例                |
| `sub`    | 同机后续启动的实例              |
| `master` | attach 了至少一个 slave 的实例 |
| `slave`  | 被 master attach 的实例    |

跨机器 attach 时，两边都可以是 main——不要求对方必须是 sub。

## 常见问题

### 看不到 LAN peer

1. 检查防火墙是否放行 UDP 7101
2. `Get-NetConnectionProfile`（Windows）确认网络为"专用"
3. 确认两台机器在同一子网（`ping` 能通）
4. 路由器未开启 AP 隔离

### 连接超时

1. 检查 TCP 入站防火墙规则
2. 确认没有 VPN 劫持流量
3. 尝试 `/send tcp:ip:port hello` 直接测试

### beacon 绑到了错误网卡

Windows 上 WSL/Docker 虚拟网卡可能劫持 multicast。beacon 会自动选择非内部 IPv4 接口。如果选错，检查 `getLocalIp()` 返回值。

## 安全说明

* TCP 连接当前**无认证**——同 LAN 内知道端口号即可连接
* Multicast TTL=1，不跨路由器
* AI 通过 `SendMessageTool` 发送 `tcp:` 消息时需**用户显式确认**
* 建议仅在信任的局域网中使用