RetinueOS

RetinueOS is a persona-driven personal agent control plane. Local-first, self-hostable, and provider-agnostic — bring your own LLM API keys.

What this is: a small staff of persona-shaped agents you hire, assign tools to, and delegate work to, with every destructive action gated behind your approval by default.

What this isn't: a general chat UI, a multi-tenant SaaS (one shared password, one operator), or a place to run arbitrary local/stdio MCP servers or hand-coded connectors — external tools are remote HTTPS MCP servers only.

A TypeScript/Hono backend orchestrates personas via LangGraph.js; a Next.js frontend talks to it over REST and SSE. Both deploy via Docker Compose.

Quick start

git clone https://github.com/cjsissingh/retinue.git
cd retinue
cp .env.example .env
# edit .env: set AUTH_PASSWORD and at least one LLM provider key
# (ANTHROPIC_API_KEY and/or OPENAI_API_KEY)

docker compose up --build

Then visit http://localhost:3000. If neither provider key is set, RetinueOS still lets you sign in with AUTH_PASSWORD, but blocks every other page behind a "no one's able to work yet" screen with the same instructions above, rather than letting you hire personas and dispatch jobs that would otherwise fail silently once they reach the model call.

That's enough for a local, localhost-only install. Putting RetinueOS on a server — every environment variable, HTTPS/reverse-proxy setup, and connecting Google — is Self-hosting.

Where to go next

• Operating RetinueOS — hiring personas, tool permissions, routines, and approvals, once it's running.
• Self-hosting — every environment variable, Web Push, HTTPS, and upgrades.
• Connectors — give a persona access to Gmail, Calendar, or any remote MCP server.
• Control-plane MCP — connect Claude Code, Cursor, or another agent into RetinueOS.
• Self-host Google Workspace MCP — run your own Workspace MCP server if you're not enrolled in Google's Developer Preview.

Source and architecture decisions

RetinueOS is open source at github.com/cjsissingh/retinue. Standing architecture decisions (why LangGraph.js, why three memory stores, the control-plane policy layer) live in the repo's docs/adr/ and aren't duplicated here — they're engineering rationale, not operator documentation.