Set up with your AI assistant

This page is a runbook written for an AI assistant: Claude Code, Codex, Cursor, or any assistant that can read a web page and, ideally, work in a local copy of your repository. It takes the assistant through setting Coroid up for one or more repositories. It stops for you at every step only a person can do: signing in, granting access, entering a secret, or approving a change.

Hand it to your assistant#

Open your assistant in the repository you want Coroid to work on, and give it this prompt:

Set up Coroid for this repository. Follow the runbook at
https://coroid.ai/docs/export/en-US/getting-started/assistant-setup.md
step by step. Ask me before you change anything, and never ask me to paste a
password or token into this chat.

For several repositories, open the assistant in a directory that contains them all, and name them in the prompt. The assistant does the inspection and the checking, and tells you exactly what to do at each step that needs you.

Ground rules for the assistant#

You are setting up Coroid, a hosted AI software factory that turns a description of work into a tested, reviewed pull request in the user's repository. Follow these rules throughout:

1. The user acts; you prepare. You cannot sign up, sign in, accept terms, install apps or grant access for the user. Say exactly what to do and where, then wait until the user confirms it is done.
2. Keep secrets out of the conversation. Never ask for a password, personal access token, provider key or MCP token. The user types secrets into the Coroid portal or their own shell. If one is pasted into the chat anyway, tell the user to revoke it and create a new one.
3. Ask before every change: commits, branches and pull requests in the user's repository, Coroid projects, and invitations.
4. Check each step before the next. If a check fails, use the notes in that step, and continue only when it passes or the user decides to skip it.
5. Follow the product, not your assumptions. If the portal shows something this runbook does not describe, tell the user what you see and follow the portal. Do not invent settings.
6. Keep a setup record of each step and its outcome, for the end.

Each step links the pages with the detail. https://coroid.ai/llms.txt indexes the whole documentation.

Step 1: Agree the plan#

Ask the user these questions together, not one at a time:

Then repeat the plan back: the steps below, which need the user, and the repositories in scope.

See Plans and pricing, Limits and quotas and Synced or local only.

Step 2: Check each repository builds and tests from a clean clone#

This is the most useful work you can do. Every Coroid task runs in a clean, disposable Linux workspace: a fresh clone, nothing cached, nothing installed beyond the image's toolchain. An agent that cannot build and test the project cannot verify its own work, and its tasks fail in verification for reasons unrelated to the change.

If you can work in the repository locally, do this for each one:

1. Identify the languages, the package manager, and whether it is a monorepo.
2. Find the install, build and test commands in the README, the CI configuration and the manifests.
3. Ask before you run anything. Then clone the repository into an empty temporary directory and run install, build and test there with nothing else set up. The user's working copy has caches and .env files that hide problems.
4. Note everything the run needed that a fresh clone does not have:
   • services the tests expect, such as a database, a cache or a queue
   • steps before the tests, such as code generation, migrations or fixtures
   • environment variables or an .env file that is not committed
   • private package registries
   • a runtime that is not in the agent environment

Never run commands that deploy, publish, or touch shared environments. If the suite is slow or calls paid services, ask the user first.

Report a short readiness check per repository: the commands, how long the suite took, what passed, and each gap with a proposed fix.

A missing runtime is not a blocker either: a container that encodes the toolchain solves it. If you cannot reach the repository locally, gather what you can from the user, and record that the clean-clone check did not happen.

See Build and test configuration and Language support and the agent environment.

Step 3: Write the instructions Coroid's agents read#

Before every task, Coroid's agents read the memory files in the repository: AGENTS.md, CLAUDE.md or GEMINI.md at the root, and .cursor/rules. The commands you verified in Step 2 belong there.

Propose an AGENTS.md, or an addition to the existing one, that states:

• the install, build and test commands, verified from a clean clone, and the directory to run them in
• the steps and services the tests need
• how to run the narrowest useful set of tests, such as one package or one file
• conventions and boundaries the code does not show: frozen modules, areas not to touch, dependencies not to add

Leave out what the code already shows, and keep the file short. If CLAUDE.md or .cursor/rules holds the same instructions, keep them once in AGENTS.md and import it from the other file with an @AGENTS.md line.

Show the user the diff. With their approval, commit it on a new branch and open a pull request, or leave it for them to commit. It must reach the base branch before the first task, because each task reads the memory files from its own checkout of that branch. Handle the fixes from Step 2 the user accepted the same way.

See Project context settings and Project context.

Step 4: Account and organisation (the user)#

Skip this step if the user already belongs to a Coroid organisation as an Owner or Admin.

Ask the user to:

1. sign up at https://client.coroid.ai/auth/signup with their work email, and verify the address
2. accept the terms of service
3. create the organisation

Check: the user can open https://client.coroid.ai/projects. The person who completes this setup needs the Owner or Admin role, because only those roles can connect source control and add provider keys.

See Create your account and organisation.

Step 5: Connect source control (the user)#

Go through the access requirements with the user before they start. An install that stops halfway for someone else's approval is the usual reason this step takes a day instead of a minute.

GitHub#

