Getting Started

Docker is the easiest way to run Upkeep. Everything – the Go binary, Claude Code, the tea CLI, and other tools – is bundled in the image.

Quick start

Run the setup script to start Forgejo, create bot accounts, and configure everything:

script/setup

Setup will prompt for an Anthropic API key if ANTHROPIC_API_KEY isn’t set. You can also use a Claude subscription (Max, Pro, Team, or Enterprise) instead – see Authenticating Claude below.

Once setup finishes, start the bots:

docker compose up upkeep

This runs cycles in a loop: managerbot first, then all role bots in parallel, then managerbot again. Cycles repeat with a configurable pause between them.

Running individual bots

docker compose run --rm upkeep run managerbot --turns 5
docker compose run --rm upkeep run forkbot --turns 20
docker compose run --rm upkeep run securibot --prompt "Audit simplecov dependencies"

Running a single cycle

docker compose run --rm upkeep cycle
docker compose run --rm upkeep cycle --sequential
docker compose run --rm upkeep cycle --turns 15

Other commands

docker compose run --rm upkeep report
docker compose run --rm upkeep web

The web dashboard serves on port 7200 by default. The runner and bots push events to it over an internal API – tool calls, text output, lifecycle transitions – and the dashboard streams them to the browser via SSE.

Authenticating Claude

If you have a Claude Code subscription (Max, Pro, Team, or Enterprise), generate a long-lived OAuth token:

claude setup-token

If you don’t have the Claude CLI installed locally, generate the token from inside the container:

docker compose run --rm --entrypoint claude upkeep setup-token

Add the token to CLAUDE_CODE_OAUTH_TOKEN in the .env file.

Alternatively, set ANTHROPIC_API_KEY in .env to use an Anthropic API key directly.

Custom domain or port

Both URLs default to http://localhost:7100. To use a custom domain or port, set FORGEJO_PUBLIC_URL and FORGEJO_URL before running setup, and update public_url in upkeep.yml to match. If you use a custom domain, add it to /etc/hosts.

Starting over

To wipe everything and start fresh:

docker compose down -v
script/setup

The -v flag removes named volumes (Forgejo data, runner data, CLI auth credentials). Without -v, only containers are stopped.

Local setup (without Docker)

See docs/local-setup.md in the main repository for instructions on installing CLIs locally and building the Go binary yourself.