Projects & repositories

The workspace tier: binding a repo, where configuration lives, and the project system prompt.

A project is the workspace inside your organization that scopes everything about one codebase: its tasks, runs, workflows, statuses, personas, priorities, and settings. Organizations hold many projects; every run belongs to exactly one.

Connect a repository

In the editor, Connect this repo to a project picks an existing project or creates one — the repository field pre-fills from the checkout's git origin as a visible, editable suggestion. Connecting writes peractorrc.json at the repo root, the only file Peractor ever keeps in a repository:

{ "project": "3f9a…" }

That's the whole binding: the id tells every Peractor surface which project this checkout belongs to. An optional host field points the repo at a self-hosted control plane instead of Peractor Cloud. Rebinding to another project applies live; changing the host reloads the editor. Projects can also be created from the dashboard or the phone's setup wizard — a repo isn't a prerequisite.

One project, one repo

A run works against its project's repository and nothing else — there are no per-task repo overrides to audit. A project with no repository is valid too: runs start in an empty workspace, which is exactly what greenfield scaffolding wants. (On Peractor Cloud the repository must be a git remote; a self-hosted control plane may also bind a local filesystem path.)

Where configuration lives

Everything except peractorrc.json is stored on the host and edited through the apps — nothing to commit, nothing to drift:

Trackers follow the same split: the OAuth connection is organization-level, but what each project imports — and the tasks that result — belong to that project alone. See Connect trackers.

The project system prompt

In Settings → General → System prompt, give the project standing instructions every run starts with — the house rules you'd otherwise repeat in each task:

Follow the repository's existing conventions. Keep changes small
and focused. Always add or update tests for the code you touch.

It layers under everything else: project system prompt → the workflow's basePrompt → the step's persona. A workflow that sets its own systemPrompt replaces the project one for its runs.

Renaming and housekeeping

The Project block in Settings → General edits the name and repository (admins only). A fresh project needs none of this to be useful: the built-in default workflow and priority scale apply until you define your own.