Your First Project · RoboCo Docs

A project is a git repository RoboCo is allowed to work on, plus the configuration that tells the company how to build and check it. Until you register one, the agents have nowhere to put their work. You register projects in the panel under Projects → New.

What a project needs

Field	What it is
Name	Human-readable label for the repo.
Slug	URL-safe short name. It becomes the top of the workspace path (`{slug}/{team}/{agent}/`) and shows up in branch names.
Git URL	The clone URL. HTTPS is the common case and requires a token (below).
GitHub token (PAT)	A Personal Access Token, stored encrypted. Required for private or HTTPS repos — see The GitHub token.
Assigned cell	Which delivery cell owns this repo: Backend, Frontend, or UX/UI.
Default branch	The branch PRs ultimately target. Read the default-branch gotcha before you save.
Gate commands (optional)	Per-project test / lint / format / typecheck / build commands, and a fast pre-submit `quality_command`. See Gate commands.

The GitHub token

Agents clone your repository and open pull requests on it, so they need a GitHub Personal Access Token with permission to do that.

Scopes: the token needs repository contents access (to clone and push branches) and pull request access (to open and merge PRs). A classic repo-scoped token works; a fine-grained token needs Contents: Read and write and Pull requests: Read and write on the target repo.
It's encrypted and write-only. The token is encrypted at rest the moment you save it (with your ROBOCO_ENCRYPTION_KEY) and the API never returns it — the panel only shows whether a token is set, not its value.
Rotating or clearing it: in Edit Project, entering a new token replaces it, an empty field clears it, and leaving it untouched keeps the current one.

HTTPS without a token fails

If you give an HTTPS Git URL and no token, the clone fails — agents can't reach the repo. Set the token when you create the project.

The encryption key is load-bearing

Every stored project token is encrypted with ROBOCO_ENCRYPTION_KEY. If you ever change that key, all stored tokens become undecryptable and you'll have to re-enter every one. Pick it once at install and keep it backed up.

The default-branch gotcha

The Create Project dialog defaults the branch to main, but several places in the backend assume master. Set this field explicitly to match your repository's real default branch (main or master) rather than trusting the pre-filled value. Getting it wrong is the most common first-run snag — branches get cut from, and PRs target, the wrong base.

Gate commands

A developer agent runs a quality gate against its own work before it submits for QA. By default that's a sensible lint + typecheck pair, but you'll get far better results by pointing RoboCo at your repository's real checks:

quality_command — the fast pre-submit gate, run at the moment an agent says it's done (for example make gate). If you set this, it replaces the default lint/typecheck pair. Keep it fast; it runs on every submission.
test_command, lint_command, format_command, typecheck_command, build_command — the individual commands for the cell's QA and CI steps.

Setting these so they mirror what you would run locally is the single biggest lever on output quality: the company gates itself exactly the way you would.

Sandboxing agents away from a repo

If you want to make sure agents can never point a project at a particular repository — RoboCo's own source, say, during a test run — set ROBOCO_PROTECTED_GIT_URLS to a comma-separated list of URL substrings. Creating or updating a project whose Git URL matches one is rejected.

What happens under the hood

You don't have to manage any of this, but it's worth knowing what registering a project sets in motion:

The first time an agent is assigned work on the project, RoboCo clones the repo into that agent's own workspace under ROBOCO_WORKSPACES_ROOT (default /data/workspaces). Every agent gets its own clone, so they work in parallel without stepping on each other. That directory is the disk to provision and back up.
Right after cloning, RoboCo scrubs the token out of the clone's git config and verifies no token byte survived anywhere under .git/ — destroying the workspace if one did. Your PAT never lives inside an agent container.