Config file · Scout

Every key in scout.config.json in one place — baseUrl, model, engine, profiles, recordVideo, videoSpeed — plus the environment variables that override them at run time.

scout.config.json lives at your project root and is created by scout init. It holds the few things Scout needs that aren’t a scenario: where your app runs, which model to verify with, and the auth profiles your flows use.

// scout.config.json
{
  "baseUrl": "http://localhost:3000",
  "model": "claude-sonnet-4-6",
  "engine": "agent-sdk",
  "recordVideo": false,
  "videoSpeed": 0.35,
  "defaultViewport": "mobile",
  "viewports": {
    "wide": { "width": 1920, "height": 1080 },
    "phone-xl": { "device": "iPhone 13", "width": 414 }
  },
  "profiles": {
    "anon": { "description": "Logged-out session" },
    "subscriber": {
      "description": "User with active subscription",
      "env": ["QA_SUB_EMAIL", "QA_SUB_PASSWORD"]
    }
  }
}

Keys

Key	Type	Default	What it does
`baseUrl`	string	—	The URL every scenario is relative to. Overridable per run (see precedence below).
`model`	string	`claude-sonnet-4-6`	The model used for verification and healing. Scout infers the provider and engine from it — see Providers & credentials.
`engine`	`"agent-sdk"` \| `"ai-sdk"`	inferred	Forces the run engine. Anthropic defaults to `agent-sdk`; Google/OpenAI use `ai-sdk`. Usually best left unset.
`recordVideo`	boolean	`false`	When `true`, a verified scenario also produces a paced demo MP4 (enable per-run with `--demo-video`). Needs `ffmpeg`. See Run artifacts.
`videoSpeed`	number `(0,1]`	`0.35`	Playback pacing for the demo video. `0.35` is slower (easier to watch); `1` is natural speed.
`defaultViewport`	string	`mobile`	The viewport a scenario runs in when it declares none. Must name a built-in or a `viewports` entry.
`viewports`	object	—	Named viewports, merged over the built-ins `mobile`/`desktop`/`tablet` (a same-named entry overrides one). Each value is a Playwright `device` preset and/or explicit fields (`width`, `height`, `deviceScaleFactor`, `isMobile`, `hasTouch`, `userAgent`) — they compose. Names are limited to `[a-z0-9-]`. See Viewports.
`testIdAttribute`	string	`data-testid`	The attribute the selector ladder prefers when recording a stable handle for each interaction. Set it to `data-test`, `data-qa`, … if your app uses a different convention — the ladder reads it and `getByTestId` resolves it on replay.
`profiles`	object	—	Named auth profiles. Each has a `description` and an optional `env` array naming the env vars its login needs. See Auth profiles & secrets.

Environment overrides

Some keys can be overridden at run time without editing the file — handy for CI and parallel worktrees:

Variable	Overrides	Notes
`SCOUT_BASE_URL`	`baseUrl`	Precedence: `--base-url` flag > `SCOUT_BASE_URL` > config.
`SCOUT_ENGINE`	`engine`	`agent-sdk` or `ai-sdk`. Note: `ai-sdk` can’t reuse a Claude Code session — Anthropic then needs `ANTHROPIC_API_KEY`.
`SCOUT_RECORD_VIDEO`	`recordVideo`	Set to `1` to enable the demo video for one run.
`SCOUT_VIEWPORT`	—	Forces every scenario into this one viewport for the run (ad-hoc; mirrors `scout go --viewport`). Must exist in the registry; the run never persists a script.
`FFMPEG_PATH`	—	Path to `ffmpeg` if it isn’t on `PATH`.
`SCOUT_VIDEO_FONT`	—	Path to a `.ttf` for the burned-in video captions (otherwise autodetected).

Never put a literal secret in the config. Application secrets belong in profiles.<name>.env and $ENV: placeholders — see Auth profiles & secrets.