kookster310/op-agent-engine repository overview

⁠OpenProject Agent Engine

Polls OpenProject work packages and dispatches the pi⁠ coding agent to work on them.

OpenProject is the system of record. The engine claims work, prepares a per-agent clone, renders a prompt, runs the agent, verifies the outcome against GitHub and OpenProject, and performs every status transition itself. Agents never change status: a human (or the engine) still owns the board.

• Source, docs and issues: https://github.com/310networks/openproject-agent-engine⁠
• License: MIT
• Security reports: see SECURITY.md⁠ — do not open a public issue

⁠Image

docker pull kookster310/op-agent-engine

linux/amd64 only. The engine itself is architecture independent, but the op, node and gh builds baked into the image are not cross-built, so no arm64 image is published.

The image is a runtime, not a deployment by itself: it ships the engine, the prompts and the agent definitions, and expects a docker/docker-compose.yml next to a .env you provide. That compose file lives in the repository, not in the image.

⁠Quick start

Requires Docker, OpenProject 17 (API v3) and a GitHub repository the agents can push to and merge in.

1. One-time OpenProject setup — statuses, the GIT_REPO and AGENT project/work-package fields, the Agent Worker role: docs/OPENPROJECT_SETUP.md⁠

2. Get the deployment directory (it is the whole deployment — copy anywhere, for example /opt/op-agent-engine):

   git clone https://github.com/310networks/openproject-agent-engine
   cd openproject-agent-engine/docker
   

   Copy

3. Run the interactive setup. It asks for the OpenProject URL and token, the four agent tokens, the model and the provider key, and writes .env. Re-running is safe:

   ./agent-init.sh
   

   Copy

4. Add the GitHub token(s) to .env — the setup script does not ask for them:

   GH_TOKEN=github_pat_...
   # optional, see "Branch protection" below
   GH_TOKEN_REVIEWER=github_pat_...
   GIT_REVIEWER_NAME=...
   GIT_REVIEWER_EMAIL=...
   

   Copy

5. Start it and watch the log:

   docker compose up -d
   docker compose logs -f engine
   

   Copy

6. After adding a project, or changing its GIT_REPO / AGENT values in OpenProject: docker compose restart engine. After editing .env: docker compose up -d engine — restart keeps the old environment.

Pin a release in .env instead of tracking latest:

OP_AGENT_ENGINE_TAG=0.2.5

⁠Required environment variables

Everything else — concurrency, timings, status names, paths, git identity — has a working default. The full list, including limits and the llama.cpp provider, is in docs/CONFIG.md⁠.

Each monitored project needs a project attribute named GIT_REPO holding its GitHub repository (owner/name or a github.com URL).

⁠The agent team

Fixed in the image, one OpenProject account and one token each:

⁠How a ticket flows

On Hold is terminal until a human moves the ticket. Branches are op-<project>-<wp>, one per ticket. At most MAX_RUNS_PER_AGENT runs per agent (default 1). Every engine comment starts with ENGINE:.

⁠Branch protection

If your repository requires an approving review from an account other than the pull request's author, give codeReviewer its own GitHub account and set GH_TOKEN_REVIEWER. The reviewer then switches gh/git to that account and can submit an approving review before merging. With a single GH_TOKEN, every agent is the same account, cannot approve its own PR, and merges stall.

If reviewers are also required for specific paths, list both the human and the reviewer account in .github/CODEOWNERS — an owner that is also the PR author can never satisfy the requirement.

⁠What is in the container

Runs as uid 10001 (agent). Nothing is mounted from the host: settings and credentials are environment variables, and all state lives in volumes. Provider credentials are never written to credential files by the image.

⁠Dashboard

The compose stack also starts a read-only dashboard on http://127.0.0.1:8765 (loopback only). It has no authentication — keep it on loopback or put it behind your own reverse proxy. Details: docs/DASHBOARD.md⁠.

⁠Documentation

⁠License

MIT. See LICENSE⁠.