# AgentAirlock v0.2.0-beta.2

> **Formerly AgentBridge.** The project was renamed without rewriting Git
> history. Existing `agentbridge_*` MCP tool names remain stable protocol
> identifiers, while managed desktop configuration is migrated to
> `agentairlock`.

> [!WARNING]
> **⚠️ Beta software**
>
> AgentAirlock is under active development. Use it only with test projects and
> non-sensitive files. Real Codex Desktop and Claude Windows App / Claude Code
> MCP integrations have been verified, including bidirectional peer messaging.
> This beta remains Windows-first and does not provide a stable production
> guarantee.

AgentAirlock 是一个完全在本机运行的智能体通信与只读项目共享原型。
v0.2.0-beta.2 在 v0.1 Gateway/权限边界上增加了 Codex Desktop 与 Claude Windows
App / Claude Code 真实适配层。两端的 MCP 注册、独立认证身份和双向 peer 消息均已
真实验证；语义往返轮数限制仍主要依赖客户端指令约束。

现有 AgentBridge 安装可平滑迁移：Gateway 在过渡期继续接受旧
`AGENTBRIDGE_*` 环境变量和 `X-AgentBridge-Client-Id` 请求头；Codex 与 Claude
安装器会在创建备份后，将受管的 `mcp_servers.agentbridge` 或
`mcpServers.agentbridge` 配置迁移为 `agentairlock`。真实 secret 不会写入客户端
配置。

## 当前功能

- 仅监听 `127.0.0.1:17890` 的 Fastify Gateway
- REST、WebSocket 与 MCP Streamable HTTP (`/mcp`)
- SQLite 自动建库/迁移及 repository 层
- `chat_only`、`ask_before_read`、`trusted_read` 三级权限
- 单文件、目录、项目范围的申请；单次和固定分钟有效期
- 安全路径解析、realpath 根目录校验、符号链接/Windows junction 逃逸防护
- 敏感文件、二进制文件、超大文件和疑似凭证内容拒绝
- 安全文件列表、文本读取/搜索、无 shell 的 Git 状态与变更摘要
- React 本地控制面板与管理员批准/拒绝/撤销/紧急断开
- 两个命令行模拟客户端、自动演示和安全/集成/MCP 测试
- 所有消息、授权申请、权限变更和项目读取结果写入结构化审计日志
- Codex 插件 + AgentAirlock Skill，以及 Claude Code MCP/CLAUDE.md 集成
- 适配器 secret 的 scrypt 哈希、轮换、撤销和 re-pair
- 消息大小/频率/未读上限、非可信输入标记和最长 25 秒的受限等待工具

## 安全边界

v0.2.0-beta.2 是本地、只读 Beta：

- Gateway 和控制面板只绑定 `127.0.0.1`，没有公网通信、隧道或遥测。
- 当前不支持远程网络或项目写入；首次安装请只连接测试项目和非敏感文件。
- 所有项目读取统一经过服务端权限引擎和安全路径模块；MCP annotations 只是描述，不是安全边界。
- MCP 没有批准授权、改变权限、撤销他人授权、shell 或文件修改工具。
- 即使 `trusted_read` 也不能创建、修改、删除文件，不能运行命令或安装依赖。
- `.env*`、密钥、令牌、凭据目录、依赖/构建输出和 `.git` 内部文件不返回。
- 管理接口必须携带环境变量中的本地管理员令牌。令牌不会返回给智能体或 MCP 客户端。
- Codex/Claude Code 宿主适配器使用管理员配对的 `clientId + clientSecret`；SQLite
  只存带随机 salt 的 scrypt hash。`agentId + deviceId` 仅保留给明确标记的模拟器。
- adapter identity 和 secret 只应保留在本机，不得提交、复制到文档或与他人分享；泄漏后应立即撤销并重新配对。
- Git 功能使用 `isomorphic-git` 读取仓库并只返回路径/状态矩阵摘要，不执行 Git 或项目命令。

完整威胁模型见 [docs/security-model.md](docs/security-model.md)。

## 要求与安装

- Node.js 22+
- pnpm 11（项目由 Corepack 固定）

```powershell
Set-Location C:\path\to\AgentAirlock
corepack enable
corepack pnpm install
Copy-Item .env.example .env
```

