Crewlet Documentation

Crewlet is an open-source engine for orchestrating hierarchically organized AI agent companies. It treats the organizational hierarchy as the primary orchestration structure — knowledge, permissions, communication, and decisions are all scoped by position in the org chart.

New here? Read in this order: Installation → Quickstart → Choosing your stack, then dip into the concept pages for the subsystems you touch.

Rather not write the YAML by hand? An AI assistant can interview you and author it — see Authoring with an AI assistant.

Getting Started

Installation — Install the binary or run the signed container image (a release’s tag, or main, rebuilt on every push to main), and verify either; why there is no infrastructure to bring up, and what the compose profiles are for
Quickstart — Build a four-agent company and watch its first turn, with LLM provider options (Anthropic / OpenAI / any OpenAI-compatible)
Choosing Your Stack: the decision guide for every external dependency (the LLM provider, the tracker and knowledge base, the code host, chat and the code sandbox), what each path sets up for you, and what you must create manually
Authoring with an AI Assistant — Let an AI write your company config: a step-by-step walkthrough, the company-architect skill, crewlet schema for editor autocomplete, and the crewlet validate -json fix loop
Configuration Reference — Full YAML config schema and examples

Core Concepts

How the engine works, one subsystem per page:

Overview — The org chart as execution graph, design principles, high-level architecture
Architecture — The whole engine at six zoom levels: what sits outside the process boundary and what each dependency is for, what runs inside one node under data / ingress / seats / workers, the hop-by-hop path a trigger takes from a third-party app webhook to an agent’s reply across a fleet, what a turn does and how one survives its own process, which of the four estates every table, bucket and stream belongs to, and what changes when a second node appears
Configuration — Two-tier config (ops-owned crewlet.yaml + a founder-owned revision in the store), bootstrap sequence, unconfigured state, live propagation, auth, the apply stage by stage, whole-config encryption at rest
Identity and Access — Who is acting and what they may do: the four kinds of principal, why every person holds a human seat and acts as it while a token or service account bound to none acts as the credential, the four permissions — admin, which runs the company and the engine, and one per app, tracker, knowledge and artifacts — what each opens beside the overview every signed-in principal reads, and why a seat’s transcript is its lead’s and an admin’s, the enrolment stages, why a name’s shape decides which namespace it belongs to so a login, a machine handle and a seat handle can never collide in one audit column, and the difference between the engine knowing you are nobody and the engine not being able to tell — plus where identity is KEPT: the state log’s fourth domain, its seven tables, why a claim’s uniqueness is arbitrated at the broker rather than checked by an index, what is sealed under the fleet keyring and what is deliberately in the clear, what removing somebody erases from every data node’s rows and what it cannot reach, why a stalled identity log does not stop your agents, WHAT SOMEBODY PROVES THEMSELVES WITH — the argon2id parameters and what each one buys, why a machine token is not memory-hashed, the twelve-character rule and why there are no others, and the two mechanisms that stop a sign-in endpoint being a roster and what they deliberately leave unpadded, why a failed attempt costs a wait that doubles and never a lockout — keyed on what was typed and where from, and never on an address alone, which is also why no curve stands in front of a bearer a guarded route compares — why each node keeps its own curve, and why the N-fold rate a fleet of N nodes allows is bounded by what stands behind it, and why a second-factor code is spent by the sign-in it completes — THE AUDIT FEED, what the auth category says and how often, why a failed attempt is a counter and one row per node per minute, a count per source, that never carries what was typed or whom it named, why a token’s use is on its records rather than a row of its own and its overreach is a log line, and which facts have no event at all — and the SESSION COOKIE itself: every field in the bearer and why it is there, why a re-issue writes nothing so an hour of use costs no record, why the dashboard holds no credential of its own and what its four sign-in screens do, why a cookie cannot prove it was copied and nothing pretends it can, and the two three-valued tables that answer 503 rather than 401 on a node that is merely behind — plus HOW THE FIRST PERSON EXISTS: invited or created onto a human seat the company declares, under a Tier A token like everybody after them; the two ways a person arrives on their seat — an invitation, or an administrator’s create that hands back their first password link; why an invitation arbitrates where an ADDRESS and a SEAT do and holds both while it is open, why a GET on one renders and never spends, and why absent, redeemed and expired are one refusal; and that EVERY ROUTE IS GUARDED but the ones on one exact list — five of them under /auth/ — and why that list cannot be a prefix, and how a cross-site write is refused by its Origin where CORS cannot
Scaling Out — Why one node is the design’s degenerate case rather than a lesser path, what a node is (data / ingress / seats / workers), the node that holds no data at all and how every node reaches the one replicated estate every data node holds whole, the five kinds of coupling that had to be resolved and which one a lock actually fixes, what the fleet shares in the coordination slot versus what stays per-node, the measured broker numbers the lease TTL and prefetch cap come from, and what the design does not promise
Object Store — Where a company’s files live: the row that names a file replicated like everything else, its bytes stored as one object per upload, under a key minted for that upload and never reused, in one store the whole fleet shares — a JetStream object store bucket on the fleet’s own broker at stream.replicas copies (nats, the default) or an S3-compatible bucket (s3, with the permissions its identity needs), chosen by every node’s store.objects and recorded once so a node configured otherwise refuses to boot. Uploads that store the object before the row and are checked against the row’s SHA-256 on every read, the object-collector duty’s hourly collection of objects no row names and of unfinished uploads, its daily audit for missing and damaged files, why a deletion needs no lock, the objects_missing alarm, choosing a backend, why there is nothing to drain, and how far it scales. Artifact uploads are reserved against the quota before a byte moves, read back and verified before the version is recorded, and an unchanged file is carried rather than copied, never across artifacts
Coordination: The fleet’s shared store and the line between it and the node’s own database: the three-valued answer every question here returns, which direction each contract fails in when the store cannot be reached, why a listing is certified against the stream’s own key index and read back from its leader so it is complete or unknown but never short, why a single key is read from the stream’s leader and a compare-and-set waits out a write the leader still has in flight rather than reading it as a lost race, the slots a fleet is discovered from, why every retention is a bucket’s age rather than a per-write TTL and what sweeps the removal markers a bucket with no age would keep for ever, why fleet duties keep their leases in a bucket apart from the seats’, and what stays node-local or per-process on purpose
Seat Ownership: How a fleet decides which node runs which seat, and why no two ever run the same one: TTL leases with epoch fencing, fair-share placement with give-back, the two release modes, freshness-based admission, the line between a copy that is behind and one that is wrong (and why lag at any size never moves work), owner-only inbox and sandbox-control attachment, the durable subscription that holds an unowned seat’s mail, the broker settings that must not delete it, how a removed seat’s mailbox is found and retired after a grace period, and why a wedged-but-alive node ends its own process
Control Plane — How every node converges on one company config: the shared activation pointer whose own revision is the epoch, the reconcile poll, per-node apply status (ok / error / degraded), the posture a lagging node takes (serve / wait / shed / isolated / stuck), what a running turn sees through a live apply, and what /health and /ready report
Secret Store — The company’s encrypted credentials on the coordination KV, read by every node and consulted ahead of the process environment when resolving ${VAR}: crewlet secrets set/list/unset/get/rekey, the /secrets API they write through, the -secret-store provisioning sink that hands minted credentials straight to the engine, the engine’s own key beside the operator’s credentials and never in their namespace, rotating the keyring — the identity estate’s sealed values included — with nothing in flight lost, store-wins precedence, and the Tier A root-of-trust boundary
Organization Model — Hierarchy, departments, teams, roles (seats), handles
Humans in the Org Chart — Human seats (kind: human): hierarchy membership, contact identities, notify delivery, escalation terminus, prompts and lookup — and the person at the dashboard: invited or created from their vacant seat in the org chart, holding that seat for as long as they are here, signed in as themselves and acting as it, the Inbox and My work that answer for them, and every write made as them
Agent Runtime: how a configured role becomes a running seat, the states the dashboard shows, what each phase’s prompt is built from (including the chat thread a turn is handed rather than told to fetch), the built-in tools, and graceful shutdown
Turn Engine — Per-agent executor / reviewer loop, how the engine decides a turn delivered, delegating to workers, colleague-surface tools, per-phase LLM models
Subscription LLM Backends — Run agents on a coding CLI you already subscribe to (Claude Code, Codex, Gemini CLI, OpenCode, …) instead of a metered API key: the two modes (a text model behind the engine’s tool loop, or the CLI running the executor itself as a detached run with the seat’s tools bridged in), per-seat state isolation, the in-prompt tool-call channel, how the answer is found in a CLI’s own output and what happens when the profile no longer matches it, crewlet llm login, falling back to a key when the window is spent, and the other shape — an OAuth proxy behind an ordinary HTTP entry, and what that moves onto you
Code Sandbox — Sandboxed coding-agent execution: the run_sandbox tool, providers.sandbox as a catalogue with a per-seat run_in (including self, for a seat whose executor already has a shell), E2B cloud/self-hosted, local boxes (direct or containerised, on a subscription login), Claude Code & OpenCode runners, git-auth recipes, mid-run clarifications
Tool Skills: Knowledge-base-sourced prompt fragments (Confluence pages, or the engine’s own) that teach agents how to use each tool / MCP server, and how every node keeps its copy current: a walk at boot, on an apply that moves the skills source and every 10 minutes, a read of the one page a webhook names broadcast to the rest of the fleet, and a bounded retry behind a walk that failed
Tool Capabilities — How the engine stays tool-stack agnostic: capability prose + MCP annotations, no hardcoded tool names
Event System: EventQueue, topics, routing, inbox batching, listing the durable subscriptions a broker holds, reading the fleet’s history from every node’s own store (and why a departed node’s detail departs with it), distributed tracing
Integration Reconcile — What checks that an integration still works: the finding vocabulary every third-party app reports in, why the excess-access advisory is ranked last, a cadence derived from who has to act rather than from what failed, the fleet singleton that runs it, how a seat’s account at a third-party app is named, and what the loop deliberately will not do (tear anything down, or rotate a credential that works) — it does register the webhooks and create the accounts, because connecting an integration is the permission
The Tracker — the two shapes a company’s work can take: the engine’s own tracker (tracker.backend: native, the default — every change a record on an ordered log the fleet shares, applied into identical SQL copies on every data node, with a board, seat tools and an MCP surface), or an external PM tool the engine deliberately mirrors none of
Scheduling — Role/unit-scoped cron-style recurring work (standups, audits, nightly jobs)
Knowledge System — Shared knowledge behind the knowledge.Searcher seam — exactly one backend per company, either the engine’s own pages (keyword, semantic or both fused) or a live Confluence search, who read each page and who links to it, what a folder and a draft are, edited from the dashboard as the signed-in person — plus the private agent_diary, and crewlet search eval for measuring the semantic half on your own vectors
Artifacts: Pages, documents, slide decks and native sheets that people and agents publish for each other: versions that name their base and carry unchanged files, shares on a five-role ladder under the artifacts app that gates authoring only, the serving origin that holds no credential and re-authorizes every document, a shared datastore whose writes are decided where they are applied from authority stamped at the API, presence that is told and never stored, what an agent may and may not do, and the security model in one table
Agent Learning — Reflection loop, skill induction, episodic memory, counterparty profiles
Conversation Sessions — What a seat already said in one Slack thread / issue / pull request, carried into that conversation’s next turn: the entry shape and its elision budgets, which turns are recorded, why the key is the conversation and the dedupe is the work key, and why this is a structured ledger rather than a transcript replay
One-on-Ones — Manager↔report coaching as a usage pattern over the scheduler + A2A channels + learning loop
Decision Framework — DACI model for multi-agent decisions, and the structured ask a decision is recorded as

