Get started with Capybari

Capybari runs an engineering organisation on your repositories and ships the result to your servers. This page takes you from an empty account to one request that has been planned, built, reviewed, deployed and reported on.

Work through it in order. Allow about thirty minutes, most of which you spend watching.

Before you start

Have these ready:

• A git repository Capybari can clone, plus an access token if it is private.
• A server you can reach over SSH, if you want to deploy. Skip it for now if you do not — planning, building and review all work without one.
• A terminal, for two copy-and-paste steps.

Create your account

1. Register at capybari.com/signup with your work email address.
2. Confirm the address from the message we send you.
3. New accounts are reviewed before the first sign-in. You get an email when yours is ready.
4. Sign in and choose New project. Give it a name — the name becomes the project slug used for its checkout paths, so keep it short.

A project is the unit that owns everything else: its repositories, its team, its deployment targets, its board and its autonomy level. Most teams run one project per product, and agencies run one per client.

Connect a git repository

Open Project settings → Repositories and choose Add repository.

Capybari clones the repository when you save. If the clone fails you get the git error back word for word, which is usually enough to tell a wrong URL from a wrong token. The first repository you add becomes the project's primary repository: the Project Manager plans in it, and tasks default to it.

You can add more repositories at any time. Tasks are assigned to one repository each, so a task in web never touches the worktree of a task in api.

Add a deployment target

A deployment target is a server you own, described precisely enough that an agent can ship to it and put it back the way it was. Open Project settings → Deployment targets → Add target.

Choose a target type first:

• SSH host — Capybari merges, connects over SSH and runs your commands. Use this one for a real deploy.
• Merge and push only — Capybari merges the approved branches and pushes. Your own pipeline takes it from there.
• Download only — Capybari produces a build artefact you download by hand.

For an SSH target, fill in the host, port, username and these four fields.

Deploy path. The directory the deploy runs in. Capybari runs your deploy command as cd '/srv/orderly/app' && your-command, so write the command as though you are already standing in that directory.

Deploy command. One shell command, or several joined together. It must be safe to run twice.

git pull --ff-only origin main && \
  docker compose build --pull web && \
  docker compose up -d --remove-orphans && \
  docker compose exec -T web ./manage.py migrate --noinput

Health check. Either an HTTP check or a command check.

• HTTP — give a URL. Any status from 200 to 399 passes. Anything else fails, and the status code and the first part of the body are recorded on the run.
• Command — give a shell command. Exit code 0 passes.

Rollback command. This is the field that lets you sleep. Capybari records the commit that was live the last time a health check passed, and substitutes it into {sha} when a rollback is needed.

git reset --hard {sha} && docker compose up -d --remove-orphans

Add the deploy key to your server

Capybari generates an ed25519 keypair when you save the target and keeps the private half encrypted. You are never asked to hand over a private key. Copy the public key it shows you onto the server, as the user you gave in Username:

# On your server, as the deploy user
mkdir -p ~/.ssh && chmod 700 ~/.ssh
echo 'ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIBq7T2m0nJ4pW8Xh1sD9vK3rY6fL0cN5uE2aZ8gQwR4t capybari-deploy-production' >> ~/.ssh/authorized_keys
chmod 600 ~/.ssh/authorized_keys

Now press Test connection. The test opens an SSH session and checks that the deploy path exists and is writable. Until it passes, the target cannot be deployed to at all — a target you have not proved you can reach is not a target.

Assemble your team

Open Project settings → Team and add the specialists this project needs. Fourteen roles are available:

Start with five: Project Manager, Full Stack Developer, Code Reviewer, Security Engineer and DevOps Engineer. That team can plan, build, review and ship. Add the rest as the work demands them.

Two things to know about a partial team:

• Work planned for a role you have not added is reassigned to the closest capable member, and the substitution is recorded on the task. If nobody can cover it, the task falls back to the Project Manager. A task is never dropped for want of a specialist.
• Every role is governed by a Markdown contract you can read and edit. Open a role and tighten its rules if your codebase needs it.

Tick Requires review on any role you want a human gate behind. Work that depends on a task owned by that role stops until you approve it — at every autonomy level, with no exceptions.

Set autonomy to Manual

Open Project settings → Autonomy and choose Manual for your first request.

Autonomy governs how much of a healthy pipeline you approve by hand. It never changes what an agent is allowed to do, and it never suppresses a review gate or a genuine escalation.

File your first request

Choose something that has been on your list for a month and is small enough to read in one sitting. Press New request on the board.

• Title — one line, in your own words. "Card payments fail for European customers" is a fine request.
• Description — anything you know. Error messages, a customer's exact words, the file you suspect. It is all useful and none of it is required.
• Type — feature request, improvement, investigation, bug fix, deployment or other.
• Priority — urgent, high, medium or low. This orders the board.

Save it, then press Start planning.

Read the plan

The Project Manager reads your repositories and comes back with a plan. It has three parts:

1. A plan summary in plain English: what it intends to change and why.
2. A list of tasks, each with a task code, an owning role and a spec file.
3. A dependency graph — every task lists the tasks it waits for, so you can see what runs in parallel and what queues behind a decision.

Read the summary first. If it has misread you, press Re-plan and say what it got wrong; your feedback goes to the Project Manager and it plans again. You can do this as many times as you need. Nothing has run yet.

Approve the plan

When the plan is right, press Approve. You can untick individual tasks before you approve if you want a smaller first slice — unticked tasks are skipped, not deleted.

At Manual autonomy the tasks now sit ready. Dispatch them yourself.

Watch the run

Every task claims its own branch in its own git worktree, so parallel tasks cannot see each other's half-finished work and none of it touches your default branch.

Open a running task to watch it live. The stream shows the commands the agent runs and the output it gets back, as it happens. Three things can interrupt it, all of them on purpose:

• The agent asks you a question. When a specialist hits genuine ambiguity it stops and asks rather than guessing. Answer in the task and it continues.
• A review gate holds. A task owned by a role marked requires review waits for your approval before its dependents start.
• A design preview appears. Front-end tasks produce a shareable preview link so you can look at the change before it merges.

Review the report

Every task ends with a structured report, in the same shape every time:

• Summary — one or two sentences on what was done.
• Files Modified — each path, with what changed in it.
• Risks — what might bite, in the author's own judgement.
• Assumptions — what it decided for itself when you had not said.
• Recommendations — follow-up worth doing.
• Blockers — what stopped it, if anything did.

Read Risks and Assumptions first. They are where the disagreements live.

If the report is wrong, give the task feedback and send it back. If it is right, approve any tasks waiting on review, then press Merge and deploy and pick your target. Capybari merges the approved branches, records a merge summary, runs your deploy command, runs your health check, and — if the check fails — runs your rollback command against the last commit known to be healthy and opens an investigation.

You now know the whole loop. Everything after this is the same five moves at a larger size.

Where to go next

• Turn autonomy up one level when the plans stop surprising you. Most teams take about three weeks to reach Supervised.
• Add the roles you left out, starting with QA Engineer.
• Read the role contracts and tighten the ones that matter to your codebase.