Skip to content
Back to search

atlas-agent-control-plane

AtlasAgent - an auditable AI agent control plane: evidence-backed memory, governed tool runtime, checkpoint DAG recovery, and a 55-chapter engineering tutorial. FastAPI / Next.js PWA / Textual TUI

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/malevrigns--atlas-agent-control-plane/badge.svg)](/listings/malevrigns--atlas-agent-control-plane)

HTML

<a href="/listings/malevrigns--atlas-agent-control-plane"><img src="/api/listings/malevrigns--atlas-agent-control-plane/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 257 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. <div align="center">
  2. <img src="./assets/readme/hero-editorial-50.webp" width="92%" alt="AtlasAgent" />
  3. <br><br>
  4. <a href="https://github.com/malevrigns/atlas-agent-control-plane/stargazers"><img src="https://img.shields.io/github/stars/malevrigns/atlas-agent-control-plane?style=flat&color=2b6cb0&labelColor=f6f8fa&label=%E2%98%85" alt="Stars"></a>&nbsp;
  5. <a href="https://github.com/malevrigns/atlas-agent-control-plane/actions"><img src="https://img.shields.io/github/actions/workflow/status/malevrigns/atlas-agent-control-plane/ci.yml?style=flat&labelColor=f6f8fa&label=CI" alt="CI"></a>&nbsp;
  6. <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-2b6cb0?style=flat&labelColor=f6f8fa" alt="MIT"></a>
  7. [English](#english) · [中文](#中文) · [📖 完整教程](tutorial/README.md)
  8. </div>
  9. ---
  10. <a id="english"></a>
  11. ### Why I built this
  12. When I deployed OpenClaw for the first time, the experience was unlike anything before. But a question followed me for weeks: these general agents are already this strong — is there any point in building another one?
  13. The answer I settled on: a general agent is a good knife; a vertical agent is a machine assembled for one workflow. They don't compete. So this project is my attempt to build the machine — not a chat shell wired to an LLM, but a system that plans a task, executes it step by step, calls tools, observes results, and answers with evidence it can point to.
  14. Along the way I kept running into the same wall: the demos were impressive, but the moment you ask *"where did this fact come from?"* or *"what did the agent do while I was asleep?"* — nothing holds up. AtlasAgent is what that wall looks like when you take it seriously. Every fact carries its source. Every tool call passes a gate before it runs. Every long task leaves behind checkpoints you can resume from. And when a task claims it's done, an acceptance command has to exit 0 before the system believes it.
  15. One more thing: the whole system is paired with a [62-chapter tutorial](tutorial/README.md) that rebuilds it from an empty directory — because reading source code tells you *what*, but rarely *why*. The trade-offs, the dead ends, the reasons things are the way they are: that's what the tutorial keeps. [写在前面](tutorial/README.md) has the full story, in my own words.
  16. <br>
  17. <img src="./assets/readme/evidence-chain.webp" width="100%" alt="Evidence chain" />
  18. ### Six boundaries, taken as first principles
  19. | | |
  20. |:--|:--|
  21. | **Memory with provenance** | Facts pass a write gate before they reach the model — source, scope, expiry. Then Ebbinghaus decay, consolidation, conflict resolution, and a typed memory graph. A memory should be able to forget. |
  22. | **RAG that cites its work** | Query rewriting, multi-query RRF fusion, parent-document retrieval, LLM reranking with a lexical fallback. Every citation carries a confidence score; every query leaves a retrieval trace. |
  23. | **A tool runtime with a gate** | Risk tier → approval → idempotency → timeout → redaction → artifact. The handler runs only after the gate says yes. Add result caching, dependency-aware batching, retries with fallback, per-step budgets. |
  24. | **A task must earn "done"** | Before a task completes, three gates run in order: the acceptance command (exit 0 or it isn't done), a scope audit (only files the plan declared), and an LLM coverage review of the tests. Three gates, one shared retry budget — no infinite arguing with the model. |
  25. | **Checkpoints over restarts** | State hashes and environment fingerprints. A task that dies at step 38 resumes from step 17. |
  26. | **Events are the only truth** | Task state is a rebuildable view; checkpoints are verified recovery points. Everything the agent ever did is a queryable record. |
  27. <br>
  28. <img src="./assets/readme/checkpoint-recovery.webp" width="100%" alt="Checkpoint recovery" />
  29. ### Run it
  30. Just Node 22+ — no Docker, no PostgreSQL, no Redis:
  31. ```bash
  32. git clone https://github.com/malevrigns/atlas-agent-control-plane.git
  33. cd atlas-agent-control-plane
  34. cd backend/api-ts && pnpm install && pnpm dev
  35. # or from the repo root: node scripts/quickstart-ts.mjs
  36. ```
  37. That's SQLite plus the TypeScript Hono control plane. Open <http://localhost:8000/api/status>.
  38. For the full stack — Web workbench, Postgres, Redis, Nginx, sandbox container — you need Git, Docker and Docker Compose v2:
  39. ```bash
  40. cp .env.example .env
  41. BUILD=true ./scripts/start.sh # Git Bash / WSL
  42. # Windows PowerShell: $env:BUILD="true"; ./scripts/start.ps1
  43. ```
  44. Open <http://localhost:8088> — the Web workbench. The start script prints the API key you'll log in with. No LLM key? Everything still boots; a local hash embedding powers offline mode, and any OpenAI-compatible endpoint (DeepSeek, Qwen, DashScope, Ollama…) plugs in via one line in `backend/api/config/llm.yaml`.
  45. <details>
  46. <summary>Calling the control plane directly</summary>
  47. ```bash
  48. ATLAS_KEY="$(sed -n 's/^ATLAS_API_KEY=//p' .env)"
  49. # a structured task, with its acceptance command declared up front
  50. curl -X POST http://localhost:8088/api/control-plane/tasks \
  51. -H "X-Atlas-API-Key: ${ATLAS_KEY}" -H "Content-Type: application/json" \
  52. -d '{"title": "Upgrade deps", "goal": "A verifiable upgrade",
  53. "acceptance_criteria": ["pytest exits 0"], "project_id": "atlas"}'
  54. # a tool call — risk, approval and idempotency are checked before the handler runs
  55. curl -X POST http://localhost:8088/api/agent-core/tools/draft_plan/invoke \
  56. -H "X-Atlas-API-Key: ${ATLAS_KEY}" -H "Content-Type: application/json" \
  57. -d '{"arguments": {"task": "Check delivery quality"}, "project_id": "atlas",
  58. "idempotency_key": "demo-001"}'
  59. # every invocation left a record you can query
  60. curl -H "X-Atlas-API-Key: ${ATLAS_KEY}" \
  61. "http://localhost:8088/api/control-plane/tool-invocations?project_id=atlas"
  62. ```
  63. More: [Memory & Tool Control Plane](docs/MEMORY_TOOL_CONTROL_PLANE.md) · [RAG & Skills](docs/RAG_AND_SKILLS.md) · [Architecture](ARCHITECTURE.md)
  64. </details>
  65. <details>
  66. <summary>Configuration, security, and local development</summary>
  67. **Key settings** (see [.env.example](.env.example) for the rest): `LLM_API_KEY` (optional), `ATLAS_API_KEY` (auto-generated), `RAG_VECTOR_BACKEND=pgvector|qdrant`, `RAG_EMBEDDING_PROVIDER=auto|local_hash`, `NGINX_PORT` (default 8088). The built-in key is a single-tenant boundary; internet-facing deployments need TLS, OIDC/RBAC and rate limiting in front. MCP and A2A transports are off or allowlist-only by default.
  68. **Development**, after `docker compose up -d postgres redis`:
  69. | Module | Command |
  70. | --- | --- |
  71. | API | `cd backend/api-ts && pnpm install && pnpm dev` — [docs/TYPESCRIPT_RUNTIME.md](docs/TYPESCRIPT_RUNTIME.md) |
  72. | Web | `cd frontend/web && pnpm install && pnpm dev` |
  73. | TUI | `cd frontend/tui && uv sync && ATLAS_API_URL=http://localhost:8000 uv run atlas-tui` |
  74. | Sandbox | `cd backend/sandbox && docker build -t atlas-sandbox . && docker run -d -p 127.0.0.1:8100:8100 -e SANDBOX_AUTH_ENABLED=true atlas-sandbox` |
  75. Tests: `cd backend/api-ts && pnpm test`.
  76. </details>
  77. <br>
  78. <img src="./assets/readme/three-clients.webp" width="100%" alt="One control plane, three ways in" />
  79. ### The repository
  80. ```text
  81. atlas-agent-control-plane/
  82. ├── frontend/
  83. │ ├── web/ Next.js client (PWA)
  84. │ └── tui/ Textual terminal client
  85. ├── backend/
  86. │ ├── api-ts/ TypeScript Hono control plane
  87. │ ├── sandbox-ts/ TypeScript sandbox (files / shell / VNC)
  88. │ ├── api/ legacy Python (not the runtime)
  89. │ └── sandbox/ legacy Python (not the runtime)
  90. ├── docs/ Deep-dive documentation
  91. ├── tutorial/ 62-chapter engineering tutorial (62,000+ lines)
  92. ├── scripts/ start.sh / start.ps1 / stop.sh
  93. └── docker-compose.yml
  94. ```
  95. Issues and PRs are welcome — [CONTRIBUTING.md](CONTRIBUTING.md) has the setup, commit conventions, and PR flow.
  96. ---
  97. <a id="中文"></a>
  98. ### 为什么做这个
  99. 第一次部署 OpenClaw 的时候,体验是前所未有的。但随之而来的问题困扰了我很久:这些通用 Agent 已经这么强了,还有必要从零做一个新的吗?
  100. 后来我想明白了:通用 Agent 像一把好刀,垂类 Agent 更像一台按业务流程装配好的机器。两者并不冲突。所以这个项目就是我去造那台机器的尝试——不是一个接了 LLM 接口的聊天壳,而是一个能围绕任务做规划、逐步执行、调用工具、观察结果、最后用可指认的证据回答的系统。
  101. 做的过程中反复撞到同一堵墙:演示都很惊艳,但只要你问一句「这条事实从哪来的」「我睡着的时候 Agent 到底干了什么」,就没有一样东西站得住。AtlasAgent 就是把这堵墙当真之后的样子:每条事实带来源,每个工具调用先过门禁,每个长任务留下可以恢复的 Checkpoint,任务说自己完成了,验收命令必须 exit 0,系统才信它。
  102. 还有一件事:整个系统配了一套 [62 章的教程](tutorial/README.md),从空目录开始把它重新造一遍。因为读源码能知道「是什么」,很难知道「为什么」——那些取舍、死路、和「为什么它是现在这个样子」,教程里都留着。[写在前面](tutorial/README.md) 里有完整的来龙去脉。
  103. <br>
  104. ### 六个边界,当成第一性约束
  105. | | |
  106. |:--|:--|
  107. | **带来源的记忆** | 事实先过写入门禁才到模型——来源、作用域、有效期,一个都不能少。再往上叠艾宾浩斯衰减、自动巩固、冲突消解、类型化记忆图谱。记忆应该会遗忘。 |
  108. | **会引用出处的 RAG** | 查询改写、多查询 RRF 融合、父文档检索、LLM 重排(词法降级兜底)。每条引用带置信度,每次检索落审计。 |
  109. | **有门禁的工具运行时** | 风险分级 → 审批 → 幂等 → 超时 → 脱敏 → 制品化。门禁说可以,handler 才执行。另有结果缓存、依赖分批、重试降级、步骤预算。 |
  110. | **「完成」要挣来的** | 任务完成前,三道关依次跑:验收命令(exit 0 才算完)、范围审计(只改计划声明的文件)、LLM 覆盖度评审。三关共享重试额度——不和模型无限拉扯。 |
  111. | **Checkpoint 优先于重启** | 状态哈希 + 环境指纹。第 38 步挂了,从第 17 步恢复。 |
  112. | **事件是唯一事实源** | 任务状态只是可重建的视图,Checkpoint 是验证过的恢复点。Agent 干过的每件事都是一条可查询的记录。 |
  113. ### 跑起来
  114. 只要 Node 22+,不用 Docker、不用 PostgreSQL、不用 Redis:
  115. ```bash
  116. git clone https://github.com/malevrigns/atlas-agent-control-plane.git
  117. cd atlas-agent-control-plane
  118. cd backend/api-ts && pnpm install && pnpm dev
  119. # 或仓库根目录:node scripts/quickstart-ts.mjs
  120. ```
  121. SQLite + TypeScript Hono 控制平面。打开 <http://localhost:8000/api/status> 就能调。
  122. 要完整形态(Web 工作台、Postgres、Redis、Nginx、沙箱容器),才需要 Git、Docker、Docker Compose v2:
  123. ```bash
  124. cp .env.example .env
  125. BUILD=true ./scripts/start.sh # Git Bash / WSL
  126. # Windows PowerShell: $env:BUILD="true"; ./scripts/start.ps1
  127. ```
  128. 打开 <http://localhost:8088> 就是 Web 工作台,启动脚本会打印登录用的 API Key。没配模型密钥也能跑——本地哈希 embedding 撑起离线模式;要接模型的话,DeepSeek、Qwen、DashScope、Ollama,任何 OpenAI 兼容接口在 `backend/api/config/llm.yaml` 里改一行就行。
  129. <details>
  130. <summary>直接调用控制平面</summary>
  131. ```bash
  132. ATLAS_KEY="$(sed -n 's/^ATLAS_API_KEY=//p' .env)"
  133. # 一个结构化任务,验收命令一开始就声明好
  134. curl -X POST http://localhost:8088/api/control-plane/tasks \
  135. -H "X-Atlas-API-Key: ${ATLAS_KEY}" -H "Content-Type: application/json" \
  136. -d '{"title": "升级依赖", "goal": "可验证升级",
  137. "acceptance_criteria": ["pytest 退出码 0"], "project_id": "atlas"}'
  138. # 一次工具调用——handler 执行前先过风险、审批、幂等检查
  139. curl -X POST http://localhost:8088/api/agent-core/tools/draft_plan/invoke \
  140. -H "X-Atlas-API-Key: ${ATLAS_KEY}" -H "Content-Type: application/json" \
  141. -d '{"arguments": {"task": "检查交付质量"}, "project_id": "atlas",
  142. "idempotency_key": "demo-001"}'
  143. # 每次调用都留了记录,随时可以查
  144. curl -H "X-Atlas-API-Key: ${ATLAS_KEY}" \
  145. "http://localhost:8088/api/control-plane/tool-invocations?project_id=atlas"
  146. ```
  147. 更多:[Memory 与 Tool Control Plane](docs/MEMORY_TOOL_CONTROL_PLANE.md) · [RAG 与 Skill 注册中心](docs/RAG_AND_SKILLS.md) · [整体架构](ARCHITECTURE.md)
  148. </details>
  149. <details>
  150. <summary>配置、安全与本地开发</summary>
  151. **常用配置**(其余见 [.env.example](.env.example)):`LLM_API_KEY`(可选)、`ATLAS_API_KEY`(自动生成)、`RAG_VECTOR_BACKEND=pgvector|qdrant`、`RAG_EMBEDDING_PROVIDER=auto|local_hash`、`NGINX_PORT`(默认 8088)。内置 API Key 是单租户边界;公网多用户部署需要 TLS、OIDC/RBAC 和限流。MCP 与 A2A 传输默认关闭或仅白名单。
  152. **本地开发**,先 `docker compose up -d postgres redis`:
  153. | 模块 | 命令 |
  154. | --- | --- |
  155. | API | `cd backend/api-ts && pnpm install && pnpm dev` — [docs/TYPESCRIPT_RUNTIME.md](docs/TYPESCRIPT_RUNTIME.md) |
  156. | Web | `cd frontend/web && pnpm install && pnpm dev` |
  157. | TUI | `cd frontend/tui && uv sync && ATLAS_API_URL=http://localhost:8000 uv run atlas-tui` |
  158. | Sandbox | `cd backend/sandbox && docker build -t atlas-sandbox . && docker run -d -p 127.0.0.1:8100:8100 -e SANDBOX_AUTH_ENABLED=true atlas-sandbox` |
  159. 测试:`cd backend/api-ts && pnpm test`。
  160. </details>
  161. ### 仓库结构
  162. ```text
  163. atlas-agent-control-plane/
  164. ├── frontend/
  165. │ ├── web/ Next.js 客户端(PWA)
  166. │ └── tui/ Textual 终端客户端
  167. ├── backend/
  168. │ ├── api-ts/ TypeScript Hono 控制平面
  169. │ ├── sandbox-ts/ TypeScript 沙箱(文件 / Shell / VNC)
  170. │ ├── api/ 旧 Python(不再作为运行时)
  171. │ └── sandbox/ 旧 Python(不再作为运行时)
  172. ├── docs/ 专题深潜文档
  173. ├── tutorial/ 62 章中文工程教程(62000+ 行)
  174. ├── scripts/ start.sh / start.ps1 / stop.sh
  175. └── docker-compose.yml
  176. ```
  177. 欢迎 Issue 与 PR——流程见 [CONTRIBUTING.md](CONTRIBUTING.md)。
  178. ---
  179. <div align="center">
  180. <sub>纵使这个时代资料多如繁星,也希望自己的思考能在这个时代留下痕迹。</sub>
  181. </div>

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.