Getting started

From a new account to your first reviewed run, in six steps.

Peractor runs AI coding agents through a pipeline you define. The work happens in phases, you review between them, and you can watch every step as it happens — from a browser, the desktop app, your Mac, or your phone.

This guide gets you from nothing to a finished, reviewed piece of work. It takes about ten minutes, and most of the steps have a working default you can skip.

In Runs, use Started by to see one member's runs. Choices come from the people recorded on the current list, including former members. Choose Started by anyone or clear the filter to show everyone.

1. Create an account and an organization

Then create an organization, or join one with an invite link. The organization is the shared space your team works in — it owns your projects, tasks, runs, connected services, and billing. You can belong to as many as you like. See Organizations & members.

Every step below works the same in a browser, the desktop app, the Mac app, or on your phone. See Peractor on your devices; the download page tracks where every app stands.

2. Let runs push to your repository

Runs work on real git branches, so Peractor needs permission to push. Open Settings → Git access and pick one:

The Peractor GitHub App — recommended for GitHub. Each run gets a short-lived token scoped to exactly its own repository, and the app opens and merges the pull requests.
A token or SSH key — works with GitLab, Bitbucket, and any self-hosted remote.

Details in Git & credentials.

3. Create a project for your repository

A project is the workspace for one codebase. Create one and give it your repository's address — or leave the repository empty and Peractor keeps the project's files for you. Everything about a project lives on the server and is edited in the app.

4. Take the setup wizard, or skip it

The wizard walks seven optional steps: the agent to use, the kind of work you do, git access, instructions, workflows, issue trackers, and notifications. Nothing is saved until you press Complete setup, so you can back out at any point.

Every step has a sensible default. Skip all of them and you still have a working spec → coding → merge pipeline.

If you would rather describe what you want in your own words, the assistant can set the same things up from a conversation.

5. Start a run

Write a task, or sync one in from your tracker. Pick a workflow and press Run.

The live session opens. You see what the agent is thinking, every file it changes as a diff, every command it runs, and the cost ticking up per phase. When a phase finishes, the run stops and waits for you.

6. Review, then advance

At the stopping point — we call it a gate — you have two buttons:

Approve moves the run on to the next phase.
Request changes sends it back with your note. The agent reworks the same branch and comes back to you.

Review from a browser, the desktop app, the Mac app, or your phone — whichever is nearest. That loop is the whole product: watch, decide, advance.

Where to go next: Core concepts · Workflows · Gates & reviews