Configuration

Configuration

Repo Steward is configured by flags and a few environment variables. Nothing is read from the target repository, because repository content is untrusted; a repository cannot change validation commands, policy, or limits.

Data directory

Default: $XDG_DATA_HOME/repo-steward or ~/.local/share/repo-steward. Override with -data-dir. It must be on a local filesystem, and with a VM-backed engine it must be under a path the engine shares.

steward.db                    runs, steps, approvals, model calls, events, tasks, promotions,
                              validation records, proposals, publication operations
executor.lock                 one executing run per data directory
snapshots/<tree>              base-tree snapshots made by inspect
runs/<id>/work                scratch clone (working tree)
runs/<id>/gitdir              its Git directory, kept outside the tree
runs/<id>/snapshots/<tree>    materialized candidate trees
runs/<id>/staging/<id>        manifest staging copies
runs/<id>/gocache-<nonce>     a new, empty build cache for every validation, removed at the end of the run
runs/<id>/run.lock            per-run lock
cache/mod/<module>            module cache per target module path
tools/govulncheck-<version>-<image digest>/
                              the vulnerability scanner built for that image, with its sha256 and build record
vulndb/vulndb-<modified>-<hash>/
                              a fetched vulnerability database snapshot, named by its content

Upgrading across agent-runtime v0.5.0 migrates steward.db on its first open (migration 6 chains the audit events). Stop every older repo-steward process and agentrt binary before that first open: an older binary's events would carry no hash, and a v0.4.0 binary refuses a migrated database.

The data directory is created owner-only (0700). One that group or others can only read or enter is tightened to 0700; one they can write, or that another account owns, is refused with a message naming the path, its mode, and the fix. The build cache and staging roots are owner-only too; the engine resolves the bind mounts itself, so containers still reach the caches below. Verified for the modes, and the mount below an owner-only parent on colima only; native Linux Docker is covered by CI's integration job, which had not yet run this change.

The module cache is written by the Go toolchain with read-only permissions. To delete a data directory, restore write permission first. The scanner and database directories are named by content and never deleted and recreated within a run; a scanner directory that fails verification is left for you to remove.

Dependency policy

Flag	Default	Effect
-allow-major	off	majors become eligible
-dependency MODULE[@VERSION]	none	only this module, or only this exact version of it, is eligible; selection is skipped; an older pin yields no candidate

Pre-release and pseudo-versions are never eligible. Minor and patch upgrades are eligible by default.

Flag	Default	Effect
-min-age DURATION	72h	version cooldown on maintain and inspect: a version published less than this long ago, or with no known publish time, is ineligible with the reason; 0 disables it. This changed behaviour from releases before it. In -select vulnerable it is waived for the version that clears an advisory, and the result (cooldown_waived) and the proposal say so

Vulnerability options: -select smallest|vulnerable (baseline mode only), -vulndb DIR, and -scan-timeout (default 10 minutes). The scanner versions are pinned in the tool per Go minor, like the toolchain images. See Vulnerabilities: Reporting and Fixing.

Scope limits

Flag	Default
-scope-files-soft	10
-scope-files-hard	20
-scope-lines-soft	200
-scope-lines-hard	400

Scope counts changed source files and lines against the base commit, computed on the projected result before a write lands. Manifests are exempt; the manifest rules bound them instead. Crossing a soft limit pauses for one expansion approval; crossing a hard limit ends the run.

Run limits

Set by mode. Model mode defaults: 40 steps, 80 model calls including retries, 2048 output tokens requested per call (the runtime's per-call limit is 4096), two million total tokens, a loop threshold of three identical call-and-result pairs, three consecutive failed steps. -max-model-calls overrides the call cap. Repair budgets: eight validation cycles, and three consecutive validations with the same introduced findings.

Validation

-check-timeout (default 10 minutes) bounds each of build, vet, and test. Every validation gets its own new build cache, so a later validation does not reuse what an earlier one compiled; measured on 2026-10-03 on colima, TestBaseline_PatchSafeProducesVerifiedProposal went from a median of 6.0 seconds (nine runs) to 9.3 (six runs). The checks are the toolchain's own; custom commands are not read from the repository.

Toolchain images

The image that validates a repository is chosen from its go directive and pinned by digest in the tool. A repository whose directive is outside the table is refused.

Go	Image
1.22	golang:1.22-bookworm
1.23	golang:1.23-bookworm
1.24	golang:1.24-bookworm
1.25	golang:1.25-bookworm
1.26	golang:1.26-bookworm
1.27	golang:1.27-bookworm

Digests are in internal/toolchain/toolchain.go. GOTOOLCHAIN=local is set in every container, so a dependency that needs a newer Go than the image provides fails at go get and the run reports requires_newer_toolchain.

Environment variables

Variable	Use
GITHUB_TOKEN	API and push credential when -publish is set; read at maintain and resume, never stored
OLLAMA_HOST	Ollama server address; default 127.0.0.1:11434
ANTHROPIC_API_KEY or CLAUDE_KEY	key for the paid provider; read at maintain, resume, and bench run, never stored
DOCKER_HOST	engine socket as unix:///path; otherwise well-known local sockets are tried
XDG_DATA_HOME	data directory root

Protected paths

Never written by the agent, whatever the policy: **/*_test.go, **/testdata/**, .github/**, .gitlab-ci.yml, .circleci/**, Jenkinsfile, .repo-steward/**, SECURITY.md, go.mod, go.sum, go.work, go.work.sum, vendor/**, .gitignore, .gitattributes, .gitmodules. Manifests change only through the dependency tools.