Core concepts

The words Peractor is built from, and how they fit together.

Peractor uses about fifteen words. Learn them once and every screen, config file, and API response reads the same way.

How things nest

Account              you — one sign-in
  └─ Organization    your team: members, connected services, billing
      └─ Project     one codebase: its tasks, workflows, wiki, settings
          └─ Task    a piece of work
              └─ Run one execution of a workflow for that task
                  └─ Phase → Steps    what actually happens, in order

The vocabulary

Term	What it is
Account	You. One sign-in, any number of organizations.
Organization	Your team's shared space. Owns projects, members, connected services, and billing.
Project	The workspace for one codebase, bound to one repository. Holds its own tasks, workflows, personas, wiki, and settings.
Task	A piece of work, with a key like `WEB-14`. Typed by hand, synced from a tracker, or filed by an automation. Keeps its comments, history, and every run ever started on it.
Run	One execution of a workflow for one task. A task can have many, but only one at a time.
Workflow	The pipeline: phases, steps, and where a human reviews. Written as YAML, edited visually.
Phase	A stage of the pipeline — spec, coding, merge — with ordered steps and usually a gate at the end.
Step	One unit of work inside a phase. Nine types: `prompt`, `check`, `command`, `git`, `notify`, `publish`, `preview`, `loop`, and `workflows`.
Gate	The point where a run stops for a person: approve to advance, or request changes to send it back.
Live session	The real-time view of a run — its reasoning, diffs, commands, and cost — on every device.
Status	A stage a task can be in, and a column on the board. You define your own; tasks synced from a tracker keep that tracker's statuses.
Persona	A reusable identity for an agent: a name, a face, and a system prompt. Attached to a step.
Agent	The coding model doing the work — Claude Code, Codex, or one your organization registers itself.
Runner	Where a phase executes: Peractor's own isolated containers, or a machine you paired.
Connector	A service you link up: an issue tracker, a chat notifier, a git host.
Trigger	An event that starts a run when nobody is watching — a schedule, a repository event, or an incoming webhook.

Four things worth knowing early

The branch carries the state. Each run works on one git branch, and phases hand off through it. That is why a run survives a crash, a week-long wait, or a machine disappearing.
People hold the gates. Agents run isolated, with their own permission prompts switched off. The control point is the gate, where the whole phase is in front of you.
Configuration lives on the server, not in your repo. Workflows, statuses, personas, triggers — all edited in the app and shared by your team. Your repository carries one small file.
Your wiki is the exception, and on purpose. Wiki pages are markdown files in your repository, not rows in a database. See The project wiki.