The user opens Settings → Connections → Source control (https://client.coroid.ai/settings/connections/source-control).

GitHub App: on GitHub's install screen, the user chooses Only select repositories and picks the ones agreed in Step 1. The App keeps working when the person who installed it leaves, receives webhook events, and is what lets Coroid publish its checks on pull requests. A token cannot publish GitHub checks.

Personal access token: the user creates it on GitHub with an expiry, and pastes it into the Coroid portal. Prefer a fine-grained token limited to the agreed repositories. Pull requests are attributed to the token's owner, and the connection breaks if that person loses access.

GitLab#

GitLab is in private preview and only appears on accounts where it is enabled. It connects with a personal access token with the api scope. If GitLab does not appear under Source control, tell the user to contact Coroid, and do not plan around it.

Branch protection#

Coroid opens ordinary pull requests, so branch protection, required checks and review rules still apply. Recommend keeping protection on. If the rules require signed commits or a status check Coroid cannot produce, its pull requests will open and stay unmergeable. Tell the user, and do not change their rules.

Check: the provider shows as connected under Source control. The real proof comes in Step 6, when the repositories appear in the project list.

See Connect your code, GitHub, GitLab and Repository and branch settings.

Step 6: Create the projects (the user)#

Create one project per repository, never two for one repository. The user opens Projects → New (https://client.coroid.ai/projects/new) and, for each repository:

1. picks it from the connected provider, or uses Connect with URL for a public repository
2. chooses the Repository mode: Synced, where Coroid pushes branches and opens pull requests, or Local only, where Coroid never writes to the repository until someone chooses Start syncing
3. checks the default branch
4. creates the project

If the team merges into something other than the default branch, such as develop, set the base branch in the project's repository settings. A wrong base branch sends pull requests to a branch nobody reviews.

If a repository is missing from the list, the cause is almost always one of:

• the GitHub App was not granted that repository
• the token's scope is too narrow to list it
• the repository belongs to a different organisation than the one connected

See Create your first project and Repository and branch settings.

Step 7: Check what Coroid found#

Ask the user to open each project's overview and read out the Repository details and anything listed under Finish setup:

• Status and Branch: the repository is cloned, on the base branch you agreed. If the overview says the repository hasn't been cloned yet, the user chooses Clone repository.
• Stack: the languages, framework, package manager and test tools Coroid detected. Compare them with your readiness check. If the stack is empty or wrong after the first sync, the user can scan it again from there.
• Finish setup: items such as "Dependencies didn't install cleanly" point at the same gaps as Step 2. Work through them with the user.

Then the user opens the project's Settings → Knowledge → Context. The memory file from Step 3 must be listed under Repository sources and be enabled. If it shows Create instead, the file has not reached the connected branch yet.

See Project context settings and Build and test configuration.

Step 8: Organisation settings (optional)#

Ask whether the user wants any of these now. All have workable defaults:

• Members, under Settings → Members: the people who will review pull requests, as Owner, Admin, Member or Reviewer. Recommend Admin only for people who should change policies and provider keys. Needs Professional.
• Provider keys, under Settings → Provider keys: only to use the organisation's own model provider accounts. The user enters the key in the portal. Recommend a restricted key with a spend limit at the provider.
• Settings from another organisation: export a settings bundle there and import it under Settings → Data → Export settings. Secrets travel as placeholders, so every needsRebind item in the preview needs attention.

See Create your account and organisation, Provider keys and Export and import settings.

Step 9: Connect yourself to Coroid (optional)#

If your client supports remote MCP servers, you can reach Coroid through its MCP server at https://api.coroid.ai/mcp. Setup does not depend on it, but it lets you check the projects yourself and help the user run work later.

1. The user opens Settings → Automation → Coroid MCP server (https://client.coroid.ai/settings/automation/coroid-mcp). If it is not available to their organisation, skip this step.
2. Client setup shows the commands per client. With OAuth, the user approves your access in their browser. With a personal access token, the user creates it under Access tokens and stores it in an environment variable in their own shell. You never need to see the value.
3. Recommend the least access that works: mcp.read to check the setup, plus mcp.work.write only if you are to create tasks. Limit the token to these projects, give it an expiry, and set Automation policies before any client runs unattended.

Check: call list_projects, then get_project for each project from Step 6, and confirm the repository and branch.

Use only api.coroid.ai for MCP. The client portal hostname does not serve it.

See Coroid as an MCP server.

Step 10: Draft a first task#

Finish by drafting a small first task with the user in one of the new projects. A good first task is real, small, close to existing tests, and has a clear finish line. Avoid authentication, payments, data migrations, open-ended clean-ups, and anything that needs a design decision nobody has made yet.

Describe the outcome, not the implementation: what should be true when the work is done, which files matter, and what not to touch. The user submits it from New Work (https://client.coroid.ai/work/new), reads the specification, and approves the plan. Running work uses agent hours, and the Free plan includes 2 per UTC day, so let the user decide when it runs.

See Run your first task and Specifications.

Step 11: Hand over#

Give the user the setup record:

• each repository, its project, repository mode and base branch
• how source control is connected, and who owns the connection: the App's installer, or the token's owner and its expiry date
• per repository, the gaps fixed, the ones pending (such as an open pull request with AGENTS.md), and the ones the user chose to leave
• the optional settings done and skipped, and the drafted first task

Then point the user to Review and merge the result for what arrives with the first pull request.

Next#

Create your account and organisation — the same setup, done by hand.