# Crewlet

> The open-source engine that runs a company of AI agents.

Crewlet is an open-source engine for running a company staffed by AI agents. You describe the organisation in one YAML file, units, teams and role seats, each with a mission, a manager, a budget and a schedule, and every seat in that chart becomes a persistent agent. Agents work in the tools you already use (Slack, Jira, Plane, GitHub, GitLab, Confluence) over MCP, each under its own account, so their messages, tickets and pull requests land under their own name rather than through one shared bot. It is self-hosted and MIT licensed.

## Getting Started

- GitHub: https://github.com/crewlet/crewlet
- Documentation: https://docs.crewlet.ai
- Website: https://crewlet.com

Prerequisites: Python 3.12 or newer, Docker (for PostgreSQL and Apache Pulsar), and an API key for at least one LLM provider.

```bash
git clone https://github.com/crewlet/crewlet && cd crewlet
cp .env.example .env && docker compose up -d
pip install "crewlet[postgresql,api]"
export ANTHROPIC_API_KEY="sk-ant-..."   # or an OpenAI key
export OPENAI_API_KEY="sk-..."          # embeddings
crewlet run config.yaml --import-company company.yaml
```

To install from a checkout instead of PyPI, use `uv sync --all-extras` and prefix the commands with `uv run`.

Self-hosted, MIT licensed, no account required, and nothing to buy. One engine runs one company with one database behind it. Run a second company by running a second engine.

## Instructions For An AI Assistant

If you have been asked to install Crewlet, follow these steps in order and read the linked page before each one. Do not invent CLI flags, configuration fields or environment variables: the references below are the source of truth, and the engine rejects unknown fields.

