# 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) # Appendix: README.md (from the rookrunner repo) ## Rookrunner A local tool, worker agent, and execution protocol for software builds and tests. **Status:** M1 is complete. M3 is implemented: the MCP adapter and the dashboard are in the tree. The owned engine runs owner CI. M4, the downloadable preview, is planned in [the release plan](docs/planning/m4-release.md). A wheel and a source tarball build from this tree and are not yet published. See [Install](docs/install.md). The worker runs synthetic development fixtures and executes one captured workflow job in a caller-pinned container. **Accepted direction:** Rookrunner will own its workflow execution engine and incrementally match GitHub Actions behavior. The earlier act backend selection is superseded. See the [engine decision](docs/decisions/0003-owned-execution-engine.md) and [compatibility plan](docs/design/execution-engine.md). Developers and coding agents will submit jobs, follow output, and retrieve results through the same execution service. The first release targets one local worker. Later designs can extend execution to private machines and managed capacity. ### Start here - [Product requirements](docs/prd.md): users, scope, acceptance criteria, and open decisions. - [Technical design](docs/design/architecture.md): components, execution boundaries, and recovery. - [Execution protocol draft](docs/design/protocol.md): client and worker contract. - [Build milestones](docs/roadmap.md): implementation order and completion evidence. - [Install](docs/install.md): the 0.1.10 wheel and the host layout. - [Review policy](REVIEW_POLICY.md): leaf vs trunk, proof, review and merge rules. ### Schedule A poll of the default-branch tip runs a workflow that lists `on.schedule`. Each entry is `{cron: "..."}` with five POSIX fields, evaluated in UTC. When both the day-of-month and the day-of-week are restricted, the minute matches if either field matches. `7` and `SUN` are Sunday. An unusable cron is rejected. A `timezone` key, and any key other than `cron`, is rejected. Evaluation stays in UTC. The first time a workflow is seen, the poll records the latest due minute and does not run it. A later poll runs at most the newest minute that is due, including one catch-up after downtime. That minute is not run again after a restart. The due minute and the tip SHA are stored before submit, so a lost reply retries that SHA after the default branch moves. The run checks out that stored SHA. `github.event_name` is `schedule` and `github.event.schedule` is the cron text. File-backed secrets follow the same rule as a push to the default branch. The check context is `rookrunner///schedule`. A due minute runs on the first poll at or after that minute. The engine does not choose the interval. The owner poll is every 5 minutes, so a shorter cron still runs at most once per poll. ### Project boundaries This is an independent repository under Moonbase2090. `execution-platform` is a temporary directory name. Rookrunner is the working title. The final public name, CLI name, package identifier, and domain remain undecided. The project license is the MIT License, in [LICENSE](LICENSE). The distribution name is `execution-core`. Local Actions is a reference implementation outside this repository. No source or configuration has been imported from it. Implementation choices in these documents are proposals unless explicitly marked as accepted. The intended distribution is open source under that license. ### Untrusted code A poll refuses untrusted code. A fork, a head repository other than the owner repository, a pull request author who is not `OWNER`, `MEMBER`, or `COLLABORATOR`, or a commit whose author or committer cannot write to the repository produces a warning that names the reason. No run is created. A missing or unrecognized author association is refused. The commits checked are a pushed tip and every commit on a pull request. Writing means the `write` or `admin` permission GitHub reports for that login on the repository. A commit without a GitHub account is refused, and so is a permission GitHub does not return. Without `--app-key` the poll sends no credential, so GitHub returns no permission and the commit is refused. The committer `web-flow` passes only when GitHub verified the commit's signature, and that commit's author is still checked. A pull request with more commits than GitHub lists (250) is refused. `--allow-untrusted` with that commit's SHA is the only override. The flag is not stored and it is not the default. The run record stores the override and the reason. See [the roadmap](docs/roadmap.md#planned-paused). A pull request that changes a workflow file is also refused. No run is created unless `--allow-pr-workflow` names that pull request's author association. `OWNER`, `MEMBER`, and `COLLABORATOR` are the accepted names. A missing association does not match. The flag is not stored and it is not the default. A diff that cannot be read is refused the same way. The fetched merge commit is checked out only when its first parent is the listed base and its second parent is the listed head. Every engine call uses the Docker context named `default` unless `worker --docker-context` or `ROOKRUNNER_DOCKER_CONTEXT` names one. An inherited `DOCKER_CONTEXT` or `DOCKER_HOST` does not select the engine. The scheduler thread uses that same context. A bash or sh `run` script quotes each `${{ }}` value. An unquoted value is single-quoted. A value already inside double quotes is escaped. A value already inside single quotes escapes `'`. Another shell, or a context the script cannot prove, is refused. An expression in `eval` or in a shell `-c` command is refused. A brace group or an `if`, `while`, or `for` body does not hide it. A backslash in that command name does not hide it either. A backslash before a newline is not part of that name. `$'eval'`, `$"eval"`, and a command substitution used as the command name are refused when that command contains an expression. An unquoted `*`, `?`, or `[` in that command name is refused the same way. The `[` command stays accepted. An unquoted `{` in that command name is refused the same way. `builtin eval` is refused the same way. ### Try the development contract Requires Linux and Python 3.11+ (validated on Python 3.14.6). Synthetic fixtures do not need Docker. Starting the program requires PyYAML 6.0.3, because importing the worker imports the planner. From this checkout: ```bash export PYTHONPATH="$PWD/src" python3 -m execution_core --state "$PWD/.execution-state" worker --repository "$PWD" ``` Job containers use Docker network `none` by default. `worker --network bridge` opts in to egress. Service containers start only with that opt-in. GitHub-hosted runners have public internet access by default (https://docs.github.com/en/actions/concepts/runners/private-networking). The Docker socket stays unmounted unless you add `--docker-socket`. That flag gives the job the host Docker service, which container-dependent tests need. The job keeps the caller user. When the socket is mounted, a private Docker volume is mounted into the job at that volume's mountpoint, and `TMPDIR`, `TEMP`, and `TMP` default to it. A workflow env value can replace those three. The volume is removed with the job container. The host `/tmp` is not mounted. The image must already contain the Docker client. Combining `--docker-socket` with `--app-key` or `--secrets` refuses at startup unless `--runner-image` is set and a startup probe shows the configured key directory is not a usable directory in that image. A worker that starts with `--docker-socket` warns that the exposure includes `~/.config/rookrunner/keys/` and `~/.config/rookrunner/files/`. GitHub requires that service to be installed and running on a self-hosted runner (https://docs.github.com/en/actions/how-tos/manage-runners/self-hosted-runners/monitor-and-troubleshoot#troubleshooting-containers-in-self-hosted-runners). In another terminal, from the same checkout: ```bash export PYTHONPATH="$PWD/src" python3 -m execution_core --state "$PWD/.execution-state" describe python3 -m execution_core --state "$PWD/.execution-state" submit --backend development --key example-1 --delay-ms 500 python3 -m execution_core --state "$PWD/.execution-state" list python3 -m execution_core --state "$PWD/.execution-state" get RUN_ID python3 -m execution_core --state "$PWD/.execution-state" logs RUN_ID --limit 1024 python3 -m execution_core --state "$PWD/.execution-state" cancel RUN_ID python3 -m execution_core --state "$PWD/.execution-state" submit \ --key example-workflow --workflow .github/workflows/test.yml --job-id build \ --event '{}' --image rust@sha256:<64 lowercase hex digits> python3 -m execution_core --state "$PWD/.execution-state" follow RUN_ID ``` Replace `RUN_ID` with the submission's `result.run_id`. Reuse a submission key to retry; use a new key for a new run. Commands return JSON. A version 1 submit needs `--workflow`, `--job-id`, and `--event`. `--image` is optional when the worker was started with `--runner-image`. `--event-name` is optional. When it is set, that name is part of the submission, and a retry with a different name conflicts. `--backend development` may be included on that command and is not sent. `follow` prints one JSON envelope per state change and per nonempty log page, and exits zero only when the run is `succeeded` with exit code 0. `get` and `logs` stay one-shot. Successful submission only means acceptance. Stop the worker with Ctrl-C. State remains on disk for restart. It contains synthetic fixture input and output; do not place credentials in fixtures or commit state directories. Install the pinned development-only tools and run contract/integration checks (requires `uv`; the worker itself still has no third-party runtime dependencies): ```bash uv sync --locked --group dev PYTHONPATH=src .venv/bin/python -m unittest discover -s tests -v .venv/bin/ruff check src tests .venv/bin/ruff format --check src tests ``` `tests/test_run.py` needs a local Docker daemon. It builds a disposable image and passes that image id. It does not select a project default image. M2 now provides preparatory source capture (requires Git): ```bash PYTHONPATH=src python3 -m execution_core --state "$PWD/.execution-state" snapshot \ --repository /absolute/path/to/repository --workflow .github/workflows/test.yml ``` Use `--include relative/path` for each required untracked file. This creates a snapshot, not a run. See the [capture rules and limitations](docs/design/source-capture.md). See the [implemented contract](docs/design/development-contract.md), [implementation choice](docs/decisions/0001-executable-foundation.md), and [M1 completion evidence](docs/validation/m1-completion.md), and [machine-readable schemas](schemas/v0/README.md). M1 covers the development backend. Version 1 accepts one workflow job and the worker executes it after recording the attempt. The MCP adapter and the dashboard are implemented. Packaging is the M4 preview and is not published yet. Development dependency provenance is [recorded here](docs/development-dependencies.md). # Appendix: docs/install.md (from the rookrunner repo) ## Install Version 0.1.10 is published as a wheel and source tarball with `SHA256SUMS`. Use the release links above to download them. The commands below install a downloaded wheel or describe an optional dedicated host layout. ### A developer machine Install the wheel into a new virtualenv. The wheel depends on PyYAML 6.0.3 and does not vendor it. ```sh uv venv uv pip install ./execution_core-0.1.10-py3-none-any.whl python -m execution_core --help ``` Do not set `PYTHONPATH`. `pip install` of the same wheel is the same install. The checkout procedure in the README remains the way to work on this tree. ### A host that follows the dedicated host layout This procedure matches [deploy/rookrunner-worker.service](../deploy/rookrunner-worker.service). It does not change that file. A host copy of the unit appends only that host's image digest. The copy still has no key path, no `--app-key`, no `--docker-socket`, and no listen socket. 1. Create `/var/lib/rookrunner`, `/var/lib/rookrunner/engine`, `/var/lib/rookrunner/clone`, and `/var/lib/rookrunner/state`. The state directory is mode `0700`. The socket the worker creates is mode `0600`. 2. Unpack the source tarball so `src/execution_core` lands at `/var/lib/rookrunner/engine/src/execution_core`. ```sh tar -xzf execution_core-0.1.10.tar.gz -C /var/lib/rookrunner/engine --strip-components=1 ``` 3. Install PyYAML for `/usr/bin/python3`. The unit runs that interpreter, not the wheel. ```sh /usr/bin/python3 -m pip install 'pyyaml==6.0.3' ``` 4. Do not write a `.pth` file. The unit already sets `PYTHONPATH=/var/lib/rookrunner/engine/src`. 5. The clone, the image, and starting the user service stay operator steps. Copy the repository unit as it is, and append only that host's image digest on the `ExecStart` line. When that host's jobs need egress, also add `--network bridge` on that line. Cargo and pip need it. The repository unit omits the flag, so a copied unit has no egress until the host adds it. A host copy of the worker unit must set `NoNewPrivileges=yes`. ### Upgrade Replacing the engine tree does not change a unit that is already running. Before restarting the worker on a tree whose job network defaults to `none`, add `--network bridge` to the host copy's `ExecStart` when jobs need egress. This page does not edit a running unit. A host copy of the worker unit must set `NoNewPrivileges=yes`. The repository unit sets that directive. A copy that omits it is reported by systemd as `NoNewPrivileges=no` and must be set to `yes`. This page does not edit a running unit. Do not copy a private key into the engine tree. Do not mount the Docker socket unless the worker is started with `--docker-socket`. The repository unit does not pass that flag. # Appendix: docs/design/protocol.md (from the rookrunner repo) ## Execution protocol — draft v0 Status: proposed workflow protocol. This broader design is not an implemented or stable workflow wire specification. The completed M1 v0 subset is specified separately in [the development contract](development-contract.md) and [machine-readable schemas](../../schemas/v0/README.md). In particular, synthetic fixture submission does not accept the workflow/source selection proposed here. Workflow inputs require a separately negotiated extension/version in M2. ### Transport and versioning Proposed local transport: JSON-RPC 2.0 messages, one JSON object per line, over a Unix socket. Request IDs correlate replies. A separate submission key prevents duplicate execution after a lost reply. Clients begin with `worker.describe`, which advertises protocol versions, worker identity, repository identity, and capabilities. Mutating requests carry an explicit protocol version; unsupported versions return an error before side effects. Initial limits: 1 MiB per message and 64 KiB of decoded log data per page. Long-running jobs never hold a submission response open for their full execution. Poll run status and paginated logs in v0. Streaming subscriptions are deferred. ### Operations | Method | Input | Output | | --- | --- | --- | | worker.describe | None | Versions, worker/root identity, capabilities, readiness, configured limits | | run.submit | Version, submission key, workflow/job/event selection, source selection | Accepted run ID, snapshot identity, initial state | | run.get | Run ID | Current state, attempt information, evidence, errors | | run.list | Opaque cursor, bounded limit, optional state filter | Runs and next cursor | | run.logs | Run ID, opaque cursor, bounded byte limit | Base64 log bytes, next cursor, end-of-stream flag | | run.cancel | Version, run ID | Current run and cancellation-request status | | run.artifacts | Run ID, optional cursor | Artifact manifest entries and next cursor | | artifact.read | Artifact ID, offset, bounded byte limit | Base64 bytes, next offset, end flag | Source and workflow paths are repository-relative. Reject escapes outside the configured repository. Do not accept arbitrary execution commands as an undocumented escape hatch. Base64 log and artifact payloads preserve arbitrary bytes; clients decode and render safely. End-of-stream is final only after the writer closes, not merely when a page is temporarily empty. ### Submission semantics Validation and source capture complete before acceptance. Invalid submissions do not create executable queue entries. The submission key is scoped to the worker and retained with the run. Repeating the same key and normalized request returns the same run, including its original captured inputs. Reusing that key with different parameters returns `IDEMPOTENCY_CONFLICT`. Clients use a new key to capture newer source, even when workflow selection is identical. Acceptance is durable before its reply. If the connection closes first, the client retries with the same key. Run pruning must retain key tombstones for a documented retry window; expired keys must not silently recreate old work. The implementation milestone must define that window and its client-visible expiry behavior. ### Run state ```mermaid stateDiagram-v2 [*] --> queued: accepted queued --> running: attempt starts queued --> cancelled: cancelled before start running --> succeeded: backend exits zero running --> failed: execution failure running --> cancelled: cancellation cleanup confirmed running --> lost: execution ownership unresolved ``` `cancel_requested` is an independent flag while active cleanup proceeds. Readiness or setup failure after execution starts produces failed with a structured error; exit_code may be null. Success requires `state=succeeded` and `exit_code=0`. Lost is terminal uncertainty, not an assertion that all execution has stopped. Worker readiness remains false for conflicting work until unresolved ownership is reconciled. ### Run record - Identity: run ID, worker ID, optional parent run ID, submission key. - Selection: workflow path, job selection, event and event-payload digest. - Source: snapshot ID and digest, workflow digest, base commit, dirty flag. - Execution: attempt ID, backend name/version, image digest, configuration digest, compatibility notes. - State: queued/running/succeeded/failed/cancelled/lost, cancellation flag, structured error, nullable exit code. - Timing: acceptance, start, and finish timestamps in UTC; elapsed duration when available. - Evidence: log availability, artifact manifest references, cleanup outcome. Artifact entries include an ID, logical relative path, size, digest, and media type when known. Arbitrary absolute host paths are not portable artifact identifiers. Credentials never appear in run records. Record credential references only if that capability is added later. ### Errors JSON-RPC reserves parse, invalid-request, unknown-method, invalid-params, and internal-error codes. Domain errors use a server-error code with a stable `data.kind`, readable message, and retryability flag. Initial kinds: VERSION_UNSUPPORTED, CAPABILITY_UNSUPPORTED, ROOT_MISMATCH, SOURCE_UNSTABLE, WORKER_NOT_READY, QUEUE_FULL, RUN_NOT_FOUND, CURSOR_EXPIRED, IDEMPOTENCY_CONFLICT, STORAGE_FULL. Transport errors must not be rewritten as successful job results. Unknown capabilities fail explicitly. The worker must not silently ignore requested execution constraints. ### Before implementation is called compatible Publish machine-readable schemas, valid and invalid examples, numeric error assignments, and default limits. Define event payloads, idempotency retention, artifact retention, and snapshot rules precisely. Verify duplicate submissions, client disconnects, log paging, malformed requests, cancellation races, and crash recovery. Record which protocol version each released client and worker supports.