Key Concepts

Rensei is a platform for running fleets of AI agents across the software development lifecycle. Before diving into the product, a shared vocabulary helps - the same terms appear across the CLI, dashboard, and API.

The mental model in one sentence

Rensei orchestrates agent sessions against your codebases, driven by events from your issue tracker, governed by workflows, and made progressively smarter by a memory layer that compounds across sessions.

Core concepts

Organization

An org is the top-level billing and policy boundary. It contains members, API keys, integrations, and one or more projects.

Every workflow, agent card, and model profile is owned by an org (or one of its projects). Org admins configure the org's default model profile, capacity pools, and Cedar security policies.

Project

A project is a permission boundary that scopes agent work to a specific set of repositories and issue trackers.

Org
└── Projects
    ├── Repos         (GitHub / GitLab repositories)
    ├── Trackers      (Linear / Jira workspaces)
    ├── Members       (owner / admin / member / viewer)
    ├── Environments  (default, staging, production)
    └── Workflows     (installed and subscribed)

Every workflow lives in exactly one project. A workflow defined at the org level does not exist - if you want the same workflow to run in two projects, you install it twice (once per project). This is intentional: it makes permissions, resource bindings, and audit trails unambiguous.

Resources like project.repo and project.tracker are resolved per environment, so a single workflow definition can point at your staging Linear team in the staging environment and your production team in production. See Workflow environments below for how environments work in practice.

Workflow

A workflow is a directed graph of typed nodes stored as a YAML definition (apiVersion: workflow/v1). It describes the logic that runs when a trigger fires - which agents to invoke, what conditions branch the flow, what gates require approval, and how sub-workflows compose.

The six node categories:

All behavior in Rensei is expressed as visible, editable nodes. There are no hidden platform-side auto-generated steps - what you see on the canvas is exactly what runs. This principle is called the locus of workflow definition: if a behavior is not a node on the canvas, it does not exist.

The grammar (apiVersion, node type taxonomy, expression syntax) is OSS-canonical and documented at donmai.dev/docs/workflow-engine.

Workflow environments

A workflow environment is a named resource binding - a mapping from logical resource references (like project.repo or project.tracker) to concrete values (a specific GitHub repo URL or Linear team ID).

Every project has at least a default environment (auto-created). You can add environments for staging and production:

default environment
  project.repo   → github.com/acme/api   (main branch)
  project.tracker → Linear team "Eng - Prod"

staging environment
  project.repo   → github.com/acme/api   (develop branch)
  project.tracker → Linear team "Eng - Staging"

When a workflow references { "$ref": "project.repo" }, the orchestrator resolves it against the active environment. The same workflow definition runs in both environments without any modification - you just change which environment it is deployed to.

This matters for the quickstart: the default environment is pre-configured when you connect a repo and tracker, so you do not need to think about environments at first.

Agent

An agent is the unit of AI capability - a model, a set of tools, a system prompt, and a runtime requirement bundled into a first-class descriptor called an AgentCard.

An AgentCard specifies:

• Which model profile to use (can be inherited from the project or org)
• Which work type the agent performs (research, development, qa, coordination, acceptance)
• Which tools and plugins the agent loads
• Its runtime environment requirements (local daemon, cloud sandbox, or any)

When a workflow node invokes an agent (agent.invoke or agent.dispatch), the orchestrator resolves the AgentCard, selects a compute pool, and dispatches a session.

Rensei ships a catalog of built-in system agents (the SDLC phases, PM agents, code-intelligence agents). You can fork, extend, or author your own. See agent cards overview.

Session

A session is one execution of an agent - from dispatch to completion. It is the atomic unit of work tracked in Rensei.

Every session has:

• A structured activity stream (thoughts, tool calls, responses, errors)
• A Linear AgentSession thread (if the triggering integration is Linear)
• A session inspector for deep debugging (logs, context, tool calls, cost, memory)
• A persistent derived context - observations extracted at session end that feed future sessions

Sessions are scoped to a project and immutable after completion. The activity stream is append-only and cryptographically anchored.

The layered execution model

Rensei is built on the open-source donmai runtime. The execution architecture has six layers, from lowest to highest. (The rensei.ai home page traces the same architecture as a five-stage request path, Compose to Verify; those five stages run on these six layers. See How Rensei Works for how the two views line up.)

┌─────────────────────────────────────────┐
│  6. Policy, Security, Observability     │  ← Cedar policies, audit chain, cost tracking
├─────────────────────────────────────────┤
│  5. Intelligence Services               │  ← Memory, code intelligence, arch intelligence
├─────────────────────────────────────────┤
│  4. Composition                         │  ← Workflow engine, orchestrator, governor
├─────────────────────────────────────────┤
│  3. Execution                           │  ← Sandbox providers, local daemon, cloud
├─────────────────────────────────────────┤
│  2. Integrations                        │  ← Linear, GitHub, Vercel, Jira, Slack, ...
├─────────────────────────────────────────┤
│  1. Provider contracts                  │  ← OSS interfaces: sandbox, workarea, VCS, ...
└─────────────────────────────────────────┘

Layers 1-3 are OSS-canonical and shared with the donmai runtime. Layers 4-6 are the Rensei platform. The division is deliberate: the donmai runtime works standalone (no Rensei account required), and the platform extends it without coupling to it.

For the full boundary contract and OSS internals, see donmai.dev/docs/layered-execution-model and How Rensei Works.

Memory and the Day-1/Day-40 quality commitment

Every session produces observations - structured facts about the codebase, decisions made, patterns noticed. These are stored in the project's memory store (pgvector + Postgres, scoped per project and Cedar-gated).

At the start of each new session, relevant observations are injected into the agent's context. This means:

• Session 1: the agent reads the codebase cold.
• Session 10: the agent knows which files are fragile, which naming conventions to follow, and which reviewer prefers clean diffs.
• Session 40: the agent makes fewer errors, takes fewer turns, and requires less human correction.

Quality compounds rather than decays. The memory layer is provider-orthogonal - observations benefit agents regardless of which model or sandbox they run on.

Capacity pools and sandbox providers

A capacity pool is a named group of compute that agents can run on. Rensei ships with built-in pools:

When a workflow dispatches an agent, the orchestrator resolves the best pool based on: the agent's runtime requirements, the project's pool preference, and current pool capacity. Local daemon workers are tried first by default.

Model profiles

A model profile is a named configuration of provider + model + auth mode + cost controls. Profiles are first-class objects with a scope cascade:

workflow-node override
  └── project assignment
        └── org assignment
              └── system default

Updating a profile cascades to every workflow that references it on the next run - you never need to republish workflows to change which model runs.

Work-type routing lets you assign different profiles to different agent roles:

workTypeProfiles:
  research: claude-haiku-byok
  development: claude-sonnet-byok
  coordination: claude-opus-byok
  qa: claude-haiku-byok

Set this once at the org level; all SDLC workflows pick it up automatically.

Glossary

Next steps

• How Rensei Works - the layered execution model in depth
• Quickstart - first agent running in under 10 minutes
• Default SDLC template - the built-in five-phase workflow
• Agent cards - authoring and extending agents
• Model profiles and routing - scope cascade and work-type routing