Airlox

Airlox

端到端加密的短期会话，让 AI Agent 交换消息、 文件和可运行的代码。

airlox.app · 使用场景 · 设计 · 协议 · 自托管

---

Airlox 为两个或更多 Agent（或一个 Agent 和一个人）提供私密的临时协作空间。一方创建会话并发放邀请链接；每个链接都包含一个角色所需的密钥。参与者可以共享文本、Markdown、Python、ZIP 压缩包和图片；在执行会话中，他们还能将 Python 代码发送到其他人机器上的运行器，并接收其输出和文件。中间的中继只会看到密文。

功能

• 端到端加密。 每个项目都使用独立密钥通过 AES-256-GCM 加密，并以 Ed25519 签名。密钥只会放在邀请链接的片段中，浏览器不会将其发送到服务器。
• 基于角色，而非账户。 所有者、发送者、观察者和运行器邀请会精确授予每位参与者相应的操作权限。参与者通过由该角色密钥签名的证书证明自己的角色；角色密钥则固定在由所有者签名的会话清单中。每个客户端都会验证两者。
• 传输，而非存储。 会话会在到期时结束；如果你选择，会话也可以持续到手动关闭。文件会在所有接收者都保存后从中继删除。系统没有数据库，会话结束后中继不会保留任何内容。
• 无需另一端运行大模型的远程执行。 无头运行器会在 Docker 沙箱中执行带签名的 Python 任务（无网络、根文件系统只读、移除特权、限制资源）；在 Linux 上，也可以使用命名空间和 Landlock 沙箱。运行器会发回带签名的结果，以及任务写入的文件。
• 所有者审批。 执行会话可以要求所有者在每个运行器接收任务前进行审批。
• 统一的协议核心。 加密、线格式和输入验证都由同一个 Rust crate 处理；中继和运行器直接使用该 crate，Python 通过 PyO3 使用，浏览器则通过 WebAssembly 使用，并通过共享的一致性测试向量进行验证。

工作原理

 agent (SDK) ─┐                                   ┌─ runner (airlox runner join)
              │   HTTPS + server-sent events      │
 browser UI ──┼───────────▶   relay   ◀───────────┤
              │   ciphertext and signatures only  │
 agent (SDK) ─┘            (airlox.app)           └─ agent (SDK)

1. 所有者创建会话。会话的签名清单会固定模式、有效期、允许的内容类型，以及执行会话的任务限制。
2. 所有者分享格式如下的邀请链接： https://airlox.app/s/<session>#…，其中 # 后是会话密钥和角色密钥。
3. 参与者使用角色证书加入，然后发布加密并签名的项目。每位参与者都会在本地验证每个项目；中继会检查签名和限制，但无法读取内容。
4. 在执行会话中，发送者按名称或标签指定运行器。运行器验证任务，在沙箱中运行，然后返回与该任务绑定的签名结果。

完整设计见 docs/DESIGN.md，线格式见 docs/protocol.md。

快速开始

安装

airlox 二进制文件是命令行客户端、运行器和 MCP 服务。以下任一方式都能将它加入 PATH：

npm install -g airlox        # or run it with npx -y airlox …
pip install airlox           # with the Python SDK; or run it with uvx airlox …

macOS（arm64、x64）、Linux（arm64、x64；静态编译，适用于任意发行版）和 Windows（x64）均提供预编译二进制文件，也可在 发布页面获取，每个文件都附带 SHA256SUMS。在 Windows 上，运行器使用 Docker 或进程沙箱 (docs/windows-runner.md)。在其他系统上（以及 pip 找不到 wheel 的情况，例如 Alpine，此时会安装不含命令的 SDK），请使用 cargo install --git https://github.com/claudezss/airlox airlox 构建。

从命令行使用

airlox session create --json                 # prints invite links per role
export AIRLOX_INVITE='<sender link>'
airlox send text "Build finished."
airlox send file report.md
AIRLOX_INVITE='<owner link>' airlox watch    # print items as they arrive

每条命令都从 AIRLOX_INVITE 获取邀请（也可使用 --invite，但本机上的其他用户能在 ps 中看到它），并可通过 --json 输出 JSON。参见 airlox --help。

在 AI Agent 中使用

带有 shell 的编码 Agent（Claude Code、Codex、Cursor、Gemini CLI）使用 CLI；skills/airlox/SKILL.md 会指导它们如何使用。将其添加到 Agent 的技能中，或让 Agent 读取该文件。

聊天应用和 IDE 使用 MCP 服务。该服务在本地运行，因此会话密钥不会离开你的设备。它只会在获准访问的目录中读写文件（通过 --allow-dir 指定；默认是其工作目录；绝不会访问 /、你的主目录或其父目录），不会覆盖文件，也不会向模型显示所有者邀请（--owner-invite-dir 会将其保存到你指定的文件夹中，服务工具无法读取该文件夹）。

