Install Ballet on one host

The compose installation runs Ballet’s services as containers on one Linux host with Docker Engine: Core (with the web UI), Knowledge, the LLM gateway and an agent that runs coding-agent sessions as processes in its own container (Agents). Ballet needs no Docker socket.

Requirements

  • Linux with Docker Engine and the Compose plugin (docker compose). The services use the host network (network_mode: host); with Docker Desktop, enable host networking in its settings.

  • Free ports 8080 (Core), 8081 (Knowledge), 8082 (gateway), 8083 (agent metrics), 9090 (Prometheus), 3000 (Grafana), and 8180 for the development Keycloak.

  • An Anthropic API key for the projects, and a git token for their repositories.

Start

git clone https://github.com/denyszorinets/ballet.git && cd ballet
docker compose -f deploy/compose.yaml up -d --build

This builds the images (make images builds them too) and starts the services without authentication (see below for several users). The agent image, ballet-agent, has git, Claude Code and common build tools; sessions run in it as the user ballet. Extend it for your projects’ toolchains and set BALLET_AGENT_IMAGE to your image.

Open http://localhost:8080 on the host — no sign-in: you are the local user. Then, as in Run Ballet locally:

  1. create an organization and a project;

  2. store the organization’s Anthropic key (organization page → LLM credentials);

  3. in the project settings, set the repository and a git token;

  4. add tickets — or plan them with the planner — and move them to Ready.

Configuration

Every service reads its BALLET_* environment variables (Configuration); deploy/compose.yaml sets the installation-specific ones and takes these from the environment or an .env file next to it:

BALLET_OIDC_ISSUER_URL

Your identity provider’s issuer. Empty (the default): no authentication — one local user, and Core listens on localhost only. Set it for several users: register the ballet-web public client with http://<host>:8080/* as redirect URI (Configure OIDC Authentication). To try it with the development Keycloak and its demo users (alice / alice): BALLET_OIDC_ISSUER_URL=http://localhost:8180/realms/ballet docker compose -f deploy/compose.yaml --profile keycloak up -d.

BALLET_PLATFORM_ADMINS

Claim matchers that are platform admins, e.g. groups:ballet-admins.

BALLET_ANTHROPIC_URL

Anthropic API base URL (default https://api.anthropic.com).

BALLET_AGENT_IMAGE

The agent image (default ballet-agent), e.g. one extending it with your projects’ toolchains.

BALLET_AGENT_NAME, BALLET_AGENT_CAPACITY

The agent’s name and how many sessions it runs at once (default 2). Sessions share the agent’s container, each in its own workspace.

BALLET_LOG_LEVEL

debug, info (default), warn or error.

Monitoring

The installation includes Prometheus (http://localhost:9090), scraping every service’s /metrics (Metrics), and Grafana (http://localhost:3000, admin / BALLET_GRAFANA_PASSWORD, default admin) with three dashboards in the Ballet folder:

Ballet · Delivery

Tickets done and failed, lead time, rework (loops per ticket), stage outcomes, pipelines in progress and what they wait for, questions and how fast they are answered — by planner or humans.

Ballet · LLM usage

Tokens and requests by organization, project, model and token type; refused or failed requests (for example over budget).

Ballet · Platform

Services up, durable jobs and dead jobs, runs and session durations, versions.

Every dashboard filters by organization and project. Prometheus keeps 30 days (BALLET_METRICS_RETENTION). The dashboards are generated by deploy/monitoring/dashboards.py (make dashboards); edit that script, not the JSON.

State and backups

All state lives in the ballet-data volume: Core’s and Knowledge’s SQLite databases, the token signing keys, the key encrypting stored credentials, and the service tokens. Back it up as a whole, with the services stopped:

docker compose -f deploy/compose.yaml stop
docker run --rm -v ballet_ballet-data:/data -v "$PWD":/backup alpine \
  tar czf /backup/ballet-data.tgz -C /data .
docker compose -f deploy/compose.yaml start

Upgrades

git pull
docker compose -f deploy/compose.yaml up -d --build

Database migrations run when the services start. Pipelines in progress continue (Recovery and stuck stages).

Security notes

  • With host networking the services listen on all interfaces: allow only port 8080 (or a TLS reverse proxy in front of it), and Grafana’s 3000 if you use it, through the host’s firewall. The gateway and Knowledge are only needed by agent sessions on the same host; Prometheus only by Grafana.

  • Agent sessions run on the host network as the unprivileged user ballet in the agent container: they can reach every service listening on the host.

  • The development Keycloak and its demo users are for trying Ballet; use your own identity provider for real use.