Integrations

Connecting the external surfaces agents work on. The tracker and the knowledge base are the two that are optional: the engine ships its own and runs them by default, so Jira and Confluence are the path you take when your people already live there.

Jira

An alternative to the engine’s own tracker. Cloud or Data Center: webhook routing by mention / assignee / watcher / project lead, derived seat account ids, per-role MCP tools, and crewlet jira provision

Confluence

An alternative to the engine’s own knowledge base, and the one that searches as the asking seat so Confluence’s own page permissions are the boundary. Cloud or Data Center: live CQL search, page-change routing, tool-skill pages, and crewlet confluence import

GitLab

gitlab.com or self-hosted: API-provisioned per-agent service accounts, crewlet gitlab provision, webhook routing, per-role MCP tools, sandbox code authoring

GitHub

github.com or Enterprise Server: one GitHub App per agent (create it, then install it) with three access tiers, webhook routing by review request / assignment / review verdict / mention, derived seat logins, participant fan-out, organization or per-repository hooks, and crewlet github provision

Datadog

Monitor alerts as inbound events through the Webhooks integration: routing by monitor tag with a required fallback seat, a trigger and its recovery as one conversation, and shared-token verification because Datadog cannot sign a body

Slack

One app per agent: crewlet slack provision builds and installs them from a manifest, per-seat webhook routing with thread follows, a text-carrying working indicator, and the Slack MCP tool server

