English · 简体中文 · English demo · 中文演示
The dashboard now switches between English and 简体中文. The language preference is saved locally and preserves the selected task/page. User-authored task content is retained. See the English PRD, English screenshots and release notes, and English sharing draft.
Retinue (Chinese name 众卿, "the assembled ministers") is a self-hosted task board and orchestration hub where a mixed team of people and AI agents work the same cards. Every piece of work is one durable baton: a task card with a single holder, an acceptance check, and an append-only receipt chain. You run the board, agents claim work over MCP or HTTP, they write back, and you accept the card or send it back. There is no hosted control plane, no vendor account requirement, and no telemetry. The server-backed hub uses operator-managed local accounts and scoped credentials.
Version 0.3.0a5 is the first AGPL-3.0-only release. Task conversation histories remain behind an opt-in flag. Release notes. Manual quota refresh remains available.
Opt-in node quota collection and bilingual Home cards for Claude, Codex, Grok, Cursor and Kimi subscriptions, plus Moonshot API balance. See used percentages, reset time, report age and labelled last-successful data. Setup and API semantics · Update notes · Conversation timeline design. Existing servers require the explicit schema-26 migration; collectors stay off until enabled locally. The online demos show synthetic data only.
Version 0.3.0a1 brings the collaboration process into each task. See who
delegated to whom, what each device/model worker reported, what it is waiting
for, and which artifact supports the next handoff.
| View | What it explains |
|---|---|
| Home | The original task flow, dispatch coordination, and session flow views |
| Per-task graph | Explicit delegation, dependencies, baton movements, and review returns |
| Device/model timeline | Recorded runs with identity snapshots and source labels |
| Module contributions | Explicit functional assignments, reported work, remaining items, and artifact references |
| Node details and context | Instructions, acceptance criteria, waiting owners, progress, evidence versions, and next-step intent |
| Operations and data quality | Separate sources, reported usage coverage, receipt freshness, and retained history |
Read-only cc-connect observers match native sessions to Claude records and deduplicate usage by stable deliveries. A worker is an execution identity; session transports and observers are listed separately. The operations view has one primary implementation, while the existing task and session modes remain available.
Boundaries: delegation does not launch a model, observation does not invent task progress, an executor's claim is not independent acceptance, and reported usage is not a complete provider bill. Explicit task bindings and structured receipts are needed to follow real work. GitHub retains code/PR/CI evidence; Retinue retains holder, lease, task state, and collaboration events.
All screenshots below use the deterministic, read-only synthetic demo
(seed=42).
Its product-launch example illustrates the UI and protocol, not real model
execution or an end-to-end production acceptance result. Collaboration images
show one fixed task; timestamps come from staged synthetic demo time, not
production activity.
Operations screenshot · Data-quality screenshot · Device/model lanes · Module contributions · Branch details · Home dispatch and session flow · Full update notes · English PRD · Sharing draft
Retinue is a self-hosted, local-first task board for AI agents and the people who supervise them. It is not a chat wrapper and not an agent framework — it is the shared board and audit layer that sits underneath whatever agents you already run (Claude Code, OpenAI Codex, any MCP client, or a human with a browser).
- One holder per card. Work is never ambiguous: exactly one actor holds
the baton, and only the holder can write. Another agent's token gets
403 holder-only-writes. - Append-only receipt chain. Claim, progress, hand-off, block, and acceptance are all recorded and cannot be rewritten after the fact.
- Acceptance checks on the card. A card says what "done" means before an agent starts. Recorded completion and independent quality verification remain separate observations.
- MCP-native coordination.
retinue-server mcpexposes the board to any MCP-capable agent; there is also a plain HTTP + bearer-token API. - Runtime exporters. Read-only importers for Claude Code and Codex session data give you token activity per agent without touching sources.
- Optional IM adapters. Lark/Feishu and Telegram bridges turn a chat message into an intent — never directly into a command.
- Data sovereignty. File mode keeps canonical state in one data directory
(
org.yaml,tasks/,metrics/,nodes/); stop writers before copying it. The server stores canonical state inretinue.db; use a consistent SQLite snapshot for its backup. Runtime source records, external artifacts, credentials and deployment configuration have separate recovery paths. See the backup guide.
Individuals and small teams running a fleet of AI coding agents who want one durable board, observable receipts, and data they can take away — without adopting a hosted agent platform. It runs on one machine, a homelab box, or a NAS.
| Retinue | Trello / Jira / Linear | Agent frameworks (LangGraph, CrewAI, AutoGen) | |
|---|---|---|---|
| Primary users | People and AI agents on the same cards | People | Agents, in code |
| Where it runs | Your machine, self-hosted | Vendor SaaS | Inside your app process |
| Audit | Append-only receipt chain per card | Activity log, editable | Traces, usually ephemeral |
| Agent access | MCP server + token-scoped HTTP API | Bots and webhooks bolted on | N/A — it is the agent |
| Write safety | Holder-only writes, hooks only from org.yaml |
Anyone with access | Whatever you code |
| Telemetry | None | Vendor-side | Varies |
Retinue does not replace your agent runtime. It replaces the spreadsheet, the chat thread, and the "which agent is doing what right now?" question.
The path below stays on loopback. Credentials stay in the environment, never in a card.
Host port 9219 must be free (docker compose fails with "address already
in use" otherwise). The admin password must be at least eight characters.
read -rsp 'Choose an admin password (at least 8 characters): ' RETINUE_ADMIN_PASSWORD
printf '\n'
export RETINUE_ADMIN_PASSWORD
docker compose up --buildWait until the logs show the hub listening, then:
curl -fsS http://127.0.0.1:9219/api/healthThat returns JSON like {"status":"ok","version":"0.3.0a5"} with no
authentication. version is the PEP 440 string from pyproject.toml (the
same spelling as the wheel name and the next git tag, v0.3.0a5). Open
http://127.0.0.1:9219/ and sign in as operator with that password. The
image is the authenticated v0.2 hub, not the old read-only panel.
Onboard the agent first: sidebar Administration → prepare an executor with actor
id worker-1, save the one-time token outside the data volume. Then open
Task workspace → Task board → New task and publish:
- Title:
Write hello.txt with: hello from retinue - Holder:
worker-1(the agent that will claim it; do not leave this as yourself if you will use the agent token in the next step) - Priority:
high - Acceptance:
hello.txt contains exactly: hello from retinue
Copy the generated task id (task-YYYYMMDD-NNN).
The same card can be published over HTTP after you sign in (session cookie)
or with an admin bearer. The holder must be worker-1.
Use the one-time token from step 2:
export RETINUE_AGENT_TOKEN='<one-time-agent-token>'
export RETINUE_TASK_ID='<task-id-from-the-board>'
curl --fail --request POST \
--header "Authorization: Bearer $RETINUE_AGENT_TOKEN" \
--header 'Content-Type: application/json' \
--data '{"status":"doing","note":"claimed through the agent API"}' \
"http://127.0.0.1:9219/api/tasks/$RETINUE_TASK_ID/update"MCP-capable agents can use retinue-server mcp after
pip install 'retinue[mcp]' instead of learning curl. See
docs/agent-onboarding.md.
curl --fail --request POST \
--header "Authorization: Bearer $RETINUE_AGENT_TOKEN" \
--header 'Content-Type: application/json' \
--data '{"progress":80,"refs":["artifact:hello.txt"],"note":"recorded the result reference"}' \
"http://127.0.0.1:9219/api/tasks/$RETINUE_TASK_ID/update"When the acceptance line is actually true:
curl --fail --request POST \
--header "Authorization: Bearer $RETINUE_AGENT_TOKEN" \
--header 'Content-Type: application/json' \
--data '{"status":"done","note":"acceptance checked; hello.txt matches"}' \
"http://127.0.0.1:9219/api/tasks/$RETINUE_TASK_ID/update"Refresh the board. The card is in done and the chain shows claim, write-back,
and completion. A token issued for a different agent receives
403 holder-only-writes.
A file-mode corridor (no Docker) is in
docs/closed-loop-walkthrough.md.
Installation, backup, and exposure warnings are in
SELF_HOSTING.md.
operator agents
| |
| org.yaml (hooks only) | MCP or HTTP + actor token
v v
+------------------------------------------------------+
| RETINUE hub |
| task cards -- holder, acceptance, append-only chain |
| claim / update / receipt / handoff / block |
| optional IM adapter (intent in, never a command) |
+------------------------+-----------------------------+
|
+---------------+----------------+
| |
read-only board node reports
127.0.0.1 panel heartbeat + CLI inventory
GET only node token, no card writes
File mode keeps canonical state in the selected data directory; stop writers
before copying it. Server mode uses retinue.db and needs a consistent SQLite
snapshot. Runtime source records, external artifacts, credentials and deployment
configuration are recovered separately; see Backup.
Agents never choose on_claim hooks; file-mode hooks come only from org.yaml.
What is Retinue used for? Assigning work to a mix of humans and AI agents on one self-hosted board, and keeping a verifiable record of who held each card, what they claimed, and whether the acceptance check actually passed.
Does Retinue work with Claude Code, Codex, or other MCP clients?
Yes. MCP-capable agents connect through retinue-server mcp. Agents without
MCP use the HTTP API with a scoped actor token. Claude Code and Codex also
have read-only session exporters for token activity.
Is Retinue open source? Retinue is open source under AGPL-3.0-only, with optional commercial licensing. Personal and commercial use are free when you comply with AGPL. See LICENSE and COMMERCIAL.md.
Does Retinue send my data anywhere? No. There is no telemetry, no hosted control plane, no remote account, and no mandatory outbound request. The core, panel, daemon, demo, and exporters all work offline. Only IM adapters you explicitly configure contact anything.
Can I self-host Retinue on a homelab or NAS?
Yes. docker compose up --build brings up the hub on one host port; the
loopback corridor below is the ten-minute path. See
SELF_HOSTING.md for exposure warnings and backup.
How is Retinue different from an AI kanban board like Vibe Kanban?
Retinue is board plus audit boundary. Agents are treated as untrusted
executors: they can never choose the hook that runs, only the operator's
org.yaml can; writes are holder-only; and the receipt chain is append-only.
The board is the governance surface, not just a task queue.
Does Retinue require Docker?
No. There is a file-mode corridor with no Docker in
docs/closed-loop-walkthrough.md.
Copyright (c) 2026 JKL Thinking. The current source tree uses AGPL-3.0-only, with a separate commercial licensing option.
- Personal use and internal company use are free, including commercial use.
- If you modify Retinue and provide it to outside users over a network, you must offer those users the modified version's Corresponding Source under AGPL.
- If you do not want to meet those requirements, you can buy a commercial license. Contact: jklthinking@foxmail.com.
- Versions 0.3.0a4 and earlier released under MIT remain MIT forever.
Distribution and other uses must also meet the applicable AGPL requirements. This applies to the development tree after that cutoff; old releases and tags are unchanged. See LICENSE, NOTICE, commercial terms, contributor agreement and trademarks. Third-party dependencies retain their own terms; see THIRD_PARTY_NOTICES.
RETINUE is announced and discussed on the LINUX DO community. Issues and pull requests are welcome on GitHub.
众卿 Retinue 是一套可自托管的 AI 智能体任务看板与多智能体编排中枢： 人和 AI agent 共用同一批任务卡。每一件工作对应一张任务卡——有唯一持有人、 有可观测的验收条件、有只可追加的回执链。你来跑看板，agent 通过 MCP 或 HTTP 认领，回写结果，你验收或退回。没有托管控制面或第三方账号要求，也没有遥测； 服务端中枢使用部署方管理的本地账号与限定范围的凭据。
版本 0.3.0a1 补齐每任务的关系图、设备/模型时间泳道和功能模块贡献。
点击节点可以查看委派指令、进展、等待对象、成果引用和下一步；新会话通过只读
任务上下文了解验收条件、已有状态记录和尚未核验的工作声明。
首页的任务流转、派单协调和会话流转台继续保留。运营效率入口统一，任务看板、 列表、协作空间、历史会话和实时会话仍各有自己的用途。执行 Worker 标清设备、 runtime 与模型；同步与观察服务单列，不算作执行者。
cc-connect 原生会话观察以只读方式接入，用量按实际消息模型分层、稳定 delivery 标识去重。运营看板把任务事件、runtime 日报和会话累计来源分开解释，未上报 显示未知，采集回执与模型最后活动分别说明。
委派排队不代表模型已启动，原生会话采集不自动生成任务进度，任务 done 记录也 不代表独立验收。真实任务仍需显式绑定与结构化回执。GitHub 保存代码、PR 和 CI 证据；Retinue 保存 holder、租约、任务状态与协作事件。
上方配图均为固定种子的合成演示；协作图、泳道、模块和分支详情展示同一固定 任务，时间来自分阶段演示时钟。图片不包含真实业务记录，不声称真实模型闭环 已全部通过验收。当前自有代码采用 AGPL-3.0-only，第三方声明保留，历史标签许可不改写。
查看 完整版本说明、 PRD、小红书草稿； 也可打开 只读演示。
它是本地优先、可自托管的 AI agent 任务板与审计层，不是聊天壳，也不是 agent 框架。它垫在你已经在用的 agent（Claude Code、OpenAI Codex、任意 MCP 客户端，或者一个开着浏览器的人）下面。
- 一卡一持有人：同一时刻只有一个执行者握棒，只有持有人能写。别的 agent
的令牌会收到
403 holder-only-writes。 - 只可追加的回执链：认领、进度、交接、阻塞、验收全部留痕，事后改不掉。
- 验收条件写在卡上：开工前写清「怎样算完成」，任务完成记录与独立质量 核验分别解释。
- 原生 MCP 协作：
retinue-server mcp把看板暴露给任意 MCP agent；也提供 纯 HTTP + bearer token 接口。 - 运行时 exporter：只读导入 Claude Code / Codex 会话数据，按 agent 看 token 消耗，不改动来源。
- 可选 IM 适配器：飞书 / Lark 与 Telegram 桥接把聊天消息变成「意图」， 绝不直接变成命令。
- 数据主权：文件模式的事实源是一个数据目录（
org.yaml、tasks/、metrics/、nodes/），停掉写入者后复制；服务端事实源是retinue.db， 使用一致性 SQLite 快照备份。运行时源记录、外部成果、凭据与部署配置 分别恢复，详见备份说明。
手上跑着一队 AI 编程 agent 的个人和小团队：想要一块持久的看板、可观测的 回执、随时能带走的数据，又不想被托管平台绑住。单机、homelab 主机、NAS 都能跑。
以下步骤只走本机回环。凭据放在环境变量里，不写进任务卡。
本机 9219 端口必须空闲（否则 compose 会报 address already in use）。 管理员密码至少八位。
read -rsp 'Choose an admin password (at least 8 characters): ' RETINUE_ADMIN_PASSWORD
printf '\n'
export RETINUE_ADMIN_PASSWORD
docker compose up --build等日志里出现监听后再探活：
curl -fsS http://127.0.0.1:9219/api/health应返回类似 {"status":"ok","version":"0.3.0a5"}，无需登录。version
与 pyproject.toml、wheel 文件名、下次 git tag（v0.3.0a5）是同一串。
打开 http://127.0.0.1:9219/，用 operator 和上面的密码登录。默认镜像
是带登录的 v0.2 中枢，不再是旧只读面板。
先在侧栏 管理 入职执行者 worker-1，把一次性令牌存到数据卷以外。
再到 任务看板 → 新建任务：
- 标题、持有人填
worker-1（下一步要用该 agent 的令牌认领，不要填成 你自己） - 优先级
high，写上可观测的验收条件
记下任务 id（task-YYYYMMDD-NNN）。
用第 2 步的一次性令牌：
export RETINUE_AGENT_TOKEN='<one-time-agent-token>'
export RETINUE_TASK_ID='<task-id-from-the-board>'
curl --fail --request POST \
--header "Authorization: Bearer $RETINUE_AGENT_TOKEN" \
--header 'Content-Type: application/json' \
--data '{"status":"doing","note":"claimed through the agent API"}' \
"http://127.0.0.1:9219/api/tasks/$RETINUE_TASK_ID/update"curl --fail --request POST \
--header "Authorization: Bearer $RETINUE_AGENT_TOKEN" \
--header 'Content-Type: application/json' \
--data '{"progress":80,"refs":["artifact:hello.txt"],"note":"recorded the result reference"}' \
"http://127.0.0.1:9219/api/tasks/$RETINUE_TASK_ID/update"验收条件真正成立后再把卡标为 done：
curl --fail --request POST \
--header "Authorization: Bearer $RETINUE_AGENT_TOKEN" \
--header 'Content-Type: application/json' \
--data '{"status":"done","note":"acceptance checked; hello.txt matches"}' \
"http://127.0.0.1:9219/api/tasks/$RETINUE_TASK_ID/update"刷新看板。卡在 done，事件链上能看到认领、回写和完成。另一名
agent 的令牌会得到 403 holder-only-writes。
文件总线走廊见
docs/closed-loop-walkthrough.md。安装、
备份和暴露警告见 SELF_HOSTING.md。
见上方英文节的文字架构图。文件模式的事实源是运营者选定的数据目录，停掉
写入者后复制；服务端使用 retinue.db，需要一致性 SQLite 快照。运行时源记录、
外部成果、凭据与部署配置分别恢复，详见备份说明。
文件模式的 on_claim 钩子只来自 org.yaml，任务卡不能指定要执行的命令。
众卿 Retinue 用来干什么？ 把工作派给人和 AI agent 组成的混合团队，在一块自托管看板上执行，并留下可核 验的记录：谁握过这张卡、声称做了什么、验收条件是否真的通过。
支持 Claude Code、Codex 和其他 MCP 客户端吗？
支持。MCP agent 通过 retinue-server mcp 接入；不支持 MCP 的用 HTTP 接口加
受限 actor 令牌。Claude Code 和 Codex 另有只读会话 exporter 统计 token。
它是开源软件吗？ 是，当前源码采用 AGPL-3.0-only，遵守 AGPL 可免费商用，也可另购商业授权。 详见 LICENSE 和 COMMERCIAL.md。
会把我的数据传到哪里去吗？ 不会。没有遥测、没有托管控制面、没有远程账号、没有强制外呼。核心、面板、 daemon、demo、exporter 全部可离线运行。只有你显式配置的 IM 适配器会外联。
可以部署在 homelab 或 NAS 上吗？
可以。docker compose up --build 起一个端口即可；下面的十分钟走廊全程走回
环。暴露风险与备份见 SELF_HOSTING.md。
和 Vibe Kanban 这类 AI kanban 有什么不同？
众卿是「看板 + 审计边界」。agent 被当作不可信执行者：它永远不能指定要跑的
hook（hook 只来自运营者的 org.yaml）、写权限只归持有人、回执链只增不改。
看板本身就是治理面，不只是任务队列。
必须用 Docker 吗？
不必。无 Docker 的文件总线走廊见
docs/closed-loop-walkthrough.md。
Copyright (c) 2026 JKL Thinking。当前源码树采用 AGPL-3.0-only， 同时提供单独的商业授权。
- 个人和公司内部使用都免费，包括商用。
- 修改后通过网络对外提供服务，必须按 AGPL 向这些用户提供修改版本的对应源码。
- 不想履行这些要求，可以购买商业授权。 联系邮箱：jklthinking@foxmail.com。
- 已按 MIT 发布的 0.3.0a4 及以前版本永远是 MIT，不追溯。
分发和其他使用场景也须履行适用的 AGPL 条款。此说明针对该分界后的开发源码， 不改写旧发行版或标签。详见 LICENSE、NOTICE、 商业授权、贡献者协议 和 商标说明。 第三方依赖继续遵循各自许可证，声明见 THIRD_PARTY_NOTICES。
RETINUE 在 LINUX DO 社区发布与交流，欢迎在 GitHub 提交 issue 与 PR。