gbr-games/BUILDER.md

AI builder (gbrgames worker)

The panel's AI builder (Admin → Games → AI Config Generator) is run by a worker we host ourselves. The panel only keeps a queue; every result is a pull request to this repo, which CI validates and boot-tests like any other.

Panel                                     Builder worker (gbrgames worker, Docker)
─────                                     ─────────────────────────────────────────
admin starts a job ──► queued    ◄─poll── research: web search + page reader + model
progress / log / variants        ◄─post── build: first boot → draft → boot with the node-agent
"Review draft PR"                         → branch draft/<id>-<job> + PR as the bot ──► CI (validate + boot test)

1. Research (gbrgames research -name N): searches the web, reads the best pages, and has the model list the server's variants (edition, image or SteamCMD app, startup, ports). Every image and Steam app is checked for real (docker manifest inspect, anonymous steamcmd +app_info_print) before the admin sees it.
2. The admin picks a variant in the panel.
3. Build (gbrgames build -name N -variant @v.json): first boot of the image untouched (first-boot), a draft by the model (draft, rules in AUTHORING.md), then the draft is deployed with the node-agent's BootTest, the same check CI runs. Failures (crash, error lines, saves written outside /server) go back to the model, three boots at most.
4. The worker pushes games/<id>/ to a branch and opens a pull request as the bot account. A draft that validates but never booted still gets a PR, titled WIP:, with what's left listed. Nothing reaches players until a person merges it and enables the game.

The worker only connects out (to the panel, Gitea, the model and the search services).

Requirements

A Docker host with the isolated gbr-boottest network (RUNNER.md, step 1), so servers booted by the builder can't reach private networks. Enough memory for the largest server it builds (~16 GB for ARK) and disk for SteamCMD downloads. The image gbr-builder:latest is published by .gitea/workflows/builder-image.yml whenever cmd/ changes on main.

Configuration

All through environment variables; nothing about where it runs lives in this repo.

Variable	What
PANEL_URL	The panel the worker takes jobs from
BUILDER_TOKEN	Shared secret the panel checks on /api/v1/builder/** (same value in the panel's env)
GITEA_TOKEN	The bot account's token (repository read/write; the account needs Write on this repo): pushes draft branches, opens PRs as that account. Checked when the worker starts
OLLAMA_URL	Ollama for the model (or MODEL_PROVIDER=gemini with GEMINI_API_KEY)
SEARXNG_URL, READER_URL	A SearXNG instance (JSON API) and a page-to-text reader (READER_URL/<page url>)
MODEL, POLL_INTERVAL, WORKER_NAME, WORK_DIR	Optional: model name, poll interval (20s), name shown in the panel, work folder

Running a build by hand

On any machine with Docker and the gbr-boottest network, with OLLAMA_URL, SEARXNG_URL and READER_URL set:

go run ./cmd/gbrgames research -name Valheim -out research.json
# pick a variant from research.json into v.json, then:
go run ./cmd/gbrgames build -name Valheim -variant @v.json -out build.json

The draft lands in games/<id>/, first-boot reports in firstboot-out/.