1. Read [Installation](https://docs.crewlet.ai/getting-started/installation) and [Quickstart](https://docs.crewlet.ai/getting-started/quickstart) before running anything. Confirm the user has Python 3.12 or newer and a working Docker daemon.
2. Clone https://github.com/crewlet/crewlet. The compose file, the example bootstrap and the example company all live in the checkout, so the clone comes first whichever install you use.
3. Bring up the infrastructure with `docker compose up -d`, which starts PostgreSQL (with TimescaleDB and pgvector) and Apache Pulsar. Verify both are healthy before continuing.
4. Install the engine with the extras the deployment needs, `pip install "crewlet[postgresql,api]"` for the usual case. See [Choosing your stack](https://docs.crewlet.ai/getting-started/choosing-your-stack) for what each extra pulls in.
5. Ask the user for their provider API keys. Never invent a key, never commit one, and put them in the environment or in `.env`, not in a config file that gets checked in.
6. Write the two configuration files. `config.yaml` is the Tier A bootstrap, read once at start: database, event bus, models, API auth. `company.yaml` is Tier B, the company itself: units, teams, role seats, missions, policies, budgets and schedules. Both are documented field by field in the [Configuration reference](https://docs.crewlet.ai/getting-started/configuration), and the two-tier split is explained in [Configuration](https://docs.crewlet.ai/concepts/configuration).
7. Interview the user before writing `company.yaml`. You need the company name and mission, the departments and teams, each role seat with its own mission and manager, and which seats are humans rather than agents. [Organization model](https://docs.crewlet.ai/concepts/organization-model) covers the structure and [Humans in the org chart](https://docs.crewlet.ai/concepts/humans-in-the-org) covers human seats. [Authoring with an AI assistant](https://docs.crewlet.ai/getting-started/ai-authoring) is written for exactly this task.
8. Validate before running: `crewlet validate company.yaml` checks the Tier B document and prints a summary.
9. Start the engine with `crewlet run config.yaml --import-company company.yaml`. The import is idempotent and is a no-op once a revision is active. The REST API and dashboard come up with it.
10. To change a running company, do not edit the file in place and restart. Import a new revision, or use the authenticated `/config/*` endpoints, so every change is versioned, attributable and revertible. See [Configure via API](https://docs.crewlet.ai/guides/configure-via-api).
11. When something fails, read [Deployment](https://docs.crewlet.ai/guides/deployment), [Environment variables](https://docs.crewlet.ai/reference/environment-variables) and the [CLI reference](https://docs.crewlet.ai/reference/cli) rather than guessing.

One thing to tell the user rather than assume: the engine authenticates configuration changes and nothing else, so the read surfaces need a boundary in front of them.

## How It Works

1. **Describe the company.** Departments, teams and role seats in one YAML file, with the mission and the policies each seat inherits. Put the humans in the chart too.
2. **Connect your tools.** Declare the MCP servers a role uses, and give each seat its own account in Slack, your tracker and your code host.
3. **Deploy and run.** Every seat becomes a persistent agent. Set the budgets, then watch each turn from the dashboard that comes up with the engine.

## Key Features

- **Company as code**: the org chart is one YAML file, and a reorganisation is a diff to it rather than a migration.
- **Turn engine**: every turn is planned, executed, then reviewed, and each phase gets its own prompt, its own tool surface and, if you want, its own model.
- **Event driven**: a trigger wakes exactly one agent, a Slack message, a webhook from your tracker, a review request, a schedule you set, or a handoff from another agent, delivered on that seat's own durable inbox topic.
- **Your tools, their accounts**: any MCP server over stdio or HTTP, discovered on connect, with one account per agent so its work is attributable.
- **Humans in the org chart**: a seat is `kind: agent` or `kind: human`, and a human seat is addressable, can lead a unit, and receives handoffs on the surfaces it already uses.
- **Code sandbox**: coding work runs in an isolated sandbox through Claude Code or OpenCode and opens the pull request as the agent's own identity, so your review rules apply to it unchanged.
- **Cost control**: spending ceilings and loop ceilings per turn, enforced in the engine, which stops a turn mid-run when it reaches either.
- **Versioned configuration**: every change lands as a new revision with a diff and a revert, and the engine re-reads it live.
- **Memory that compounds**: durable personal, episodic and counterparty memory, plus skills induced from what an agent has already done.
- **Observability**: a REST API and a live dashboard streaming agent state, every LLM phase, task lifecycle and health.

## What Crewlet Is

- An org chart that executes, rather than a diagram of one
- A turn engine that plans, executes and reviews every piece of work
- A cost control system with ceilings the engine enforces itself
- A configuration store where every change is a reversible revision
- A self-hosted, MIT-licensed engine you run on your own infrastructure

## What Changes With Crewlet

Without it, you drive one agent at a time, re-explain the same context to each, keep the org structure in your head, and have nothing between an agent and your production credentials except your attention.

With it, the structure is the routing: work reaches the seat responsible for it, goals cascade from the company mission down to each role, agents act in your tools under their own accounts, spend stops at a ceiling instead of at your invoice, and every configuration change is a revision you can diff and revert.

## Documentation

### Getting started

Bring the infrastructure up, describe a company, watch its first turn.

- [Installation](https://docs.crewlet.ai/getting-started/installation): Prerequisites and the local Pulsar + PostgreSQL stack
- [Quickstart](https://docs.crewlet.ai/getting-started/quickstart): A four-agent company and its first turn
- [Choosing your stack](https://docs.crewlet.ai/getting-started/choosing-your-stack): Every external dependency, and what you set up yourself
- [Authoring with an AI assistant](https://docs.crewlet.ai/getting-started/ai-authoring): Let an assistant interview you and write the config
- [Configuration reference](https://docs.crewlet.ai/getting-started/configuration): Every field of the company YAML

### Core concepts

How the engine works, one subsystem per page.

- [Overview](https://docs.crewlet.ai/concepts/overview): Design principles and the high-level architecture
- [Organization model](https://docs.crewlet.ai/concepts/organization-model): Units, teams, roles, seats, handles
- [Humans in the org chart](https://docs.crewlet.ai/concepts/humans-in-the-org): Human seats, contact identities, escalation
- [Agent runtime](https://docs.crewlet.ai/concepts/agent-runtime): Lifecycle, states, execution model
- [Turn engine](https://docs.crewlet.ai/concepts/turn-engine): The plan / execute / review loop and its models
- [Code sandbox](https://docs.crewlet.ai/concepts/code-sandbox): run_sandbox, E2B, Claude Code and OpenCode runners
- [Knowledge system](https://docs.crewlet.ai/concepts/knowledge-system): Query-time knowledge search and the agent diary
- [Agent learning](https://docs.crewlet.ai/concepts/agent-learning): Reflection, skill induction, episodic memory
- [Tool skills](https://docs.crewlet.ai/concepts/tool-skills): Prompt fragments that teach agents to use a tool
- [Tool capabilities](https://docs.crewlet.ai/concepts/tool-capabilities): Why no tool name is hardcoded in the engine
- [Event system](https://docs.crewlet.ai/concepts/event-system): Topics, routing, inbox batching, tracing
- [Task engine](https://docs.crewlet.ai/concepts/task-engine): ExecutionTracker and the external tracker
- [Scheduling](https://docs.crewlet.ai/concepts/scheduling): Cron-style recurring work on a seat or a unit
- [One-on-ones](https://docs.crewlet.ai/concepts/one-on-ones): Manager and report coaching over the scheduler
- [Decision framework](https://docs.crewlet.ai/concepts/decision-framework): The DACI model for multi-agent decisions
- [Configuration](https://docs.crewlet.ai/concepts/configuration): Two-tier config, revisions, live propagation
- [Secret store](https://docs.crewlet.ai/concepts/secret-store): Encrypted values consulted ahead of the environment

### Integrations

Connecting the surfaces your agents actually work on.

- [Slack](https://docs.crewlet.ai/integrations/slack): One app per agent, thread routing, provisioning
- [Plane](https://docs.crewlet.ai/integrations/plane): Tracker and knowledge base in one product
- [Jira](https://docs.crewlet.ai/integrations/jira): Webhooks, MCP tools, per-team projects
- [Confluence](https://docs.crewlet.ai/integrations/confluence): CQL knowledge search and page writes
- [GitLab](https://docs.crewlet.ai/integrations/gitlab): Per-agent service accounts and provisioning
- [GitHub](https://docs.crewlet.ai/integrations/github): Per-role remote MCP tools for read and review
- [Custom transports](https://docs.crewlet.ai/integrations/custom-transports): Build your own notification transport

### Guides

Task-shaped walkthroughs for the things you do more than once.

- [Tools & MCP](https://docs.crewlet.ai/guides/tools-and-mcp): Built-in tools, MCP servers, the tool registry
- [Extensions](https://docs.crewlet.ai/guides/extensions): Lifecycle hooks and writing an extension
- [Deployment](https://docs.crewlet.ai/guides/deployment): Docker, Pulsar sizing, TimescaleDB, tracing
- [Configure via API](https://docs.crewlet.ai/guides/configure-via-api): Bootstrapping a company through /config/*

### Reference

The pages you consult rather than read.

- [CLI](https://docs.crewlet.ai/reference/cli): Every command and flag
- [API endpoints](https://docs.crewlet.ai/reference/api-endpoints): REST routes and schemas
- [Environment variables](https://docs.crewlet.ai/reference/environment-variables): Every configuration variable
- [Dashboard design system](https://docs.crewlet.ai/reference/dashboard-design): Tokens, panels, and the rules a change keeps
- [Design decisions](https://docs.crewlet.ai/reference/design-decisions): Why the architecture is shaped this way

## Source Code

The full source is on GitHub, MIT licensed. Read the implementation, file an issue, or open a pull request:

https://github.com/crewlet/crewlet

## Links

- Website: https://crewlet.com
- Documentation: https://docs.crewlet.ai
- GitHub: https://github.com/crewlet/crewlet