Configuration

Bugmole reads .bugmole/config.yaml, which bugmole init writes. It also reads bugmole.config.yaml at the project root when there's no .bugmole/config.yaml, and --config <path> or BUGMOLE_CONFIG points it at another file. Environment substitutions use ${NAME:-default}.

Runtime

runtime:
  env: sandbox
  workspace_id: default
  artifacts_dir: ./qa/bugmole-runs
  spec_dir: ./spec

env is one of sandbox, test, staging or production. Use sandbox for isolated data. When env is missing or not one of those, Bugmole treats the environment as staging and doesn't perform destructive actions.

Your own AI model

The llm block is optional, and bugmole init doesn't write one. Without it, AI work such as explaining a failure uses Bugmole AI and spends AI credits. Add your own model to use it instead, at no credit cost:

llm:
  provider: anthropic        # openai, anthropic or ollama
  api_key: ${LLM_API_KEY}
  model: ${LLM_MODEL:-claude-sonnet-5}
  base_url: ${LLM_BASE_URL}  # optional: an OpenAI-compatible gateway, or your Ollama address

provider is openai, anthropic or ollama.
api_key is required for openai and anthropic; a local ollama model needs none.
model defaults to claude-sonnet-5 for Anthropic and gpt-4o-mini otherwise.

Put the key in .bugmole.env as LLM_API_KEY, not in the config file. Do not put provider keys in flows, manifests, logs or anything you share. To give flows a password or token, see Credentials.

MCP

mcp:
  enabled: true
  host: 127.0.0.1
  port: 3187

Keep the MCP server on loopback for local project execution unless you have explicitly secured the deployment boundary.

Browser execution

execution:
  playwright:
    base_url: http://localhost:3010
    headless: true
    browsers: [chromium, firefox, webkit, msedge]
    devices: ["iPhone 15", "Pixel 7"]
    parallel: 4
  retries:
    step: 2
    journey: 1

base_url is the app's address, written into each plan you make (see Which URL a run hits). To run against another address, change it here or pass --base-url. PLAYWRIGHT_BASE_URL only matters when you run bugmole init: like --app-url, it tells init the app's URL. Retries are for transient failures; they must not turn invariant, permission, or destructive-action failures into passes.

Browsers and devices

A web run executes once per target, and targets run in parallel:

browsers — any of chromium (Chrome), firefox, webkit (Safari), and msedge (Edge). Each runs at desktop size. Defaults to [chromium].
devices — Playwright device names such as iPhone 15 or Pixel 7. Each device is emulated on the engine it ships with: WebKit for Apple devices, Chromium for the rest.
parallel — how many targets run at once. Defaults to the number of targets, up to 4. BUGMOLE_TARGET_CONCURRENCY overrides it.

A run passes only when every target that ran passed. A target whose browser isn't installed is reported as blocked with the install command, and doesn't fail the others. Firefox can't emulate mobile devices, so that pairing is reported as blocked too.

Choosing browsers and devices in the dashboard's Run tests control, or passing --browsers and --devices to the CLI, overrides the configuration for that run.

Which URL a run hits

The environment selected for the run (dashboard), or --base-url (CLI). Absolute URLs in the flow are moved onto this origin, keeping their paths, so a flow recorded against staging runs against the environment you picked.
The plan's target base_url.
The flow's own url: header.

Secrets in flows

Flows reference passwords and other secrets as {{secret.NAME}} in inputText. Bugmole reads them from BUGMOLE_FLOW_SECRET_NAME on the machine running the flow; no other environment variable is readable from a flow. Typed text is masked in playwright.log and step results, and a secret's value is replaced with [secret] in logs, results, manifests and everything a worker reports. A secret typed into a plain text field (not a password field) has that field's text hidden on screen, so it doesn't show in screenshots or the video. A flow that types a secret records no Playwright trace, because a trace keeps every typed character, and neither does a flow that starts from a saved signed-in session, because a trace would hold its cookies. See Sample tests.

Bugmole Cloud runs have no environment of yours to read, so their secrets are stored in the project instead: see Sign-in for runs. Your own workers (bugmole serve, CI) never receive those stored values and keep reading BUGMOLE_FLOW_SECRET_NAME.

Machine credentials

The CLI reads its machine identity from .bugmole.env:

BUGMOLE_REGISTRY_URL=https://api.bugmole.com
BUGMOLE_API_KEY=bm_live_...
BUGMOLE_AEGIS_EMAIL=you@example.com

BUGMOLE_REGISTRY_URL is the address of Bugmole's server.
BUGMOLE_API_KEY is this machine's API key.
BUGMOLE_AEGIS_EMAIL is the email you sign in with. Bugmole only uses it to fill in the next sign-in for you; it isn't a credential.

API keys are bearer credentials. Store them locally as secrets, scope them to the required project and permissions, and never publish their plaintext in documentation or logs.