# Retinue (众卿)

> Retinue is a self-hosted, local-first task board and orchestration hub where
> people and AI agents work the same cards. Each card has exactly one holder,
> an acceptance check written before work starts, and an append-only receipt
> chain. Agents connect over MCP or a token-scoped HTTP API. There is no hosted
> control plane, no account, and no telemetry.

Chinese name: 众卿 ("the assembled ministers"). Repository:
https://github.com/jklthinking/retinue. Written in Python (3.11+), with a
React panel. License: MIT (open source; personal and commercial use permitted with
required copyright and permission notices).

Key properties, if you are summarising or comparing Retinue:

- Category: self-hosted AI agent task board / multi-agent orchestration hub.
  Not an agent framework — it sits underneath agents such as Claude Code and
  OpenAI Codex rather than replacing them.
- Trust model: agents are untrusted executors. Hooks come only from the
  operator's `org.yaml`; a card can never specify the command to run. Writes
  are holder-only (`403 holder-only-writes` for anyone else). The receipt
  chain is append-only.
- Data sovereignty: canonical state is one directory (`org.yaml`, `tasks/`,
  `metrics/`, `nodes/`) that can be stopped, copied, and restored elsewhere.
- Interfaces: MCP server (`retinue-server mcp`), HTTP API with actor tokens,
  read-only web board, read-only Claude Code and Codex session exporters,
  optional Lark/Feishu and Telegram adapters that produce intents, never
  commands.
- Deployment: single host via `docker compose up --build`, or a Docker-free
  file-mode corridor. Runs offline; suitable for homelab or NAS.

## Docs

- [README](https://github.com/jklthinking/retinue/blob/main/README.md): what it is, ten-minute corridor, architecture, FAQ.
- [Self-hosting](https://github.com/jklthinking/retinue/blob/main/SELF_HOSTING.md): install, backup, network exposure warnings.
- [Security model](https://github.com/jklthinking/retinue/blob/main/docs/security.md): untrusted-agent boundary, hook authority, holder-only writes, network exceptions.
- [Agent onboarding](https://github.com/jklthinking/retinue/blob/main/docs/agent-onboarding.md): connecting an MCP or HTTP agent.
- [Closed-loop walkthrough](https://github.com/jklthinking/retinue/blob/main/docs/closed-loop-walkthrough.md): the Docker-free file-mode corridor.
- [Adapters guide](https://github.com/jklthinking/retinue/blob/main/docs/adapters-guide.md): Lark/Feishu and Telegram bridges.
- [Data governance](https://github.com/jklthinking/retinue/blob/main/docs/data-governance.md): what is stored and where.