编辑 `.env`，至少设置一个不少于 16 字符、仅用于本机的管理员令牌，并将项目根目录指向允许读取的项目：

```dotenv
AGENTAIRLOCK_HOST=127.0.0.1
AGENTAIRLOCK_PORT=17890
AGENTAIRLOCK_ADMIN_TOKEN=change-this-local-token
AGENTAIRLOCK_DB_PATH=./data/agentairlock.db
AGENTAIRLOCK_PROJECT_ROOT=C:\path\to\TestProject
AGENTAIRLOCK_PROJECT_NAME=Test Project
```

## Windows PowerShell 启动

```powershell
Set-Location C:\path\to\AgentAirlock
corepack pnpm dev
```

- Gateway: `http://127.0.0.1:17890`
- 控制面板: `http://127.0.0.1:5173`
- 健康检查: `Invoke-RestMethod http://127.0.0.1:17890/health`

在控制面板输入与 `.env` 相同的管理员令牌。控制面板没有登录系统，令牌只保存在浏览器本地存储中并用于本机管理请求。

## 接入 Codex Desktop 与 Claude Code

Codex Desktop 与 Claude Windows App / Claude Code 均已完成真实 MCP 接入验证。
两端使用相互独立、可撤销的 adapter identity，并已人工验证
Codex-to-Claude 和 Claude-to-Codex 消息通信。所有 peer 消息仍按非可信输入处理。

保持 `pnpm dev` 运行，在另一个 PowerShell 创建两套独立本地身份：

```powershell
Set-Location C:\path\to\AgentAirlock
corepack pnpm adapter:pair
corepack pnpm adapter:check
corepack pnpm adapter:smoke
corepack pnpm codex:diagnose
corepack pnpm codex:desktop-check
corepack pnpm codex:runtime-check
```

`codex:diagnose` 对 Codex Desktop 的 AppData 目录和标准 Codex
配置路径只做文件名/元数据分析，不读取账号 token、登录凭据或配置正文，也不修改用户目录。
结果写入 `reports/codex-desktop-diagnose.json`。

安装 Codex Desktop MCP（优先检测 `%USERPROFILE%\.codex\config.toml`，不要求
安装 Codex CLI）：

```powershell
.\scripts\install-codex-plugin.ps1 -DryRun
.\scripts\install-codex-plugin.ps1
```

