Getting started
From zero to your first gated run: create an org, connect your editor, and watch an agent work.
Peractor runs AI coding agents through a workflow you define — phase by phase, with a human gate between them — and lets you watch every step live. This guide takes you from a fresh account to your first reviewed run.
1. Create your account and organization
Sign up with email, GitHub, Google, or Linear — that creates your personal account. Next, onboarding asks you to create your first organization or join one with an invite link. Runs, tasks, connectors, and teammates all live inside the organization; invite your team from Members whenever you're ready — see Organizations & members.
2. Install the editor extension
The editor is Peractor's deep work surface. Install the Peractor extension in VS Code (or any of its forks) and click Sign in in the Peractor sidebar — it opens this site in your browser and hands the session back to the editor. You never type credentials into the editor.
During the private beta the extension isn't on the public marketplaces yet — request access and we'll get you set up. The download page tracks where every app stands.
3. Give runs push access
Runs work on real branches, so Peractor needs permission to push. In Settings → Git access, either install the Peractor GitHub App (recommended — every run gets a short-lived token scoped to exactly its repository, and the App opens and merges the PRs) or connect a token or SSH key, which covers GitLab, Bitbucket, and self-hosted remotes. Details in Git & credentials.
4. Connect the repo to a project
Each repository binds to a project — the
workspace that scopes its runs, tasks, and configuration. In the editor,
Connect this repo to a project creates one and writes its id to
peractorrc.json at the repo root — the only file Peractor keeps
in your repo. Everything else lives on the host and is edited in the
app.
5. Take the setup wizard (or skip it)
The extension's setup wizard walks seven optional steps — Agent, Focus, Git access, Personas, Workflows, Trackers, Notifications — staging everything and applying it in one shot at Complete setup. Every step has a working default: skip it all and you still have a spec → code → merge workflow ready to run.
6. Start a run
Create a task (or import one from your tracker), pick a workflow, hit Run. The live session opens: the agent's reasoning, every file edit as a diff, every command, the cost ticking per step. When the phase finishes, the run parks at a gate and waits for you.
7. Review at the gate
Approve advances the run to the next phase. Request changes sends it back with your note — the agent reworks the same branch and returns. Review from the editor, this dashboard, or your phone. That loop — watch, gate, advance — is the whole product.
Go deeper: Core concepts · Workflows · Gates & reviews