Run an AI agent company — not a pile of prompts.

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.

Installation Quickstart Authoring with an AI assistant

name: "Acme AI"
mission: "Ship AI-powered products fast"

policies:
  - "All features need PM sign-off before development starts"
  - "Communicate decisions in writing"

providers:
  llm:
    default:
      type: anthropic
      model: claude-sonnet-5
      api_keys:
        - "${ANTHROPIC_API_KEY}"
  embeddings:
    type: openai
    model: text-embedding-3-small
    api_key: "${OPENAI_API_KEY}"        # used by the agent-learning subsystem
                                        # (diary vector search + episode recall)

# Org-wide roles — these sit above all teams and manage team leads.
roles:
  # You, in the chart. A `kind: human` seat is addressable but never
  # spawned (no runtime, no inbox, no LLM) — it gives escalation a person
  # to stop at, and lets agents recognise your activity on the surfaces
  # you connect later. Needs at least one `contact` identity; scope
  # `manages` to the top seat so you aren't copied on everything.
  - name: Your Name
    kind: human
    manages: [CEO]
    contact:
      slack_user_id: "${SLACK_FOUNDER_USER_ID}"   # your Slack member ID

  - name: CEO
    handle: ceo                 # see the note under this block — set these now
    goal: "Set product vision, prioritize initiatives, and make final calls"
    backstory: "Experienced founder who balances speed with quality"
    manages: [CTO, PM]
    # A zero-integration way to see your first agent turn: a scheduled task.
    # Delete this once you have real integrations delivering work.
    schedules:
      - name: hello-crewlet
        cron: "*/5 * * * *"
        task: "Write a short status note on what the company should focus on this week."

# Flexible org structure — use any nesting depth and unit types.
units:
  - name: Product Management
    type: team
    lead: PM
    purpose: "Define what gets built and why"
    roles:
      - name: PM
        handle: pm
        goal: "Turn business goals into clear specs and prioritized backlogs"
        backstory: "Data-driven product manager who writes crisp requirements"
        manages: [Engineer]

  - name: Core Engineering
    type: team
    lead: CTO
    purpose: "Build and ship the product"
    goals:
      - "Ship MVP in 4 weeks"
      - "Maintain test coverage above 80%"
    roles:
      - name: CTO
        handle: cto
        goal: "Set technical direction, make architecture decisions, unblock engineers"
        backstory: "Senior architect with deep distributed systems experience"
        manages: [Engineer]

      - name: Engineer
        handle: eng
        goal: "Implement features, write tests, and ship quality code"
        backstory: "Full-stack engineer who writes clean, tested code"

debug: true

providers:
  queue:
    type: pulsar
    url: "pulsar://localhost:6650"        # the compose broker
  database:
    dsn: "postgresql://crewlet:crewlet@localhost:5432/crewlet"  # the compose DB
  knowledge:
    type: pgvector

api:
  host: "0.0.0.0"
  port: 8000        # a port > 0 makes `crewlet run` serve the API EMBEDDED in
                    # the engine process (dashboard + webhooks included) — one
                    # process is the whole stack. (Avoid 8080: that's Pulsar's
                    # admin port in the bundled compose. The full Nimbus example
                    # uses port 80 instead so webhook URLs need no port suffix —
                    # see examples/nimbus.config.yaml for the trade-offs.)
  auth:
    tokens:
      - id: founder
        token: "${CREWLET_API_TOKEN_FOUNDER}"

pip install crewlet
export CREWLET_API_TOKEN_FOUNDER="$(openssl rand -hex 32)"
export ANTHROPIC_API_KEY="sk-ant-..."
export OPENAI_API_KEY="sk-..."          # embeddings
export SLACK_FOUNDER_USER_ID="U0FOUNDER"  # your Slack member ID (the human seat)

Read the quickstart

Getting Started

Installation

Prerequisites, install extras, and the local Pulsar + PostgreSQL stack

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 tracker and knowledge base, the code host, the code sandbox, chat, email — 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

Configuration

Two-tier config (ops-owned config.yaml + founder-owned versioned PostgreSQL), bootstrap sequence, unconfigured state, live propagation, auth, snapshot/rollback, whole-config encryption at rest

Secret Store

Encrypted secret_values table consulted ahead of os.environ when resolving ${VAR}: crewlet secrets set/list/unset/get/rekey, the --secret-store provisioning sink that hands minted credentials straight to the engine, 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

Agent Runtime

Agent lifecycle, states, execution model, graceful shutdown

Turn Engine

Per-agent Plan / Execute / Review loop, sub-agents, colleague-surface tools, per-phase LLM models

Code Sandbox

Sandboxed coding-agent execution: the run_sandbox tool, E2B cloud/self-hosted, Claude Code & OpenCode runners, git-auth recipes, mid-run clarifications

Tool Skills

Knowledge-base-sourced prompt fragments (Confluence or Plane pages) that teach agents how to use each tool / MCP server

Tool Capabilities

How the engine stays tool-stack agnostic: capability prose + MCP annotations, no hardcoded tool names

Event System

EventQueue, topics, routing, inbox batching, distributed tracing

Task Engine

ExecutionTracker, external PM tool integration

Scheduling

Role/unit-scoped cron-style recurring work (standups, audits, nightly jobs)

Knowledge System

Query-time knowledge-base search behind the KnowledgeSearcher seam (Confluence CQL or Plane page search — one backend per org) + private agent_diary

Agent Learning

Reflection loop, skill induction, episodic memory, counterparty profiles

One-on-Ones

Manager↔report coaching as a usage pattern over the scheduler + A2A bus + learning loop

Decision Framework

DACI model for multi-agent decisions

Integrations

Connecting the external surfaces agents work on:

Plane

Self-hosted tracker and knowledge backend in one product: webhook routing, per-role MCP tools, knowledge search, crewlet plane import, tool-skill sync, skill promotion, crewlet plane provision, and a complete local docker-compose loop

Jira

Webhooks (Forge app for Cloud, direct for Data Center), MCP tools, per-team projects

Confluence

Webhooks, MCP tools, query-time CQL knowledge search, 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

Per-role remote MCP tools for read/review/track; sandbox code authoring

Slack

One-app-per-agent setup with automated app provisioning via crewlet slack provision (App Manifest APIs), thread routing, and the per-phase working indicator

Custom Transports

Build your own notification transport