Your first real project

The Quickstart used a fake model and a local repository. A real project needs three things: a model key, a repository Ballet can push to, and an agent with the project’s toolchain.

1. Run Ballet without the fake model

make run

For a team or a server, install it with containers instead (Install Ballet on one host) and enable sign-in (Configure OIDC Authentication).

2. Add a model key

On the organization page, under LLM credentials, save your Anthropic API key. Keys are stored encrypted and never shown again. Agent sessions never see the key: they call Ballet’s LLM gateway with a short-lived run token, and the gateway adds the key, meters every token and enforces budgets (LLM Gateway). A project can override the organization’s key in its settings.

3. Connect the repository

In the project’s Settings:

Repository URL

The HTTPS clone URL, e.g. https://github.com/acme/web.git.

Default branch

The branch tickets start from and merge into, e.g. main or develop.

Branch template

How ticket branches are named, e.g. feature/{ticket}_{slug} (default ballet/{ticket}-{slug}).

Forge

Automatic uses the GitHub adapter for github.com: Ballet opens pull requests, follows their review and CI state and — when the ticket’s policy allows — merges them. Other hosts use Plain git: Ballet pushes branches and notices merges.

Git token

A token that can push branches and, on GitHub, open and merge pull requests. A fine-grained GitHub token needs Contents and Pull requests (read and write), and Checks and Commit statuses (read).

4. Give the agents the project’s toolchain

Agents verify their work by building and testing it, so sessions need the project’s compilers, package managers and services.

• With make run, sessions run on your machine: whatever is installed there is what they have. Use Setup commands in the settings for per-workspace preparation (npm ci, go mod download, …).

• For anything beyond a laptop, build an agent pool from the project’s devcontainer: the ballet-agent devcontainer Feature adds the agent to the image, and every container of it serves the project’s runs (Build an agent pool from a devcontainer). Set the pool’s name as Agent pool in the settings.

5. Set limits

Before leaving agents alone, set budgets (organization page and project settings): tokens per ticket and per day. Work over budget waits instead of spending (Budgets). Each ticket’s policy says whether a human must also approve the pull request and whether Ballet merges or a human does; the default is fully autonomous (Review agent · Merge auto).

6. Plan and run

Open Planner and describe what you want — a feature, a fix, a milestone. The planner reads the project’s tickets and knowledge, asks what it needs, and proposes a changeset of epics, tickets with acceptance criteria, and dependencies. Approve it, move the tickets you want done to Ready, and follow them on the board.

Tickets should be small and independently testable; the planner is instructed to cut them that way, and you can edit any ticket before it runs. Continue with Planning with the planner.