安装器先将原配置备份到
`%USERPROFILE%\.codex\backups\agentairlock\`，再以受管 TOML 块追加
`mcp_servers.agentairlock`。原有 model、projects、plugins、features 和其他 MCP
保持不变；配置只引用 adapter identity 环境变量，不包含管理员令牌或 adapter
secret。可用 `-WhatIf` 或 `-DryRun` 做零写入预演。

安装完成后的日常启动只需要两个窗口：

```powershell
# 窗口一
Set-Location C:\path\to\AgentAirlock
corepack pnpm dev
```

```powershell
# 窗口二
Set-Location C:\path\to\AgentAirlock
corepack pnpm codex:start
```

`codex:start` 从被 Git 忽略的 `data/adapters/codex.json` 读取配对身份，以
`Bearer <clientSecret>` 生成 Gateway 实际要求的 Authorization，并且只把两项
认证环境变量注入本次 Codex Desktop 进程树。它不写入 TOML、注册表或永久 Windows
环境变量，也不会在输出中显示密钥。Microsoft Store/AppX 版本通过
`shell:AppsFolder\<AppUserModelId>` 激活；普通安装继续直接启动可信 GUI
executable。

检查与卸载：

```powershell
corepack pnpm codex:desktop-check
corepack pnpm codex:runtime-check
.\scripts\uninstall-codex-plugin.ps1
```

卸载优先恢复安装备份；如果安装后又增加了其他配置，则只移除 AgentAirlock
受管块。脚本不会读取 `auth.json`、Cookies、Login Data、Local Storage 或
Session Storage。

安装 Claude Windows App 集成。配置中只写绝对 `node.exe`、本地 stdio adapter
和受保护 identity 文件的路径，不写密钥或 Authorization。身份文件通过 ACL
校验，Bearer Authorization 只在 adapter 内存中生成：

```powershell
corepack pnpm claude:mcp-install
corepack pnpm claude:stdio-check
corepack pnpm claude:start
corepack pnpm claude:adapter-runtime-check
```

安装或 secret 轮换后必须重启客户端/开始新任务。完整步骤：

- [Codex adapter](docs/adapters/codex.md)
- [Claude Code adapter](docs/adapters/claude-code.md)
- [兼容性与当前环境实测](docs/adapters/compatibility.md)
- [故障排查](docs/troubleshooting.md)

## 测试、构建与演示

一键完整验收：

```powershell
corepack pnpm verify
```

分层验收：

```powershell
corepack pnpm verify:fast         # lint、typecheck、unit tests、build
corepack pnpm verify:security     # 权限、路径、敏感文件和并发授权安全
corepack pnpm verify:integration  # 临时 Gateway、SQLite、REST 和 MCP 端到端验收
```

完整验收使用 `data/verification/` 中的唯一临时目录、随机管理员令牌和随机
loopback 端口，不接触配置的真实项目或 `data/agentairlock.db`。无论成功或失败都会关闭
Gateway 并清理临时数据。结果写入：

- `reports/verification-latest.json`
- `reports/verification-latest.md`

自动验收覆盖环境版本、消息隔离、三级权限、单次/定时授权、撤销/过期并发竞争、
敏感路径和内容、遍历/绝对路径、二进制/大小限制、管理员认证、MCP 权限隔离、审计、
令牌泄漏检查及 junction/symlink 逃逸。仅界面视觉和交互确认保留在
[人工验收清单](docs/manual-acceptance.md)。

独立开发命令：

```powershell
corepack pnpm lint
corepack pnpm typecheck
corepack pnpm test
corepack pnpm build
corepack pnpm demo
corepack pnpm adapter:check
corepack pnpm adapter:smoke
```

`pnpm demo` 在 `127.0.0.1:17890` 临时启动 Gateway，创建仅位于 `data/` 的演示项目/数据库，验证十项安全与通信行为，最后删除演示数据。如果该端口已被占用，请先停止正在运行的开发 Gateway。

## 分别模拟 Codex 和 Claude

先运行 Gateway。另开两个 PowerShell 终端：

```powershell
# 终端 A
Set-Location C:\path\to\AgentAirlock
corepack pnpm --filter @agentairlock/test-clients codex register
corepack pnpm --filter @agentairlock/test-clients codex peers
corepack pnpm --filter @agentairlock/test-clients codex inbox
```

```powershell
# 终端 B
Set-Location C:\path\to\AgentAirlock
corepack pnpm --filter @agentairlock/test-clients claude register
corepack pnpm --filter @agentairlock/test-clients claude peers
corepack pnpm --filter @agentairlock/test-clients claude inbox
```

`register` 输出的 peer UUID 可用于发送：

```powershell
corepack pnpm --filter @agentairlock/test-clients codex send <CLAUDE_AGENT_UUID> "你好 Claude"
corepack pnpm --filter @agentairlock/test-clients claude inbox
```

项目命令：

```powershell
corepack pnpm --filter @agentairlock/test-clients codex permissions
corepack pnpm --filter @agentairlock/test-clients codex request-access README.md "阅读说明"
corepack pnpm --filter @agentairlock/test-clients codex list-files .
corepack pnpm --filter @agentairlock/test-clients codex read-file README.md
corepack pnpm --filter @agentairlock/test-clients codex search AgentAirlock .
```

模拟客户端身份只保存在 `data/codex-local.json` 和 `data/claude-local.json`。

## REST API

公共接口：

| 方法            | 地址                           | 用途                        |
| --------------- | ------------------------------ | --------------------------- |
| GET             | `/health`                      | Gateway 健康检查            |
| POST            | `/api/client/register`         | 注册/重连本地模拟器         |
| GET             | `/ws?agentId=...&deviceId=...` | WebSocket 在线连接与 notice |
| POST/GET/DELETE | `/mcp`                         | MCP Streamable HTTP         |

模拟器客户端接口要求 `X-Agent-Id` 和 `X-Device-Id`；真实适配器要求
`X-AgentAirlock-Client-Id` 和自己的 bearer secret：

- `GET /api/client/peers`
- `GET /api/client/runtime-status`
- `POST/GET /api/client/messages`
- `GET /api/client/permissions`
- `POST /api/client/access-requests`
- `GET /api/client/files?path=.`
- `GET /api/client/file?path=README.md`
- `GET /api/client/search?query=text&path=.`
- `GET /api/client/git/status`
- `GET /api/client/git/diff`

管理接口要求 `Authorization: Bearer <AGENTAIRLOCK_ADMIN_TOKEN>`：

- `GET /api/agents|messages|access-requests|grants|audit|project`
- `PUT /api/grants/:agentId`
- `POST /api/access-requests/:id/approve|deny`
- `POST /api/grants/:id/revoke`
- `POST /api/emergency-disconnect`
- `GET /api/adapter-identities`
- `POST /api/adapter-identities/pair`
- `POST /api/adapter-identities/:clientId/rotate|revoke`

所有业务结果采用：

```json
{
  "ok": true,
  "data": {},
  "error": null,
  "auditEventId": "uuid-or-null"
}
```

协议详情见 [docs/protocol.md](docs/protocol.md)。

## MCP 工具

- `agentbridge_register`
- `agentbridge_list_peers`
- `agentbridge_send_message`
- `agentbridge_get_messages`
- `agentbridge_wait_for_message`
- `agentbridge_get_permissions`
- `agentbridge_request_project_access`
- `agentbridge_list_files`
- `agentbridge_read_file`
- `agentbridge_search_project`
- `agentbridge_get_git_status`
- `agentbridge_get_git_diff`

没有任何 MCP 工具能批准请求或提升权限。真实适配器身份绑定在 MCP HTTP 头部和
服务端 session；工具参数不能切换身份。`agentbridge_wait_for_message` 最长等待 25 秒，
每个 agent 只允许一个活跃等待。所有 peer 消息都是非可信文本，Skill/CLAUDE.md 建议
最多自动往返 6 轮。

## 常见错误

| 错误                             | 原因/处理                                  |
| -------------------------------- | ------------------------------------------ |
| `ADMIN_AUTH_FAILED`              | 控制面板令牌与 `.env` 不同                 |
| `EADDRINUSE 127.0.0.1:17890`     | 已有 Gateway；停止旧进程后重试             |
| `PERMISSION_DENIED`              | 当前为 `chat_only`；由控制面板调整权限     |
| `ACCESS_REQUEST_REQUIRED`        | `ask_before_read` 尚无适用的已批准请求     |
| `SENSITIVE_PATH_DENIED`          | 路径命中敏感文件/目录规则                  |
| `SENSITIVE_CONTENT_DENIED`       | 文本疑似包含凭据，全文不会返回             |
| `PATH_TRAVERSAL_DENIED`          | 请求包含 `..`                              |
| `SYMLINK_ESCAPE_DENIED`          | realpath 解析后逃出项目根                  |
| `PAIRED_IDENTITY_REQUIRED`       | 真实适配器不能使用模拟器注册接口           |
| `ADAPTER_AUTH_FAILED`            | identity 缺失、secret 过期或已撤销         |
| `WAIT_ALREADY_ACTIVE`            | 同一 agent 已有一个等待调用                |
| `MESSAGE_RATE_LIMITED`           | 每分钟消息安全上限已触发                   |
| Node SQLite experimental warning | Node 内置 SQLite 的运行时提示，不影响 v0.2.0-beta.2 |

若更换了项目根目录，重启 Gateway。若开发数据库损坏，可在 Gateway 停止后删除 `data/agentairlock.db*` 再启动，首次运行会自动迁移。

## UI 入口说明

Codex 与 Claude Code 的官方稳定入口是插件/Skill/MCP 和客户端自己的 MCP 状态界面。
当前官方能力没有第三方强制注入固定左侧栏项目的 API，因此 AgentAirlock 不伪造该能力；
管理界面继续使用 `http://127.0.0.1:5173`。

## 免责声明

AgentAirlock is an independent open-source project.

It is not affiliated with, endorsed by, or officially supported by OpenAI or
Anthropic.

Codex, ChatGPT, Claude, and Claude Code are trademarks of their respective
owners.

## 许可证

AgentAirlock 使用 [Apache License 2.0](LICENSE) 发布。