# Rookrunner > Rookrunner is a self-hosted CI runner: a local worker, CLI and execution protocol that runs GitHub Actions-style workflow jobs against captured source on your own machine. It is a preview, in active development. The Python distribution is `execution-core` and the CLI is `python -m execution_core`. Every command returns JSON. A stdio MCP adapter exposes the same run operations to agents. This file is for agents. Full docs: https://rookrunner.com/llms-full.txt. Tool list: https://rookrunner.com/agents.json. Source: https://github.com/moonbase2090/rookrunner (MIT). ## Prerequisites - Python 3.11 or later. PyYAML 6.0.3 (installed as a wheel dependency). - `uv` or `pip` to install the wheel. - The worker runs on Linux. Synthetic development fixtures do not need Docker; executing workflow jobs needs a local Docker engine and a digest-pinned image. - Git, for `snapshot` source capture. ## Install The preview release (v0.1.10) is a pure-Python wheel and a source tarball with `SHA256SUMS`: https://github.com/moonbase2090/rookrunner/releases ### macOS and Linux ```sh uv venv uv pip install https://github.com/moonbase2090/rookrunner/releases/download/v0.1.10/execution_core-0.1.10-py3-none-any.whl .venv/bin/python -m execution_core --help ``` With pip: `python3 -m venv .venv`, then `.venv/bin/pip install `. Do not set `PYTHONPATH`. ### Windows The same commands work in PowerShell; run `.venv\Scripts\python -m execution_core --help`. (The worker itself targets Linux.) ### Build from source ```sh git clone https://github.com/moonbase2090/rookrunner.git && cd rookrunner uv build # writes the wheel and source tarball into dist/ # or run from the checkout: export PYTHONPATH="$PWD/src" python3 -m execution_core --state "$PWD/.execution-state" describe ``` For a dedicated Linux host layout (systemd user unit), see docs/install.md in the repo. ## Configuration - `--state DIR` (required, before the subcommand): private worker state directory. The worker socket in it is mode 0600. - Start a worker bound to one repository: `python -m execution_core --state STATE worker --repository /path/to/repo`. - Job network: `--network none` (default, no egress) or `--network bridge` (egress, service containers). - Docker context: `--docker-context NAME`, else `ROOKRUNNER_DOCKER_CONTEXT`, else the context named `default`. Inherited `DOCKER_CONTEXT`/`DOCKER_HOST` are ignored. - `--runner-image IMAGE@sha256:...`: default image when a submit omits `--image` (runs-on ubuntu-latest). The worker never pulls or builds it. - Opt-ins, off by default: `--docker-socket`, `--passwordless-sudo`, `--secrets` (with `--github-repository owner/name`, `--secret-ref`, `--secret-pusher`), `--app-key` (GitHub App key in `$XDG_CONFIG_HOME/rookrunner/keys/`, override with `--key-dir` or `ROOKRUNNER_KEY_DIR`). - MCP: run `python -m execution_core --state STATE mcp` as a stdio server, e.g. `{"mcpServers": {"rookrunner": {"command": "/path/to/.venv/bin/python", "args": ["-m", "execution_core", "--state", "/path/to/state", "mcp"]}}}`. ## Tools ### MCP tools (`mcp` subcommand) - `describe` — read the worker description. No params. Example: `{}` - `get` — read one run. Params: `run_id` (required). Example: `{"run_id": "RUN_ID"}` - `list` — one page of runs. Params: `cursor`, `limit`, `state`. Example: `{"limit": 10}` - `logs` — one page of a run log. Params: `run_id` (required), `cursor`, `limit`. - `artifacts` — one page of a run's artifacts. Params: `run_id` (required), `cursor`, `limit`. - `artifact_read` — one page of an artifact by id (no path argument). Params: `artifact_id` (required), `offset`, `limit`. - `submit` — submit the checkout this worker is bound to. Use a new submission key after each edit. Params: `submission_key`, `workflow`, `job_id` (required), `image`. Example: `{"submission_key": "fix-1", "workflow": ".github/workflows/test.yml", "job_id": "build"}` - `cancel` — cancel a run, returns the worker record. Params: `run_id` (required). ### CLI (`python -m execution_core --state STATE `) - `worker --repository PATH [--network bridge|none] [--docker-context NAME] [--docker-socket] [--runner-image IMG] [--disk-budget-bytes N] [--secrets --github-repository O/R] [--secret-ref REF] [--secret-pusher LOGIN] [--app-key PATH] [--key-dir DIR] [--api-base URL] [--node24 DIR] [--passwordless-sudo]` — run the worker. - `describe` — worker description. - `submit --key KEY [--backend development --delay-ms N --exit-code N --output TEXT] | [--workflow PATH --job-id ID --event JSON [--event-name NAME] [--activity-type T] [--changed-file P]... [--commit-count N] [--diff-unavailable] [--image IMG]]` — submit a fixture or a workflow job. Reuse a key to retry. Example: `submit --key example-workflow --workflow .github/workflows/test.yml --job-id build --event '{}' --image rust@sha256:` - `follow RUN_ID` — poll status and logs until terminal; exits 0 only on `succeeded` with exit code 0. - `get RUN_ID` | `cancel RUN_ID`. - `logs RUN_ID [--cursor C] [--limit N]`, `artifacts RUN_ID [--cursor C] [--limit N]`, `artifact-read ARTIFACT_ID [--offset N] [--limit N]`. - `list [--cursor C] [--limit N] [--filter-state STATE]`. - `snapshot --repository PATH --workflow PATH [--include REL]...` — capture Git inputs; does not submit. - `mcp` — stdio MCP adapter. `dashboard` — terminal view of runs. `status-page` — read-only page on 127.0.0.1:8765. - `status --repository O/R --status-sha SHA --tested-commit SHA [--context C] (--credential-file F | --app-key K)` — post one commit status. - `dispatch --repository O/R --clone PATH --workflow PATH [--image IMG]` — run one workflow on the default-branch tip. - `poll --repository O/R --clone PATH --job WORKFLOW JOB_ID ... [--image IMG] [--credential-file F | --app-key K] [--place JSON] [--allow-untrusted SHA] [--allow-pr-workflow ASSOC] [--ssh-host H --remote-state DIR]` — one poll pass for an owner repository. - `call` — send one JSON-RPC request from stdin to the local worker socket. ## Usage workflows 1. Start a worker in one terminal: `python -m execution_core --state "$PWD/.execution-state" worker --repository "$PWD"`. 2. In another: `submit --backend development --key example-1 --delay-ms 500`, then `get RUN_ID`, `logs RUN_ID --limit 1024`, or `follow RUN_ID`. RUN_ID is the submission's `result.run_id`. 3. Run a real job: `submit --key k1 --workflow .github/workflows/test.yml --job-id build --event '{}' --image name@sha256:` then `follow RUN_ID`. 4. Agents: call MCP `submit`, then `get`/`logs`/`artifacts`; use a new `submission_key` after each edit. 5. Acceptance only: a successful submit means the run was accepted, not that it passed. ## Troubleshooting - Submit conflicts: a reused key with different inputs conflicts. Use a new key for a new run. - No network in job: the default is `--network none`; add `--network bridge`. - Container tests need Docker: add `--docker-socket` (grants host engine access) and an image that has the Docker client. - Startup refuses with `--docker-socket` plus `--app-key`/`--secrets`: set `--runner-image` so the key-directory probe can pass. - Poll refuses a run: untrusted author/fork, or a PR that changes a workflow file. Override per SHA with `--allow-untrusted`, or `--allow-pr-workflow OWNER|MEMBER|COLLABORATOR`. - Unusable cron or a `timezone` key in `on.schedule`: rejected; schedules are UTC. ## Links - [Full agent docs](https://rookrunner.com/llms-full.txt) - [agents.json](https://rookrunner.com/agents.json) - [Source](https://github.com/moonbase2090/rookrunner) - [Releases](https://github.com/moonbase2090/rookrunner/releases) - [Install guide](https://github.com/moonbase2090/rookrunner/blob/main/docs/install.md) - [Protocol](https://github.com/moonbase2090/rookrunner/blob/main/docs/design/protocol.md)