RETINUE 众卿 — a self-hosted task board for humans and AI agents

Website & offline demo · FAQ ·
English · 简体中文

RETINUE's Chinese name is 众卿 ("the assembled ministers").

RETINUE is a self-hosted task board and orchestration hub for a mixed team of
people and AI agents. It keeps one durable baton per piece of work: a task
card with a holder, acceptance checks, and an append-only receipt chain. You
run the board, the agents claim work, they write back, and you accept or send
the card back. There is no hosted control plane and no telemetry.

Self-hosted AI agent orchestration for one person or a small team: run the
board on your own machine, coordinate Claude Code, Codex and any MCP-capable
agent from it, and keep every task, receipt and metric in a directory you own.

Ten-minute corridor

The path below stays on loopback. Credentials stay in the environment, never
in a card.

1. Start the hub with Compose

Host port 9219 must be free (docker compose fails with "address already
in use" otherwise). The admin password must be at least eight characters.

export RETINUE_ADMIN_PASSWORD=changeme1
docker compose up --build

Wait until the logs show the hub listening, then:

curl -fsS http://127.0.0.1:9219/api/health

That returns JSON like {"status":"ok","version":"0.2.0a2"} 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.2.0a2). 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.

2. Open a card

Onboard the agent first: sidebar 管理 → prepare an executor with actor
id worker-1, save the one-time token outside the data volume. Then open
任务看板 → 新建任务 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.

3. Agent claim

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.

4. Write back

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"

5. Acceptance

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.

Architecture (one page)

 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

Canonical state lives in one operator-chosen directory. Stop the process and
copy that directory to take the data away. Agents never choose on_claim
hooks; those come only from org.yaml.

License

RETINUE is source-available under the PolyForm Noncommercial License
1.0.0 (SPDX: PolyForm-Noncommercial-1.0.0). See LICENSE.md
and NOTICE.

Free for noncommercial use: personal projects, study, research, charities,
educational and government research institutions — including self-hosting
and modification.
Any commercial use — hosted services, resale, paid installation for a
customer, or use inside a for-profit organization — requires a separate
commercial license from JKL Thinking. Ask through the repository's issue
tracker. Commercial rights are reserved exclusively to JKL Thinking.
Versions published earlier under FSL-1.1-Apache-2.0 keep the license they
shipped with; every later version is PolyForm-Noncommercial-1.0.0 only.

The RETINUE name, the Chinese name 众卿, and the marks stay with JKL
Thinking. Official images and official support channels will be labelled in
the public repository. A fork or a third-party image is not official
RETINUE.

Community

RETINUE is announced and discussed on the LINUX DO community.
Issues and pull requests are welcome on GitHub.

众卿 RETINUE（简体中文）

项目主页与离线 Demo · 常见问题 · English

自托管的多智能体协作与任务管理系统：在自己的机器上跑一块任务板，统一指挥 Claude Code、Codex 以及任意支持 MCP 的智能体，任务卡、回执与用量全部留在你自己的目录里。

RETINUE 是一套可自托管的多智能体任务看板与编排中枢。每一件工作对应一张
任务卡：有持有人、有可观测的验收条件、有只可追加的回执链。你来跑看板，
agent 认领，回写结果，你验收或退回。没有托管控制面，也没有遥测。

十分钟走廊

以下步骤只走本机回环。凭据放在环境变量里，不写进任务卡。

1. 用 Compose 起完整中枢

本机 9219 端口必须空闲（否则 compose 会报 address already in use）。
管理员密码至少八位。

export RETINUE_ADMIN_PASSWORD=changeme1
docker compose up --build

等日志里出现监听后再探活：

curl -fsS http://127.0.0.1:9219/api/health

应返回类似 {"status":"ok","version":"0.2.0a2"}，无需登录。version
与 pyproject.toml、wheel 文件名、下次 git tag（v0.2.0a2）是同一串。
打开 http://127.0.0.1:9219/，用 operator 和上面的密码登录。默认镜像
是带登录的 v0.2 中枢，不再是旧只读面板。

2. 开一张卡

先在侧栏管理入职执行者 worker-1，把一次性令牌存到数据卷以外。
再到 任务看板 → 新建任务：

标题、持有人填 worker-1（下一步要用该 agent 的令牌认领，不要填成
你自己）
优先级 high，写上可观测的验收条件

记下任务 id（task-YYYYMMDD-NNN）。

3. Agent 认领

用第 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"

4. 回写

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"

5. 验收

验收条件真正成立后再把卡标为 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。

架构一页图

见上方英文节的文字架构图。事实源是运营者选定的一个数据目录；停进程、拷
走目录，数据就带走了。on_claim 钩子只来自 org.yaml，任务卡不能指定要
执行的命令。

许可证

众卿 RETINUE 采用 PolyForm Noncommercial License 1.0.0（源码可用的
非商业许可证，SPDX 标识 PolyForm-Noncommercial-1.0.0）。全文见
LICENSE.md，版权与商标见 NOTICE。

非商业用途免费：个人自用、学习研究、公益与教学科研机构，均可自托管、
修改、分发（保留许可证与署名）。
任何商业用途——商业托管、转售、替客户收费装机、营利组织内部使用——
都需要向 JKL Thinking 另行取得商业授权，请通过仓库 issue 联系。
商用权利由 JKL Thinking 独家保留。
此前以 FSL-1.1-Apache-2.0 发布的历史版本仍按其发布时的许可证执行；
此后的所有版本均仅以 PolyForm-Noncommercial-1.0.0 发布。

RETINUE 与「众卿」名称、标识权利由 JKL Thinking 保留。官方镜像与官方支持
渠道将在公开仓库中标注。第三方 fork 或镜像不是官方 RETINUE。

社区

RETINUE 在 LINUX DO 社区发布与交流，欢迎在 GitHub 提交 issue 与 PR。