Install Roook

Operating system

Linux. Roook is developed on Linux and its automated tests run on Ubuntu. macOS and Windows (WSL 2 included) have not been tested. Roook uses POSIX process groups and file flags, so native Windows is not expected to work.

Python

3.12 or newer (requires-python in pyproject.toml). If you install with uv and have no matching Python, uv fetches one.

Docker

A running Docker daemon with the Compose plugin (docker compose). The CLI builds and starts your app in a container. Roook is developed against Docker 29; it does not check for a minimum version.

git

Roook copies or clones your repo into a workspace, keeps a baseline commit there and commits the fix to a branch.

IBM Bob Shell and Node.js

Live runs call IBM Bob through Bob Shell, the bob command, which is a Node.js program. Roook is developed with Bob Shell 2.0.5 on Node 24. Roook itself needs no Node.js.

Your app

A backend with an HTTP API, in any language, that can be built and started in Docker.

$uv tool install git+https://github.com/tony19053000/rook

This installs two commands: rook, and rook-pr-comment, which the GitHub Action uses to post its comment. Python packages Roook depends on are installed with it into an environment of its own.

There are no release tags yet. To stay on one version, install a commit by its full SHA:

$uv tool install git+https://github.com/tony19053000/rook@<full-commit-sha>

To run Roook once without installing it:

$uvx --from git+https://github.com/tony19053000/rook rook --help

rook --version
rook --help
docker info
bob --version

The first two show that Roook is installed and on your PATH. docker info fails when the Docker daemon is not running, and bob --version shows that Bob Shell is installed. None of them calls IBM Bob.

Bob is the only AI in Roook, and live runs use your own IBM Bob key. Install Bob Shell and get a key from IBM; Roook does not ship either.

• IBM Bob Shell documentation

Roook reads the key from the BOB_API_KEY environment variable of the shell that runs it. One way to set it without typing it into your shell history is a small file only you can read:

export BOB_API_KEY=<your-key>

chmod 600 ~/.bob-key.env
source ~/.bob-key.env

• Roook passes the key to Bob Shell only through the child process environment, never as a command-line argument, and scrubs it from its events and logs.
• Roook looks for Bob Shell at the path in ROOK_BOB_BIN if you set it, then at ~/.nvm/versions/node/v24.21.0/bin/bob, then as bob on your PATH.
• Each run has a Bob coin budget: rook run --budget 1.5 is the default. Once it is spent, Roook refuses further live Bob calls in that run. What your IBM Bob usage costs is between you and IBM.
• Never commit the key. In GitHub Actions, store it as a repository secret.

• Exactly what is sent to IBM Bob, and when

The package is named rook-cli; the command it installs is rook.

uv tool upgrade rook-cli
uv tool install git+https://github.com/tony19053000/rook --reinstall
uv tool uninstall rook-cli

The first line asks uv to upgrade the install. If it reports nothing to upgrade and you expected a newer commit, the second line installs again from GitHub. The third removes the commands.

Uninstalling does not remove Roook's own folder, ~/.rook/: the workspaces of your runs, Bob recordings if you made any, and credentials.json if you signed in. Run rook logout first if you signed in, then delete ~/.rook/ yourself.

• HTTP APIs only: no libraries, pure frontends, mobile apps or ML notebooks.
• Rules are checked on what your API returns. State that no HTTP request can read cannot be checked.
• Not on PyPI, and no release tags yet: install from GitHub, by commit SHA if you need a fixed version.
• Live runs need Docker and your own IBM Bob key.
• Tested on Linux only.
• The hosted site does not run your own repos: hosted runs of your own repos are turned off. Run them with the CLI on your machine.
• The Mapper cannot model every API yet. On two of Roook's own example apps, billing-service and wallet-api, it cannot yet set up actions that depend on other actions, so those two are not offered on the site.
• The GitHub Action has not yet been run on a GitHub-hosted runner. See the GitHub Action guide.

• Roadmap: shipped, limited and planned
• The GitHub Action's limitations

rook: command not found

uv's tool folder is not on your PATH. uv prints a warning about it at install time: run uv tool update-shell and open a new terminal.

The app won't start

The Mechanic tries up to 3 times, reading the app's logs each time. Then Roook asks for a setup value or shows the error. If your app needs a secret or a password to start, pass it with rook run --setup NAME, where NAME is an environment variable that holds it.

Bob returns an answer Roook can't use

Each agent must answer in a fixed JSON shape. Roook asks again with the error, up to 3 attempts, then tells you.

An action fails its dry run

Roook sends the HTTP response back to the Mapper, up to 3 times. An action that still fails is disabled for the run, and the search goes on without it.

A proposed rule disappears

A rule that does not hold on a fresh app is rejected as a wrong rule before you see it. The Rules guide explains the one exception.

No counterexample found

Roook reports that no counterexample was found within the budget. That is not proof the rules hold. Give the search more room with rook run --sequences 50000 --seconds 300.

A flaky counterexample

A sequence that breaks the rule in some replays but not all is shown with its count and marked flaky, and is still reported. Races usually look like this.

The fix is not verified

When a check fails, Roook goes back to the diagnosis with the new evidence, up to 3 times, then reports honestly that the fix is not verified. An unverified fix is not shipped.

Live Bob calls are refused

The run's coin budget is spent. Raise it with rook run --budget 3, or look at what the run already found: the engine's results stand without Bob.

set ROOK_ENV_NAME

rook replay and rook verify need the values your model reads from the environment. For a model that uses env.ADMIN_PASSWORD, set ROOK_ENV_ADMIN_PASSWORD before you run them.

--base-url must be your app on this machine

rook replay and rook verify send requests only to a loopback address such as http://127.0.0.1:8000. Start your app locally and pass that address.

GitHub repos need a sign-in

rook run owner/name needs rook login and the Roook GitHub App on that repo. To skip both, clone the repo yourself and run Roook on the folder.