PeterBlenessy/airlocked-agents

# airlocked-agents **用于私有、自托管 AI 自动化技术栈的确定性 IaC —— 不受信任的内容将被留在气闸室中。** 为《推荐设置 —— 架构与构建指南》中描述的架构提供幂等设置：在 Mac 上运行本地模型 + 第二大脑，在 VPS 上运行 n8n 自动化胶水和沙盒化的 Suna 研究装备，通过私有隧道连接，仅在云端使用 Claude + MCP 处理公开工作。 这个仓库的核心目的就是自动确保一条规则成立：**没有任何单一组件能够同时读取不受信任的内容、持有你的凭证并发送外部请求。** **主题**（由 `make repo` 自动设置，或在 GitHub UI 中手动添加）： `infrastructure-as-code` · `ansible` · `docker-compose` · `self-hosted` · `ai-agents` · `privacy` · `security` · `llm` · `local-first` · `n8n` · `mcp` · `homelab` · `prompt-injection` · `automation` · `llama-cpp` 请勿与 [`NevaMind-AI/airlock`](https://github.com/NevaMind-AI/airlock) 混淆 —— 那是一个你内嵌的 Python 出口防护*库*；而这是一个你运行的实际部署*技术栈*。 ## 哪些是确定性的，哪些是手动的（请先阅读本节） 诚实的 IaC 会划清界限。本仓库也是如此。 **完全确定性 + 幂等（可随意运行多次）：** - 所有软件包安装（Mac 上的 Homebrew，VPS 上的 Docker）。 - 通过 Docker Compose 部署的容器技术栈（n8n, Khoj）。 - 使用你的变量从模板渲染的每个配置文件。 - 服务启用（Mac 上的 launchd，VPS 上的 systemd/Compose）。 - VPS 防火墙 (ufw) 和 Mac↔VPS 之间的 WireGuard 隧道。 - n8n 凭证占位符和工作流导入脚手架。 **设计上为一次性手动操作（由于需要交互式授权，无法实现确定性）：** - **Gmail OAuth** —— Google 要求浏览器同意授权；你需要创建 OAuth 应用并粘贴 client id/secret，然后在 n8n UI 中授权一次。 - **Telegram bot token** —— 通过 `@BotFather` 交互式创建。 - 用于 Suna 的 **Supabase project** —— 创建项目（云端或自托管）并粘贴其密钥。 - **模型下载** —— 可编写脚本 (`make model`)，但由于是数 GB 的大文件，因此设为可选操作。 - **VPS 配置** —— 自带主机；提到了可选的 Terraform 模块，但此处未绑定特定供应商。 所有手动操作都被简化为填写 `.env` 以及 `docs-MANUAL-STEPS.md` 中的 5 项检查清单。绝不会提交任何机密信息。 ## 前置条件 - 一台 Mac（默认为 Apple Silicon），已安装 Homebrew 和 Docker Desktop。 - 一台你可以通过 SSH 登录的小型 Linux VPS（默认为 Debian/Ubuntu），运行 n8n 只需 2 GB 内存；而 Suna 大约需要 16 GB 内存或使用单独的主机。 - 在你运行此脚本的机器上安装了 `ansible` 和 `make`（`brew install ansible make`）。 - 你的 llama.cpp 模型文件（或运行 `make model` 获取一个）。 ## 布局 ``` airlocked-agents/ ├── Makefile # the entrypoint — see `make help` ├── README.md ├── CONTRIBUTING.md # the security-first contribution bar ├── LICENSE # MIT ├── docs-MANUAL-STEPS.md # the irreducible interactive steps ├── .env.example # copy to .env and fill in ├── .devcontainer/ # Linux dev env mirroring CI (lint/validate the IaC locally) │ └── devcontainer.json ├── .github/workflows/ │ └── ci.yml # syntax + compose + json/shell checks + secret guard ├── ansible/ │ ├── inventory.ini # localhost (mac) + your vps host │ ├── mac.yml # llama.cpp + tunnel proxy + Khoj + Open Interpreter + Cua* + launchd │ └── vps.yml # docker + n8n + firewall + wireguard + suna clone ├── compose/ │ ├── n8n.yml # n8n Community Edition, locked down │ └── khoj.yml # Khoj pointed at your local model ├── mac/ │ ├── Brewfile # declarative Mac packages │ ├── com.local.llama-server.plist.tmpl # the model, 127.0.0.1 only │ ├── com.local.llama-tunnel.plist.tmpl # socat proxy: model on the WG interface only │ └── download-model.sh ├── n8n/ │ ├── allowlist.code.js # canonical chat-id + recipient guard (embedded into the write path) │ ├── workflow.read-path.json # importable skeleton (verify in editor) │ └── workflow.write-path.json # write path with the guard inlined ├── wireguard/ │ ├── wg0.mac.conf.tmpl │ └── wg0.vps.conf.tmpl ├── scripts/ │ ├── setup.sh # the guided installer (`make setup`) — start here │ ├── teardown.sh # reverses setup via its manifest (`make teardown`) │ ├── verify.sh # health + boundary checks (binding, exact firewall, guard test) │ ├── injection-selftest.sh # automated guard unit test (run by make verify) │ ├── bootstrap-repo.sh # git init + gh repo create + push (with secret guard) │ └── injection-selftest.md # the manual end-to-end injection test └── secrets/ # gitignored; your keys live here, never committed * Cua install is best-effort (the npm package name is unverified upstream); see ansible/mac.yml. ``` ## 发布到 GitHub ``` make repo # uses the gh CLI: init, commit, create, push # 或使用 options： make repo NAME=my-stack VIS=public ``` 引导脚本会拒绝提交任何类似机密的文件（如 `.env`、密钥、渲染后的 `*.conf`），并在创建远程仓库之前请求确认。随后 CI 将在 每个 PR 上运行（`.github/workflows/ci.yml`）。 ## 快速开始 最简单的方式只需一条命令 —— 一个引导式安装程序，它会检查你的系统，提议 安装缺失的组件，通过实时验证收集配置，**生成你的 WireGuard 密钥**， 并按正确的顺序运行所有步骤： ``` make setup # interactive, idempotent — start here ``` `make doctor` 会报告当前存在/缺失的内容，但不会进行任何更改。你可以随时重新运行 `make setup` 来修改值或完成之前跳过的步骤。 担心在日常使用的机器上运行它？**`make setup-dryrun`** 会运行整个向导， 并准确打印出它*将要*安装、更改和写入 `.env` 的内容 —— 不安装任何东西， 不写入任何东西，不触碰任何东西。先预览，等你放心后再真正运行。

