thiesgerken/carapace

面向 DevOps 工程师的安全个人 AI 代理。

零信任。基于 Git 的知识库。完整的审计追踪。

快速入门 · 安全模型 · Kubernetes · Helm Chart

carapace 是一个自托管的 AI 代理，提供 Web UI、CLI 和 Matrix 频道，专为那些希望拥有一个真正可推理助手的运维人员而设计。每一个有意义的操作都会由一个专门的 sentinel LLM 根据 `SECURITY.md` 中的自然语言策略进行评估，并在沙箱内执行，同时记录在审计追踪中。它的记忆并非隐藏在应用特定的数据库中：个性、策略、技能、记忆和归档的会话都存放在一个由 Git 支持的知识库中，你可以对其进行检查、对比和同步。

Web UI 将沙箱状态、知识库状态以及 sentinel 审查过的操作集中展示在一处。

## 核心亮点 - 🛡️ Sentinel 门控执行。每一个非平凡操作都会由一个专门的 security agent 进行审查，该 agent 会保持会话上下文，而不是使用静态的白名单电子表格。 - ☸️ 支持 Kubernetes 的沙箱。同时支持 Docker 和 Kubernetes 运行时，并已实现 StatefulSet 支持的沙箱会话、每会话专属的 PVC 以及闲置时缩容至零的功能。 - 🗃️ Git 原生知识库。`SOUL.md`、`USER.md`、`SECURITY.md`、技能、记忆和归档的会话都以文件形式存在，你可以对它们进行检查、对比、同步并推送到上游。 - 🚫 禁止直连互联网的沙箱。沙箱工作负载无法获取直接访问互联网的权限；出站流量会被强制通过代理路径。 - 🌐 带有隧道的代理系统。HTTP 流量由代理进行中介处理，而执行级别的隧道则覆盖非 HTTP 协议，且不会留下长期运行的守护进程。 - 🔑 上下文级别的凭证。密钥保存在你的保险库中，原生支持 Bitwarden 和 Vaultwarden，仅在具有匹配的已批准技能上下文的 exec 调用时才会按需注入或获取。 ## 项目说明 - 强制 AI 免责声明：当然，我使用 AI 来编写代码。其他任何方式都不合逻辑。前端几乎是纯粹的“氛围编程”，而后端是“审查式编程”。我尽量不亲自修改后端的任何文件，但我会查看关键代码的变更。架构和安全方面的理念与决策都是我自己的。我确实拥有超过 20 年不使用 AI 编程的经验。 - 不包含电池。项目的初衷是让使用者通过代理来构建自己的技能和工作流。 - 这是为我自己制作的！而且因为制作东西很有趣。分享东西也很有趣。我不在乎你是否认为 <在此插入其他项目名称> 更好，和/或它解决了同样的问题。 - carapace 仍处于 1.0 之前的阶段。在发布 `1.0.0` 版本之前，请预期会有破坏性更新。 ## 知识库，而非隐藏状态 carapace 将长期运行的代理状态视为一个代码仓库，而不是不透明的内部存储。 - 代理的策略存放在 `SECURITY.md` 中。 - 其个性和用户模型存放在 `SOUL.md` 和 `USER.md` 中。 - 技能是 AgentSkills 格式的纯文件。 - 记忆是磁盘上的 Markdown 文件。 - 会话历史可以归档到知识库中并推送到上游。 这使得系统在大多数代理项目中具备独特的可检查性。你可以审查变更的内容、进行对比、同步，并审计代理的知识是如何随时间演变的。 ## 安全模型 - Sentinel 代理根据自然语言策略评估每一个非平凡操作，而不是死板的规则矩阵。 - 适用严格的否决语义：如果安全路径、sentinel 或用户说“不”，操作就不会继续。 - 沙箱执行为文件和进程活动提供了硬性边界。 - 出站流量通过代理，带有域名合理性检查和可见的审批事件。 - 域名、凭证和隧道都限定在各自的 exec 调用范围内，因此权限不会在长时间的会话中累积。 - 凭证访问具有会话感知能力且可审计，只有在匹配的技能上下文明确覆盖时才提供快速通道。 - 知识工作流产生的 Git 推送与其他敏感操作一样接受安全审查。 完整模型请参见 [docs/security.md](docs/security.md)、[docs/credentials.md](docs/credentials.md) 和 [docs/sandbox.md](docs/sandbox.md)。 ## 入门指南 ``` cp .env.example .env # 填写 ANTHROPIC_API_KEY 和 CARAPACE_TOKEN docker compose build docker compose up -d ``` 这将启动： - 服务端：`http://localhost:8321` - 前端端：`http://localhost:3001` 可选的 CLI 连接： ``` uv run carapace --token "$CARAPACE_TOKEN" ``` 你可以使用任何适合你设置的 LLM 后端：托管 API、自托管的 `vllm`、`llama.cpp`、LM Studio，或任何其他暴露兼容端点的服务。 有关完整的 Docker Compose 设置、模型配置、凭证后端、Matrix 集成和知识库配置，请参阅 [docs/quickstart.md](docs/quickstart.md)。有关 Kubernetes 部署，请参阅 [docs/kubernetes.md](docs/kubernetes.md) 和 [charts/carapace/README.md](charts/carapace/README.md)。 ## 架构 ``` flowchart TD CLI["CLI Client"] & WebUI["Web UI (Next.js)"] & Matrix["Matrix Channel"] CLI & WebUI & Matrix -->|"REST + WebSocket / nio"| Server["FastAPI Server"] Server --> Engine[Session Engine] Engine --> Agent[Pydantic AI Agent] Engine --> Security[Security Module] Security --> SafeList["Safe-list (auto-allow)"] Security --> Sentinel["Sentinel Agent (LLM)"] Sentinel --> Gate["Approval Gate → subscribers"] Agent --> Skills[Skill Registry] Agent -->|"exec, file ops"| Sandbox["Sandbox Container\n(Docker or K8s pod)"] Sandbox -->|"outbound traffic"| Proxy[HTTP Proxy] Proxy --> Sentinel Engine --> Knowledge["Git-backed knowledge repo"] ``` 服务器运行代理循环、会话生命周期和安全系统。CLI、Web UI 和 Matrix 频道是瘦客户端。知识库是设计中的一等公民：会话输出可以提升为 Git 支持的知识，并且出站的 Git 操作会经过安全审查，而不是作为事后补救。 更详细的架构分解请参阅 [docs/architecture.md](docs/architecture.md)。 ## 核心文档 | 主题 | 涵盖内容 | | -------------------------------------------------------------- | -------------------------------------------------------------------------- | | [docs/quickstart.md](docs/quickstart.md) | Docker Compose 设置、凭证、Matrix 和初始配置 | | [docs/security.md](docs/security.md) | Sentinel 策略模型、审计追踪、审批和否决语义 | | [docs/skills.md](docs/skills.md) | AgentSkills 支持、上下文范围的访问、提供者和命令别名 | | [docs/credentials.md](docs/credentials.md) | 保险库支持的凭证、审批流程和每次执行级别的注入 | | [docs/memory.md](docs/memory.md) | Markdown 记忆模型及其加载和搜索方式 | | [docs/sandbox.md](docs/sandbox.md) | Docker/Kubernetes 沙箱、代理行为和执行级别的隧道 | | [docs/sessions-and-channels.md](docs/sessions-and-channels.md) | 会话生命周期、WebSocket 事件、Matrix 行为和审批 | | [docs/kubernetes.md](docs/kubernetes.md) | Kubernetes 运行时、StatefulSet 沙箱和 Helm 部署 | ## Kubernetes 部署 carapace 支持 Kubernetes 作为沙箱运行时。沙箱以 StatefulSet 形式运行，并带有每会话专属的 PVC。在闲置超时后，StatefulSet 会缩容至零，同时保留持久状态；在恢复时，沙箱将使用其已提交的知识和已激活的设置重新创建。 请使用包含在 [charts/carapace](charts/carapace) 中的 Helm chart，并参阅 [charts/carapace/README.md](charts/carapace/README.md) 获取安装详情。 ## 开发 ``` uv sync --dev uv run pytest pnpm --dir frontend install pnpm --dir frontend lint ``` 对于不使用 Docker Compose 的本地开发： ``` docker compose build sandbox uv run carapace-server pnpm --dir frontend dev uv run carapace ``` 额外的前置条件：Python 3.12+、`uv`、Node.js 24+ 和 `pnpm`。 ## 状态 carapace 正在积极开发中，但核心系统已可正常使用。 目前已交付： - Sentinel 门控的工具执行 - Web UI、CLI 和 Matrix 频道 - Docker 和 Kubernetes 沙箱运行时 - 带有会话归档和上游推送支持的 Git 知识库 - 上下文范围的技能域、凭证和执行范围的隧道 - 带有文件和 Bitwarden 后端的凭证代理 - 会话分叉、侧边栏控制、会话属性和审批来源 UI 标记 - Token 使用情况报告、预算和运行时模型切换 下一步计划： - [Vector search for memory](docs/plans/memory.md) - [Scheduled tasks and cron-like channels](docs/plans/channels.md) - [Further Kubernetes enhancements](docs/plans/kubernetes.md) ## 贡献 欢迎提交 Issue 和 Pull Request。在发起 PR 之前，请运行相关的后端测试、前端 lint 和 chart lint。该仓库使用 `prek` 钩子，CI 也会涵盖测试、前端 lint 和 Helm lint。 我想在接受第一个 PR 之前，我必须考虑一下贡献者政策以及贡献代码的所有权问题。 ## 许可证 MIT。请参阅 [LICENSE](LICENSE)。

标签：AIOps, AI助手, AI安全, Chat Copilot, CLI, DLL 劫持, Git, Helm, JSONLines, Lerna, LLM, Matrix, Python, Ruby, Streamlit, TCP SYN 扫描, Unmanaged PE, Web UI, WiFi技术, 个人AI, 人工智能代理, 大语言模型, 子域名突变, 安全模型, 审计日志, 开源, 无后门, 沙箱, 知识库, 策略执行, 网络安全, 网络安全研究, 自动化运维, 自托管, 访问控制, 请求拦截, 逆向工具, 隐私保护, 零信任