> ## Documentation Index
> Fetch the complete documentation index at: https://momentic.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# momentic.config.yaml

> Index for `momentic.config.yaml`. Project-level options live here; large blocks like `browser`, `ai`, and `emulator` have their own reference pages.

`momentic.config.yaml` lives in your project root and defines a **project**. One
file covers both web and mobile.

Paths and globs are relative to the file's location, or absolute.

## Configuration sources

Momentic resolves configuration from these sources, highest precedence first:

1. **CLI flags** (e.g. `--local-avd-id`, `--local-apk-path`)
2. **Environment variables**, including `MOMENTIC_API_KEY` and any variable
   interpolated into `momentic.config.yaml`
3. **`momentic.config.yaml`** (this file). Includes the
   [`ai.classification`](/configuration/ai#ai-classification) toggle for failure
   classification.
4. **Organization AI settings**. Failure categories and auto-heal behavior are
   configured in the
   [Momentic dashboard](https://app.momentic.ai/settings/healing) and applied
   when the CLI is authenticated. These remain dashboard-managed and cannot be
   set in this file.
5. **CLI defaults**

## Example

```yaml momentic.config.yaml theme={null}
# Project identity and test discovery
name: my-project
include:
  - "**/*.test.yaml"
  - "**/*.module.yaml"
exclude:
  - "out/**/*"

# Run behavior
retries: 2
parallel: 4
recordVideo: on-fail

# One entry per environment, each with its own baseUrl and variables
environments:
  - name: dev
    baseUrl: https://dev.example.com
    envVariables:
      USERNAME: devUser
      PASSWORD: ${DEV_PASSWORD}
  - name: production
    baseUrl: https://www.example.com
    envVariables:
      USERNAME: prodUser
      PASSWORD: ${PROD_PASSWORD}

# Browser defaults applied to every browser-based test
browser:
  defaultBrowserType: Chromium
  smartWaitingTimeoutMs: 5000
  pageLoadTimeoutMs: 8000

# AI agent versions and per-agent behavior
ai:
  classification: true
  useMemory: true
  failureRecovery: true
  agentConfig:
    locator: v4
    assertion: v4
    visual-assertion: v4
    text-extraction: v3

# Mobile emulator settings (remote-hosted)
emulator:
  region: us-west1
```

## Reference

<CardGroup cols={2}>
  <Card title="Global options" icon="gear" href="#global-options">
    Project name, file globs, retries, parallelism, video recording, Git branch
    settings.
  </Card>

  <Card title="Environments" icon="layer-group" href="/configuration/environments">
    `environments[]`: name, base URL, env variables, per-env proxy.
  </Card>

  <Card title="Environment variables" icon="terminal" href="/configuration/environment-variables">
    How Momentic resolves variables at runtime and the reserved variables
    available in every test.
  </Card>

  <Card title="Browser" icon="window" href="/configuration/browser">
    `browser.*`: defaults for browser type, timezone, timeouts, locator
    behavior, AI context filtering.
  </Card>

  <Card title="AI" icon="microchip" href="/configuration/ai">
    `ai.*`: per-agent versions, memory, and failure recovery.
  </Card>

  <Card title="Mobile" icon="mobile" href="/configuration/mobile">
    `emulator.*`: region and runtime options for remote-hosted mobile emulators.
  </Card>

  <Card title="Advanced" icon="flask" href="/configuration/advanced">
    `advanced.*`: Faker seed, per-environment cache isolation.
  </Card>

  <Card title="Workspaces" icon="folder-tree" href="/configuration/workspace">
    Group multiple projects under one repo.
  </Card>

  <Card title="Test file globs" icon="asterisk" href="/configuration/test-globs">
    Glob syntax for `include` / `exclude`.
  </Card>
</CardGroup>

## Global options

<ParamField path="name" type="string">
  Project name, displayed in reports and the dashboard.

  ```yaml momentic.config.yaml theme={null}
  name: my-project-name
  ```
</ParamField>

<ParamField path="include" type="string[]">
  Globs for test and module files to include. Matching files are picked up
  automatically when starting the Momentic Local App or running tests.

  ```yaml momentic.config.yaml theme={null}
  include:
    - "**/*.test.yaml"
    - "**/*.module.yaml"
  ```
</ParamField>

<ParamField path="exclude" type="string[]">
  Globs for files to exclude. `node_modules`, `.git`, and `.venv` are always
  excluded.

  ```yaml momentic.config.yaml theme={null}
  exclude:
    - "out/**/*"
  ```
</ParamField>

<ParamField path="retries" type="number">
  Default number of retries per test on failure. Overrides per-test `retries`.

  ```yaml momentic.config.yaml theme={null}
  retries: 2
  ```
</ParamField>

<ParamField path="parallel" type="number | &#x22;auto&#x22;">
  Default for `momentic run`: `1`. Tests to run in parallel.

  For `momentic run`, `"auto"` sizes workers from the host's CPU cores. When the
  project's `browser.remoteBrowser` flag is enabled, workers scale to
  `cores * 4 - 2` (remote browsers are IO-bound); otherwise workers cap at `cores`
  (local browsers are CPU-bound).

  For mobile projects (`momentic-mobile`), pass `AUTO` (CLI flag only, not in
  `momentic.config.yaml`) to run as many tests in parallel as the current shard
  contains. Combine with `--shard-index` / `--shard-count` so each shard saturates
  its capacity.

  In `momentic.config.yaml`, only the lowercase form `auto` is valid.

  ```yaml momentic.config.yaml theme={null}
  parallel: 4
  ```
</ParamField>

<ParamField path="recordVideo" type="boolean | &#x22;on-fail&#x22;">
  Record video for test runs. Default: `on-fail`.

  * `true`: record every run.
  * `false`: never record.
  * `on-fail`: record every run but keep video only for failures.

  Browser recording requires `ffmpeg` (`momentic install-browsers ffmpeg`); mobile
  recording does not.

  ```yaml momentic.config.yaml theme={null}
  recordVideo: on-fail
  ```
</ParamField>

<ParamField path="goldenFileDir" type="string">
  Directory Momentic writes golden files to for **Visual diff**.

  ```yaml momentic.config.yaml theme={null}
  goldenFileDir: golden/visual-diff
  ```
</ParamField>

<ParamField path="reporterDir" type="string">
  Default directory for reporter output.

  ```yaml momentic.config.yaml theme={null}
  reporterDir: reports
  ```
</ParamField>

<ParamField path="gitMainBranch" type="string">
  Main branch of the repo. When running tests on a new branch, Momentic seeds
  cache entries from the nearest commit on this branch. In non-CI
  environments, the main branch is also excluded from cache saving. See
  [cache saving eligibility](/reliability/step-cache#cache-saving-eligibility).

  ```yaml momentic.config.yaml theme={null}
  gitMainBranch: main
  ```
</ParamField>

<ParamField path="gitProtectedBranches" type="string[]">
  Branches considered ineligible for cache saving in non-CI environments.
  Prevents accidental cache overwriting on shared branches. See
  [cache saving eligibility](/reliability/step-cache#cache-saving-eligibility).

  ```yaml momentic.config.yaml theme={null}
  gitProtectedBranches:
    - staging
  ```
</ParamField>

<ParamField path="displayRoot" type="string">
  Relative path from the project root to use as the Repository root in the
  Momentic Local App. Display-only. Does not affect test execution or file
  resolution.

  ```yaml momentic.config.yaml theme={null}
  displayRoot: src/tests
  ```
</ParamField>