Configuration file
kaloko.config.yml sits in the root of the repository and tells the CLI where your flows run. kaloko init writes a commented one; kaloko doctor checks it. Its format is qawalk.config.v1, and schema, org and environments are required.
schema: qawalk.config.v1
org: acme
project: shop
scenarios: [qa/flows/*.yml]
environments:
local:
base_url: http://localhost:3000
staging:
base_url: https://staging.acme.test
access:
basic: { user_env: STAGING_USER, password_env: STAGING_PASSWORD }
accounts:
member: { user: qa@acme.test, password_env: MEMBER_PASSWORD }
production:
base_url: https://acme.com
readonly: true
blocked_paths: ["/account/**"]
walk:
browsers: [chromium]
share:
expires_days: 30Top-level keys
| Key | What it holds |
|---|---|
schema | always qawalk.config.v1 |
org | the organization's slug on kaloko.app |
project | the Kaloko project for runs; default: the repository's name |
scenarios | glob patterns of scenario files |
output | the run folder (default tmp/kaloko) |
environments | where flows run (below) |
browser | channel (a Playwright channel such as chrome; empty = the bundled Chromium) and port of the shared browser (default 9333) |
walk | defaults for every run: concurrency (languages at once, 1–16), browsers, color_schemes, reduced_motion, forced_colors, display_modes |
capture | defaults for every scenario: record, trace |
evaluators | the semantic evaluator jev and the vision evaluator (below) |
share | url (default https://kaloko.app), token_env (default KALOKO_TOKEN), expires_days (default 30) |
docs | changelog and docs settings (below) |
products | what you release and version as a whole (below) |
Environments
Each key under environments is a name you use with kaloko start --env.
| Key | What it holds |
|---|---|
kind | app (default) or design (a folder of live HTML steps) |
base_url | the address, or one per language with a default fallback; ${VAR} is filled from the environment (review apps) |
readonly | true for production: the CLI only reads, never signs in to back offices, never creates data |
blocked_paths | path globs a read-only run never opens |
allowed_post_paths | path globs a read-only run may still POST to (a cart) |
may_create_data | false forbids creating data (default true) |
access | protection in front of the whole environment: basic (user_env, password_env), headers (service tokens), client_certificate, origins that receive them |
accounts | people who sign in, keyed like the scenario's account: user or user_env, password_env, totp_env, storage_state (a sign-in saved by kaloko auth save) |
mail | the mailbox: provider (mailpit, script, none), url, user_env, password_env, address, script, options, auth |
app | the app under test per platform: android, ios, electron, desktop, windows |
serve, fixtures, tokens_mode | design environments: the folder of steps, JSON fixtures, the token mode |
html_view | experimental: keep a static HTML view of every capture |
Evaluators
| Key | What it holds |
|---|---|
evaluators.jev.api_key_env | the variable with your own evaluator key (default TYPESAFE_API_KEY) |
evaluators.jev.hosted | without a local key, evaluate through your plan's allowance (default true); false uses only your key |
evaluators.jev.thresholds | pass and fail scores |
evaluators.jev.model, base_url, max_state_chars, signals, concurrency | finer settings, rarely needed |
evaluators.vision | the second evaluator that looks at the screenshot (provider anthropic, key in ANTHROPIC_API_KEY); false turns it off |
Docs and products
| Key | What it holds |
|---|---|
docs.dir | docs sources (default docs) |
docs.changelog | the changelog file (default CHANGELOG.md) |
docs.style | keep-a-changelog or release-notes |
docs.version_source | auto, git-tag, package.json, release-please, changesets, semantic-release, pyproject, cargo, gemspec, manual |
docs.languages | languages of the docs; the first is the originals' |
docs.framework | auto, docusaurus, vitepress, mkdocs, nextra, plain |
docs.publish | who reads: members, domain or public (the last two need an admin) |
docs.images | viewport and locale (reader or a language) of the pictures |
products.<slug> | name (text or per language), version (source, path, pattern), docs, project or projects, modules, reference_env, default_scenario, publish |
Without products, the project is the product.
Secrets
Secrets never go into the config. Wherever one is needed, the config names an environment variable (password_env: STAGING_PASSWORD, { env: CF_ACCESS_CLIENT_SECRET }). Kaloko reads the value from:
- the environment of the process,
.envnext tokaloko.config.yml,~/.config/kaloko/.env.
A variable already set wins over the files. Values are removed from captured HTML, page text and console output. kaloko doctor says which named variables are missing. The token for sharing is KALOKO_TOKEN unless share.token_env says otherwise; see Roles and tokens.
Kaloko · latest · 2026-10-06