Mattermost

Self-hosted open-source chat: one bot account per agent, crewlet mattermost provision, a websocket event fleet instead of webhooks (no public URL needed), and thread routing

Guides

Tools & MCP — Built-in tools, MCP integration, the two-value tool-origin grammar the dashboard groups on, and how you extend a binary that loads no plugins
Deployment — The single host, the compose profiles, the stream beyond one host (an embedded cluster or an external NATS one, with its auth and TLS), the event store, tracing, logging (levels, the three formats, colour, a rotating log file beside stderr — with its own shape and level, or taking the stream over entirely — and the embedded broker’s own output, which is its own switch)
Budgets and Spend — The two numbers that describe what the models consumed and why they are never comparable: the budget counter a ceiling is enforced on, per day, ISO week and month on the company’s clock, and the spend rollup that says where the tokens went — the live 24 hours from each node’s projection, and every named window of up to 90 company days from the replicated usage domain, the same on every node. How far back each reaches (181 days of spend, 30 of turns), the four bands a phase chart draws, the provider split, the cache share, and the seats’ auxiliary model — what it spent by stage and purpose, which of it a turn and its task pay for, a person’s questions as their own row, why the counter and the rollup can still differ, and what is not counted (embeddings)
Backups & Restore — crewlet backup against a running node, what the directory it writes contains and what the copy is a copy of, the cold runbook behind it, restore ordering and its hazards (epoch rewind, node identity), and which losses are survivable without a backup
Running a Fleet — When to run more than one node, node roles (and nodes that hold no data), seat placement, draining and rolling upgrades, and removing a data node for good without leaving the company’s files a copy short
Running One Agent Somewhere Else — Put a single seat on a host that can reach what it needs — an internal API, a licensed binary, a GPU, a lab network — without moving the company: what a satellite is, whether it holds data — the whole replicated estate, the identity directory included — or is a small disposable node that holds none and reaches the estate through one that does, on a host that holds the fleet keyring either way, what moves with the seat (its MCP servers above all), what the node still needs outbound, and what a pin costs when the host is down
The Org Builder: editing the organization, and creating the company, from Org chart › Edit org: the one company document /config serves and writes, the org chart in it beside the settings, and what reading and saving it takes, what the builder shows and why, arriving from a link, creating a company from a template, reading the organization on the structure chart, the reporting chart and the table (their keys, the lead chip and reordering), how a draft is checked by sending the save as a dry run, what each editor can and cannot change and why, the integration fields a seat carries, the tabbed node editor and its markers, why a new human seat is vacant until somebody is put on it, what moving and deleting do and why a seat keeps its kind, reviewing and saving as one write (including a write whose answer never arrives), following the revision until the nodes apply it, keeping a company.yaml in step, with every handle and key declared, since a file is minted afresh on every import, keeping a draft across a reload and what asks before work is left behind, updating a draft when somebody else saves first, and undo, redo and the keyboard
Configure via API — End-to-end recipes for bootstrapping a company with crewlet config import or one PUT /config, then evolving it one entity at a time through /config/* — a seat, a unit, a provider, an MCP server — and why a seat’s handle and a unit’s key never change
The Work Tracker — The product guide to the engine’s own tracker: projects and keys, everything a task carries, the catalogue of types and fields a company declares, the five view shapes and the six every container has without anybody saving one, what a board groups on and why the due bands are cut on the company’s own day rather than each reader’s, why the trash is a query rather than a shape, the timeline’s bars, bands and dependency arrows and what it refuses to place, who is carrying how much and the two things the workload will not do, manual board order and what a re-spread is, a person’s own inbox, queue and pins and the three different authorities over them, the tags any seat may declare and the rules that keep them one grouping, the eighteen tools a seat has and the five that count as a delivery, how a move carries an item and its whole subtree to another project, the one wake that is about something other than a task, why a handle is checked before it is stored, what a person reaches through the dashboard and their own assistant, and the difference between removing, deleting and purging
Replication — How the fleet’s copies of the company’s work stay in step: the three numbers a reader must not fold together, the three outcomes a write has and what to do with pending, what an acknowledged write has actually reached at each topology, the two regimes above and below the trim floor, replication lag as two positions, what a bulk gesture costs every peer, and what the design does not promise
Search — How a knowledge search is answered and what to do when it is slow: the two rankers and the bucket both of them carry, when a fleet divides the scan and the floor below which it does not, why the merge is by score and only then fused, why BM25 stays comparable across a divided scan, and what a partial answer names rather than silently truncates
Read Consistency — Picking how fresh an answer has to be: the four levels and what each costs, how linearizable works as a barrier append rather than a field check, the fourteen read refusal codes and every write refusal, with a remedy each, completeness as a fact separate from freshness, and the three things no level can strengthen
Retention — What the log keeps and why it sometimes will not shrink: the one number to watch, the six trim terms in plain words, why a company that never backs up never trims, snapshots and the join runbook, eviction and readmission, what a full log refuses, the storage forecast, and the recovery-operations profile
Serving Artifacts: Giving artifacts an origin of their own: the api.artifacts listener, the two origin modes and what validation refuses, the three self-hosted shapes (a wildcard on a domain of its own, a second hostname, a second port) with their DNS and TLS, what a reverse proxy must and must not do, checking it works, and sizing the object store
Authoring Artifacts: Choosing a kind, the page contract the engine enforces at publish (paths, types, limits, scripts and styles, what a page cannot do), capabilities and the pinned runtime, the artifact kit, declaring shared data with presets and column rules, publishing from the dashboard, the CLI and an agent, and what to check before sharing

Reference

CLI — Command reference
API Endpoints — REST API routes and schemas, the WebSocket protocol (the socket reads and pushes; REST writes), the health envelope, /auth (signing in, invitations, step-up and second factors), /iam (the identity directory and the seats each person holds), the tracker and page surface over the native backends, /operator/mcp — the company’s own tracker and knowledge base served to your AI assistant over MCP — and /operator/act, where the dashboard writes as the principal its session resolves to, and how the dashboard’s own files are served, cached and compressed
Artifact Runtime: The window.crewlet contract 1.0 a page runs against: how a page reaches the engine through its host, contract versions, connection, identity, data (every op and verdict), per-viewer state, presence, assets, opening links, theme and errors
Slide Format: The format a slides artifact holds, Claude’s slide format without its project/ prefix: the deck index, one <section> per slide on a 1920 by 1080 stage, the closed element, attribute and inline-style subset with each value’s grammar, inline drawings, images and typefaces as files of the version, the bounds, what is refused and what to write instead, and how a deck is read, edited, presented, followed and printed
Dashboard Spec: The format a dashboard artifact holds: filters as closed choice sets, datasets from the artifact’s store, the engine source catalogue (the tracker, spend and the agents, each answered as the viewer), version files and deterministic calculation steps, the widgets on the twelve-column grid, refresh, export, the comment anchor and every bound
Artifact Capacity: The service objectives artifacts are measured against, what bounds their scale, and the reproducible spikes behind every bound: datastore write rate and footprint, origin isolation, contention, sandbox streaming, the strict script policy, edits, presence fan-out and the object store under a publish
Dashboard Design System — The dashboard’s information architecture and its visual system: the one sidebar and the three nouns that keep it one (a sidebar row is a workspace or a kept object, a section is a path drawn as a tab, an object tab is a query on an object’s page — and nothing is two of those), the route table and the gate that holds it against the router’s own resolver, the frame every screen wears and its three breakpoints, the sign-in screens that sit outside it, why Home is the landing screen and how its reader arranges it (the board, and the widgets every section offers for it), the Inbox as a focus split (what needs you, then updates, each read in full beside the list and answered there), Work’s scope named and switched in the trail, the mode and the theme and where each is chosen, the one rule (colour carries state, never identity) and its bounded exceptions, an agent’s chosen profile icon among them, a palette whose every contrast and separation claim is recomputed from the shipped stylesheet in both themes, the four rules that keep a running turn’s transcript from moving under the reader, ⌘K, acting as yourself (every write control is shown, and disabled with its reason when you cannot make it), honest empty states, the turn trace, how it is built (one REST transport, one write client, src/contract/ and the gates that hold it), why the built bundle is committed, and the rules a change has to keep — tokens, never money, among them
Metrics — Every instrument the engine exports, generated from the catalogue: what each one measures, its unit, its attributes, and the failure it makes visible. Plus the OTEL_* variables that switch the export on, and what is deliberately not exported
Alarms — Every condition the engine raises about itself, generated from the alarm table: what each one means and what to do about it. One table, reaching you as a gauge and as a named log line on entry and exit
Service Objectives: what the engine promises about artifacts as numbers an alarm holds it to: publish success and latency, a served document’s first byte, a frame becoming ready in the viewer’s browser, the datastore’s verdicts, each an event objective over thirty days with its reason; where each is measured, the two burn-rate pairs the objective_burn alarm judges, and the ready report the dashboard sends and the limits it is held to
Environment Variables — All configuration env vars

Part of Crewlet. Generated from crewlet/crewlet main at aee55b6.