--- title: Configuration description: Every Foreman environment variable, the MODELS map, and the session budget, with what each knob controls. type: reference summary: Environment variables, the MODELS map, storage auth, and the session budget. related: - /docs/getting-started - /docs/stations - /docs/customization --- # Configuration Foreman's configuration is a small set of environment variables plus two files: `agent/lib/models.ts` for model assignments and `agent/agent.ts` for the session budget. Everything else is discovered from the filesystem under `agent/`. ## Environment variables | Variable | Required | Default | What it does | | ----------------------- | ----------------------- | ------------------------------- | -------------------------------------------------- | | `FACTORY_REPO` | Yes | none | The `owner/repo` the factory works on. | | `GITHUB_CONNECTOR` | Yes (set during deploy) | `github/foreman-agent` | Connect connector UID for the GitHub App. | | `LINEAR_CONNECTOR` | Yes (set during deploy) | none | Connect connector UID for Linear. | | `FACTORY_LABEL` | No | `factory` | The issue label that triggers an unattended run. | | `FACTORY_BRANCH_PREFIX` | No | `factory/` | Marks the factory's own branches. | | `FACTORY_SETUP_COMMAND` | No | none | Runs in the station clone once per template build. | | `FACTORY_BOT_NAME` | No | GitHub App slug, else `Foreman` | The `@mention` name. | | `GITHUB_APP_SLUG` | No | none | Second override for the bot name. | Reads live in `agent/lib/constants.ts`, `agent/lib/github/credentials.ts`, `agent/lib/github/bot-name.ts`, and `agent/lib/github/repo-sandbox.ts`. `FACTORY_REPO` is read with `requireEnv` at module load and validated as exactly one `owner/repo` pair, so a missing or malformed value fails the build instead of surfacing mid-request. It feeds the GitHub extension's default context, the station clones, the push URL, the injected system prompt, and the factory-brain key. `GITHUB_CONNECTOR` serves the channel, the `github__*` tools, and the brokered git credential from one connector. The default points at the template's own connector. `LINEAR_CONNECTOR` is app-scoped with `read`, `write`, `issues:create`, and `comments:create` scopes. `requireEnv` inside `linearAuth` throws at module load when it is missing, so discovery fails without it even though the channel alone has a fallback. `FACTORY_LABEL` names the label that starts an unattended run. Applying it to an issue hands that issue to the full pipeline with nobody watching. The same value is built into the instructions the run receives, so changing the label takes no second edit. `FACTORY_BRANCH_PREFIX` scopes the red-CI fix loop so pull requests people pushed are never touched. See the caveat below before overriding it. `FACTORY_SETUP_COMMAND`, for example `pnpm install`, runs inside the station sandboxes' clone once per template build, and a failure there fails the build rather than a session. It is also part of the sandbox revalidation key, so changing it rebuilds the snapshot. `FACTORY_BOT_NAME` drives the channel's mention matching and stripping, the reply instructions on approval comments, and the git commit identity. When unset, the name resolves from the GitHub App's slug through the connector, falling back to `Foreman`. `GITHUB_APP_SLUG` is a second override, checked after `FACTORY_BOT_NAME`. ### Deliberately not environment-configured Vercel Blob and the AI Gateway both authenticate with the project's Vercel OIDC token. There is no `BLOB_READ_WRITE_TOKEN` and no provider API key to set or rotate. Locally, `vercel env pull` supplies a short-lived OIDC token, which is what makes Connect, Blob, and the station sandboxes work in the `pnpm dev` TUI. ## Models Every model assignment lives in one map, `MODELS` in `agent/lib/models.ts`, as Vercel AI Gateway ids in `/` form. Each agent's `agent.ts` reads its entry rather than hardcoding a string, so swapping a model is a one-line edit and no provider SDK is wired in anywhere. | Agent | Model | | ------------ | -------------------------------------------------------------------- | | Orchestrator | `openai/gpt-5.6-terra-fast` | | Classifier | `openai/gpt-5.6-terra-fast` | | Analyst | `openai/gpt-5.6-terra-fast` | | Implementer | `anthropic/claude-fable-5` | | Reviewer | `openai/gpt-5.6-terra-fast` | | Researcher | `openai/gpt-5.6-terra-fast` | | Eval judge | `google/gemini-3.6-flash`, set separately in `evals/evals.config.ts` | One split in the map is deliberate. The Implementer runs the strongest coding model, and the Reviewer runs a different vendor on purpose, because a different vendor does not share the Implementer's idiom or blind spots. That is what makes the review verdict independent. If you swap either model, keep the two on different vendors. ## Session budget The root runtime in `agent/agent.ts` sets two limits. `compaction.thresholdPercent` has the conversation compacted once it reaches 75% of the context window. `limits.maxOutputTokensPerSession` is `100_000`. The four stations draw from the root session's remaining quota, so the cap is sized for a full pipeline run rather than a chat reply. It exists to stop runaway sessions, not to squeeze normal ones. ## The FACTORY\_BRANCH\_PREFIX caveat The Implementer's station instructions describe the `factory/-` branch naming as prose, with the default prefix written into the text. Overriding `FACTORY_BRANCH_PREFIX` changes what the red-CI loop recognizes as a factory branch, but not what the Implementer is told to name its branches. Edit `agent/subagents/implementer/instructions.md` to match, or new branches fall outside the fix loop's scope. Working in the template repository with a coding agent? This prompt changes the prefix in both places at once. Change Foreman's branch prefix. 1. Ask me for the new prefix (the current default is `factory/`). 2. Update the branch naming in `agent/subagents/implementer/instructions.md` to use it. 3. Tell me to set `FACTORY_BRANCH_PREFIX` to the same value in the Vercel project's environment variables. 4. Run `pnpm validate` and confirm it reports 0 errors and 0 warnings. ## Next steps --- For a semantic overview of all documentation, see [/sitemap.md](/sitemap.md) For an index of all available documentation, see [/llms.txt](/llms.txt) For agent-facing discovery, including API and MCP surfaces, see [/agents.md](/agents.md)