Projects & repositories

What a project holds, how a repository binds to one, and where settings live.

A project is the workspace for one codebase. It holds that codebase's tasks, runs, workflows, personas, statuses, priorities, labels, wiki, and settings. An organization can have as many projects as it likes, and 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 is filled in from the checkout's git origin as a suggestion you can edit.

Connecting writes peractorrc.json at the root of your repository — the only file Peractor ever keeps there:

{ "project": "3f9a…" }

That is the whole binding. The id tells every Peractor app which project this checkout belongs to. An optional host field points the repository at a self-hosted server instead of Peractor Cloud.

Rebinding to another project takes effect straight away; changing the host reloads the editor. You can also create projects from the dashboard, the Mac app, or a phone — a repository is not a prerequisite.

One project, one repository

A run works against its project's repository and nothing else. There are no per-task repository overrides to audit.

A project with no repository at all is valid: 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 server can also point a project at a folder on its own disk.

Where settings live

Everything except peractorrc.json is stored on the server and edited in the apps. Nothing to commit, nothing to drift.

Trackers follow the same split: the authorization belongs to the organization, but what each project follows — and the tasks that result — belongs to that project alone. See Connect trackers.

Shared libraries work by picking, never overriding. An admin registers a workflow, persona, or skill or MCP server once for the organization; each project ticks the ones it wants under Settings → Shared library. A project that needs a shared workflow to be different duplicates it. Whole sets of workflows and personas can also be installed from the marketplace.

Standing instructions

Under Settings → General → System prompt, give the project the house rules you would otherwise repeat in every task:

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

This is the second of four layers, outermost first:

1. Your organization's agent instructions (Settings → Organization). Always on, and additive — a project can add to them but cannot switch them off.
2. This project's system prompt.
3. The workflow's base prompt.
4. The step's persona.

A workflow that sets its own systemPrompt replaces the project's for its own runs. Every run's transcript shows all four layers separately, so you can always see what an agent was actually told.

Key, tasks, and wiki

Three project settings are worth knowing about on day one:

• Key — two to five letters, unique in your organization, used to name tasks (WEB-14) and their branches. Seeded from the project name and editable; changing it renames every task's key at once.
• Tasks — on by default. Turning it off stops new tasks being written here; tasks synced from a tracker still appear, so the board never disappears.
• Wiki — off by default. Turning it on names the folders in your repository that hold pages. See The project wiki.

Housekeeping

The Project block in Settings → General edits the name, key, 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.