想自己手动操作？以下是具体的执行目标：

``` cp .env.example .env # then edit .env with your values make help # list targets make mac # provision the Mac (idempotent) make vps # provision the VPS (idempotent, over public SSH) make tunnel # bring up the WireGuard link make harden # lock VPS SSH to the tunnel (after the tunnel is up; recommended) make workflows # import the n8n workflow skeletons make verify # run health + boundary checks ```

每个目标都可以安全地重新运行；Ansible 会收敛到声明的状态。要拆除容器技术栈，请运行：`make down`。 ### 卸载 / 回滚 `make setup` 会写入一份**事务清单**（`.airlocked/manifest.tsv`，已被 gitignore），记录 它所做的每一项更改 —— 并且*只有在事先不存在的情况下*，才会将软件包记录为已安装。 ``` make teardown # replays the manifest in reverse, undoing only what setup did ``` 由于它是根据清单行事而不是盲目猜测，`make teardown` 会移除安装时创建的服务、 容器、卷、launchd 代理、模型文件、配置和 VPS 状态 —— 但 **绝不会卸载你已有的工具**。每一个破坏性步骤都会先询问。 （`make down` 只是停止容器技术栈；而 `make teardown` 是完全反转操作）。 即使使用了 `make setup`，哪些操作仍需手动：那些*无法*自动化的 交互式授权步骤 —— 在 n8n 编辑器中点击 Gmail OAuth 凭证上的 **Connect**， 在 `@BotFather` 中创建 Telegram bot，以及运行 Suna 的设置向导。 `make setup` 会引导你完成每一步，并尽可能地进行验证（例如，它会测试你的 Telegram token 并自动检测你的 chat id）。 ## 重申确定性保证 在提供相同 `.env` 的情况下，从干净的主机开始，`make mac && make vps && make tunnel` 每次都会以相同的方式收敛。它唯一无法为你创建的就是上述三个需要交互的机密 —— 这是 OAuth 和 bot 注册的机制属性，而不是本仓库的限制。详见 `docs-MANUAL-STEPS.md`。 ## 内置安全说明 - 本地服务（llama.cpp, Khoj）绑定到 `127.0.0.1`；模型仅在 WireGuard 隧道接口上重新暴露给 VPS —— 由 `make verify` 验证。 - VPS 防火墙仅允许三条入站规则 —— SSH (22)、HTTPS (443)、WireGuard (UDP) —— 其中 HTTPS 是唯一的应用程序入口；`make verify` 会断言这个确切的规则集。执行 `make harden` 后，SSH 将被锁定为仅限 WireGuard 隧道对等节点访问（没有公共 SSH）。 - n8n 的写入路径实现了凭证隔离和人工把关；允许列表防护已直接嵌入到 `n8n/workflow.write-path.json` 中（规范源：`n8n/allowlist.code.js`），因此开箱即用的导入操作就是受保护的。 - 敏感研究通过隧道路由到本地模型（通过 Mac 上的 socat 代理）；没有任何私密内容会流出至云端。 - `make verify` 会运行允许列表防护自测（`scripts/injection-selftest.sh`）；完整的端到端 prompt-injection 测试是手动的 —— 详见 `scripts/injection-selftest.md`。 命令和镜像标签会发生偏移；请在 `.env` 中锁定版本，并在升级后重新运行 `make verify`。

标签：AI自动化, Ansible, Docker Compose, 应用安全, 本地部署, 版权保护, 系统提示词, 网络安全, 自托管, 隐私保护