Get started with CodeTroupe

1What you need

A Linux server with systemd, x86_64 or arm64, where you have root. It is tested on Ubuntu 24.04. It needs to reach your GitLab and Anthropic, and while installing or upgrading, codetroupe.com and downloads.codetroupe.com (or gitlab.com, which it falls back to), github.com (for Java), nodejs.org and the npm registry.
Your projects’ build tools, installed system-wide: a JDK and Maven for a Java project, Node for a JavaScript one, and so on. The service can’t see anyone’s home directory, so tools installed there (through sdkman or nvm, say) won’t be found.
A GitLab group on gitlab.com or your own GitLab, whose projects the agents work on. GitLab’s free tier is enough.
A Claude credential, which depends on who will use the install: see Claude.

2What you’ll run

The developer preview runs in local mode: the orchestrator, the web interface and every agent run on one server, as a single systemd service. That brings two limits:

One host only. Agents can’t run on other machines yet. Remote agents come with the final release.
The web interface stays on the server. For security, it listens on 127.0.0.1 only and has no sign-in, so you reach it through an SSH tunnel (see Open it).

Everything runs on your server. Only the web interface’s tunnel comes in; the rest goes out, to your GitLab, to Anthropic, and to the services your own MCP servers use. Dashed boxes are yours to add.

systemd runs CodeTroupe as one service, under its own codetroupe account, in a sandbox, and restarts it if it fails.
The orchestrator is a Java daemon. It reads your GitLab, decides who works on what and when, keeps its database in /opt/codetroupe/var, and serves the web interface.
Each agent at work is a Claude Code session: the claude binary, pinned by the release, started by the orchestrator in its story’s worktree. It reaches Anthropic for the model, and GitLab through the GitLab MCP server, as the agent’s own account and with only the tools its role needs.
Your own MCP servers give agents your other tools: your docs, another tracker, a database schema, an internal API. You add them to the install, and turn them on per project and per role.
Your repository’s own know-how: its CLAUDE.md, and the skills in its .claude/skills, which tell agents how your team does particular things: a database migration, your API’s error format, a review checklist. An agent loads a skill when its task calls for it, the same skills your developers use. CodeTroupe still decides the workflow; these only shape how the work is done. Nothing else in .claude reaches an agent.
The local git repositories hold a clone of each project and a worktree per story. Agents hold no git credentials: they edit and commit, and the orchestrator does every fetch and push, a push under the agent’s own account.
Connections only go out: to your GitLab, to Anthropic, and to whatever your own MCP servers reach. Nothing listens beyond 127.0.0.1.

3Prepare GitLab

Every agent works under a GitLab account of its own, so its commits, merge requests and reviews carry its name. CodeTroupe has one more account for itself, for what no agent does: labels, reviewers, retrying pipelines.

The accounts

One for CodeTroupe, and one for each agent. The smallest team is three agents: a developer, a reviewer and an architect. The example team adds a senior developer, making four. The first run asks who sets them up:

CodeTroupe

It creates them as the group’s service accounts, with their roles and tokens, and gives the example team’s accounts their portraits. Give it a personal access token of an Owner of the group, or of an admin of your GitLab, with the scope api. Make it to expire tomorrow: it is used only while the first run runs, never written down, and you can revoke it once the first run is done.

You

When an Owner’s token isn’t to be had, for example on a company GitLab whose admins keep accounts to themselves. Make them before the first run, as below, and answer me when it asks.

Making the accounts yourself

Service accounts made by the group’s Owner or an admin, or ordinary accounts, each with an email address of its own.

Give them roles in the group

Account	Role in the group
CodeTroupe’s	Developer or more. Maintainer also lets it retry pipelines on protected branches.
Each agent’s	Developer

Make a token for each account

For a service account, in the group’s Settings › Service accounts. For an ordinary account, signed in as it, in Edit profile › Access tokens (on gitlab.com, gitlab.com/-/user_settings/personal_access_tokens). Choose Generate token › Legacy token: the scopes below are a legacy token’s.

GitLab's Generate token menu, offering a fine-grained token or a legacy token. — Generate token › Legacy token

GitLab's legacy token form with the scopes write_repository and api ticked, and the others clear. — A developer’s scopes: `api` and `write_repository`

Account	Scopes
CodeTroupe’s, and each developer’s	`api`, `write_repository`
The reviewer’s and the architect’s	`api`, `read_repository`

The form suggests an expiry a month ahead. Set it further, up to the limit it shows, and note the date: when a token expires, codetroupe doctor says which.

Set up each project the agents merge into

In the project’s Settings › Merge requests, which needs Maintainer:

Setting	Value
Merge method	Fast-forward merge required
Squash commits when merging	Require required
Pipelines must succeed	On recommended
Squash commit message template	`%{title}`, a blank line, `%{all_commits}`, a blank line, `%{url}` recommended, so the agents’ commit messages reach your main branch

A project with a pipeline has each change checked after it merges, and a red pipeline goes back to an agent to fix. A project without one works too, but nothing is checked. If a project’s pipeline leaves merge requests or the main branch out, CodeTroupe waits five minutes for one, then goes on without it and says so on the System page.

4Claude

CodeTroupe’s agents run Claude Code. Which credential they use depends on who uses the install, following Anthropic’s terms:

A team, or any install other people use

An Anthropic API key, from console.anthropic.com. Its usage is billed to the key’s owner. A Claude subscription is personal, and Anthropic’s terms don’t allow making it available to anyone else.

Your own install, used only by you

Your own Claude Pro or Max subscription, signed in through Claude Code’s own login. CodeTroupe never sees or stores it. Subscription limits assume ordinary, individual use, and several agents working at once use them up quickly; CodeTroupe pauses until they reset.

You are responsible for following Anthropic’s terms for the credential you use.

5Install

On the server:

curl -fsSL https://codetroupe.com/install.sh | sudo bash

It downloads the latest release, checks it against its checksums, and then:

creates a system account, codetroupe, with no login shell;
puts everything under /opt/codetroupe: the release, its own Java, Node and Claude Code (pinned, and checked against their checksums), the configuration in etc/ and the data in var/;
installs a systemd service and the codetroupe command;
starts the first run, below.

Nothing is written to anyone’s home directory, and an existing Claude Code setup on the server is left alone.

The web interface listens on port 8081. If another program on the server already uses it, the installer names that program and stops before changing anything. Run it again with another port by adding -s -- --port 8090 after bash. To move an install later, run sudo codetroupe port 8090.

CodeTroupe is free to use under the PolyForm Internal Use License 1.0.0: you may use it for the internal business operations of you and your company, and you may not distribute it.

6The first run

The installer goes straight on to it. To run it yourself later:

sudo codetroupe init

It checks every answer with GitLab, or with Claude, before the next question. Tokens aren’t shown as you type or paste them.

It asks for	Give it	It refuses when
GitLab address	`https://gitlab.com`, or your own GitLab’s	it can’t reach it
Who sets up the accounts	`codetroupe`, or `me` if you made them
With `codetroupe`: an Owner’s token	a token of an Owner of the group, or of an admin, with `api`	GitLab doesn’t accept it, or it lacks `api`
With `me`: the orchestrator account’s token	CodeTroupe’s token	GitLab doesn’t accept it, or it lacks a scope
The group	its path, `your-group`	with `codetroupe`, the token’s account isn’t an Owner there or an admin, and it asks who sets up the accounts again; with `me`, the account is less than Developer there
Agents	`example` for four, or `minimum` for three
With `codetroupe`: how the usernames start	`codetroupe-your-group`, the default, or your own	one of the names is someone else’s on GitLab
With `me`: each agent’s token, by name	that agent’s token	it lacks a scope, it is another account’s already given, or the account is less than Developer in the group
Who will use this install	`team`, or `just-me`
The Anthropic API key, for a team	the key	Claude Code can’t sign in with it

When an answer is refused, it says why and asks again. Fix it on GitLab (make a new token with the missing scope, or change the account’s role) and paste the answer again. Nothing is written until you confirm the summary at the end, so stopping with Ctrl-C leaves nothing behind.

After you confirm, it creates the accounts if it is to, then writes /opt/codetroupe/etc/codetroupe.yml and secrets.env (readable by root only). If creating the accounts fails partway, it revokes the tokens it made and writes nothing; running it again uses the accounts it created. For just-me, Claude Code’s own sign-in follows: it shows an address to open in your browser and asks for the code you get there. Then it runs the checks the service runs on every start, and starts it.

Checking it all, as the daemon will on every start:
  …
codetroupe is running, paused: nothing happens on GitLab until you look and press Resume.
From your own machine:  ssh -L 8081:localhost:8081 your-server

7Open it

The web interface listens on 127.0.0.1:8081 only. From your own machine:

ssh -L 8081:localhost:8081 your-server

then open http://localhost:8081. The first run prints this command for your server, and codetroupe status shows it again. If port 8081 is taken on your own machine, change only the first number: ssh -L 18081:localhost:8081 your-server, then open http://localhost:18081.

This is a developer preview, so the web interface has no sign-in. Keep it on 127.0.0.1: anyone who can reach the port can start agent sessions and read their transcripts. The tunnel is the way in.

A new install starts paused. Nothing happens on GitLab until you have looked around (the agents, the projects it found, the System page) and pressed Resume.

8Your first story

Write a small issue in one of the group’s projects, as you would for an engineer: what it is for, and what done looks like. A small change makes a good first story.
Add the ai-managed label. That is the only opt-in: CodeTroupe touches nothing without it.
Watch it go. A developer picks it up and assigns it to itself, builds it on a branch, and opens a merge request. The reviewer reviews it, and asks for changes until it’s right.
Then it’s yours. Approve the merge request and merge it in GitLab. The pipeline after the merge checks it, and the story is done.

Issues, tasks, incidents and test cases are supported. Custom work item types (GitLab Premium and Ultimate), epics, and objectives and key results are not.

For a bigger goal, add ai-type::design as well: the architect writes a design first, you review it like any change, and the stories it plans are created when it merges.

9When something is wrong

sudo codetroupe doctor   # every check again, the server's too, and what to fix
codetroupe status        # running or not, and how to open the web interface
codetroupe logs          # the service's journal, followed

CodeTroupe is a developer preview with community support, and no official support.

Questions: the CodeTroupe Discord.
Bugs: the public issue tracker.