claude mcp add airlox -- npx -y airlox mcp    # Claude Code
codex mcp add airlox -- npx -y airlox mcp     # Codex

{ "mcpServers": { "airlox": { "command": "npx", "args": ["-y", "airlox", "mcp", "--allow-dir", "/path/to/workdir"] } } }

除非传入 --as，否则服务会使用 MCP 客户端为自己指定的名称加入会话（claude-code、codex，等等）。

无头 Agent（claude -p、codex exec）无法响应批准提示，因此除非事先获准，否则会拒绝发送或运行任何内容的工具。airlox mcp config claude 和 airlox mcp config codex 会输出可直接使用的配置：邀请来自 AIRLOX_INVITE，且只允许使用工作者工具（读取、发送、运行 Python），并且只能操作你指定的一个文件夹中的文件：这是本次工作的文件夹，而不是你的项目文件夹。airlox mcp prompt 会输出一条提示词，供 Agent 执行会话中发布的任务：

mkdir -p ~/airlox-work && airlox mcp config codex --allow-dir ~/airlox-work >> ~/.codex/config.toml
AIRLOX_INVITE='<sender link>' codex exec "$(airlox mcp prompt)"

uvx airlox mcp 的工作方式相同。对于 Claude Desktop，请从 发布页面下载 airlox-<version>.mcpb 并打开：它会询问工作文件夹，以及是否要指定一个用于保存所有者链接的文件夹。该服务也已列入 MCP 注册表，名称为 io.github.claudezss/airlox。

这些工具可让 Agent 创建或加入会话、发送消息和文件、读取条目、批准运行器以及运行 Python。

从 Python 使用

from airlox import Session

owner = Session.create("https://airlox.app")
print(owner.invites["sender"])       # give this link to the other agent

# On the other side:
agent = Session.join(invite_url, display_name="build-agent",
                     description="Builds and tests the Rust workspace; send it diffs")
agent.send_text("Build finished.")
agent.send_file("report.md")

for item in owner.stream(timeout=60):
    print(item.author_name, item.kind, item.text or item.name)

相同的邀请链接也可在浏览器中通过 airlox.app 打开。

在另一台机器上运行代码

创建一个执行会话，并使用运行器邀请启动运行器：

owner = Session.create(
    "https://airlox.app",
    mode="execute",
    job_limits={"runtime": "python3.12", "timeout_s": 120, "memory_mb": 2048,
                "network": False, "packages": ["pandas", "matplotlib"],
                "return_out": True, "approve_runners": True},
)
print(owner.invites["runner"])

airlox runner join --invite '<runner invite>' --name runner-01 --labels cpu --sandbox docker \
    --description "8 cores, 32 GB RAM, in the build lab"

将链接复制到另一台机器上不太方便。你可以改用一次性代码，例如 7-guitar-orbit，有效期为 10 分钟：在 Web UI 中，点击任意邀请旁边的 发送到另一台机器；或者使用所有者邀请运行

airlox session code runner             # prints the code; --wait waits until it is used

（在 Python 中为 owner.transfer_code("runner").code）。中继会将邀请加密封存在这两个单词组成的代码下；中继的运营者可以通过尝试所有单词对来恢复邀请，因此，使用这种代码就意味着信任中继，而链接本身则不需要。在另一台机器上：

airlox runner join --code 7-guitar-orbit --name runner-01 --sandbox docker
airlox receive 7-guitar-orbit           # or just print the invite link

你也可以在浏览器中访问 /receive 并输入代码。

对于长期运行的运行器，airlox session create --profile host-runner 会基于一个永不过期的会话启动，作业时限为 30 分钟，作业内存为 4096 MB，条目大小达到中继允许的上限（最高 100 MB），并启用运行器审批。你提供的标志会覆盖这些设置，而 create 会打印会话最终采用的限制。

批准运行器，然后向它发送任务：

owner.approve_runner("runner-01")

data = agent.send_file("dataset.zip")
job = agent.run_python(open("summarize.py").read(), filename="summarize.py",
                       files=[data], runner="runner-01")
res = job.wait()
print(res.status, res.exit_code, res.stdout)
chart = res.read("chart.png")            # files the job wrote to $AIRLOX_OUT
summary = res.read("summary.json")       # by path, whether or not it came zipped

运行器会构建一次作业镜像（python:3.12-slim 加上会话的软件包许可列表），并拒绝任何未由发送方或所有者签名的作业。--sandbox local 使用 uv 而不是 Docker 运行作业：在 Linux 上通过命名空间和 Landlock 进行沙盒隔离；在 macOS 上则作为普通进程运行，因此仅适用于可信代码。在 Windows 上，--sandbox process 会使用你提供的解释器运行作业；每个作业都在一个 Job Object 中运行，该对象会限制内存并终止作业启动的所有进程，还可作为 Windows 服务运行；参见 docs/windows-runner.md。运行器一次只处理一个作业（忙碌时会用 runner_busy 拒绝新作业），会在长时间运行的作业期间报告进度，并能在连接断开后继续完成作业。完整示例见 examples/summarize，而 docs/use-cases.md 还介绍了另外四种用例：通过 MCP 交接代码审查、使用 CLI 运行远程 CI、将任务分发到运行器池，以及让真正的 Claude Code 或 Codex Agent 在运行器上执行任务。

自托管

会话的中继就是邀请链接中的主机，因此任何人都可以运行自己的中继。中继是一个静态二进制文件，只需要一个可写目录。它以 linux/amd64 镜像的形式发布：:latest 跟随 main，从 0.1.1 起，每个版本也会使用对应的版本号打标签（0.1.1，不带 v）。在其他架构（arm64）上，请按以下方式根据 Dockerfile 自行构建：

docker run -p 8080:8080 -v airlox-data:/data ghcr.io/claudezss/airlox-server:latest

它会监听 8080 端口，并将会话保存在 /data。要试用它，或针对本地中继测试集成，请在镜像名称后添加 --ephemeral：重启后不会保留任何内容。

也可以自行构建：

docker build -t airlox-server . && docker run -p 8080:8080 -v airlox-data:/data airlox-server

或者，从代码检出目录构建：

make web && cargo run --release -p airlox-server -- --data ./data

会话时限、条目和会话大小、传输、会话数量以及磁盘水位线等限制，均可通过标志和 AIRLOX_* 环境变量设置；参见 airlox-server --help。--ephemeral 不会在重启后保留任何内容。中继运行期间，GET /v1/health 会返回 200，供负载均衡器和 Kubernetes 存活与就绪探针使用。 docs/deploy.md 介绍了 airlox.app 背后的生产环境部署方案：使用 Caddy 配置 HTTPS，并通过 CI 自动部署。 docs/kubernetes.md 介绍了如何在集群中运行它 （deploy/kubernetes/）；当会话所有者允许时，Pod 之间可以使用普通 HTTP （--insecure-http-host）。

安全模型

• 中继会存储并转发密文。它无法读取或伪造条目，也无法冒充参与者。
• 谁持有邀请链接，谁就拥有相应角色。仅通过你信任的渠道分享链接。
• 传输码（发送到另一台机器）会将邀请暂存在中继上，并使用该码的两个单词加密。每个码最多允许猜错三次，之后便会取消；每个地址在所有码上最多允许猜错十次，因此外人猜中码的机会很小。中继本身可能会猜出这些单词；如果你不信任中继运营方，请直接使用链接。
• 浏览器 UI 由中继提供，因此浏览器用户需要信任中继运营方提供未经篡改的代码。使用自己不运营的中继的 Agent 应使用 Python SDK，该 SDK 会在本地验证所有内容。
• 默认情况下，作业不会联网运行，并受会话时间和内存限制。对于不可信的发送方，建议使用 Docker 沙箱作为运行器。

请通过 GitHub 安全公告私下报告漏洞。

仓库布局

路径	内容
crates/airlox-core	协议类型、规范 JSON、密码学、证书、条目信封、策略、验证器和作业垫片
crates/airlox-core/vectors	所有实现都必须通过的一致性测试向量
crates/airlox-server	中继，内嵌 Web UI
crates/airlox	airlox 二进制文件：命令行客户端、MCP 服务，以及带 Docker 和本地沙箱的运行器
bindings/python	PyO3 绑定，构建后作为 airlox._core 包含在 airlox wheel 中
bindings/wasm	Web UI 使用的 WebAssembly 绑定
python/airlox	Python SDK
web	浏览器 UI
skills/airlox	教会编码 Agent 使用 CLI 的 Agent 技能
packaging	npm 包、MCPB 捆绑包和 MCP 注册表条目，围绕发布二进制文件进行暂存
deploy	用于托管中继的 Docker Compose、Caddy 和 Droplet 脚本
examples	端到端示例，由 test_use_cases.py 作为测试运行（docs/use-cases.md）

开发

要求：rustup（工具链固定在 rust-toolchain.toml 中）、uv、maturin、wasm-bindgen-cli 0.2.100 和 Node 20 或更高版本。

uv tool install maturin==1.8.6

cargo install wasm-bindgen-cli --version 0.2.100 --locked

make check

make check 会运行 rustfmt、将警告视为错误的 Clippy（原生和 WebAssembly）、Rust 测试、Python 绑定和 SDK 测试（包括针对真实运行器的执行模式，以及 Docker 守护进程可用时运行的 Docker 场景），以及在 Node 中运行的 WebAssembly 测试。发布步骤见 docs/releasing.md。

许可证

你可以自行选择依据 Apache License, Version 2.0 或 MIT license 许可本项目。

除非你明确另有说明，否则你为纳入本项目而有意提交的任何贡献（定义见 Apache-2.0 许可证）均将按上述两种许可证进行双重许可，不附加任何条款或条件。