Configuration
This page describes where Veritas reads its configuration, every setting with its default and allowed values, and how the result cache works.
Example
.veritas/config.json needs only the settings that differ from the defaults:
{
"$schema": "https://veritas.invalid/schemas/config.json",
"schemaVersion": "1.0.0",
"project": { "packageManager": "pnpm", "tsconfig": "tsconfig.json" },
"analysis": {
"include": ["src/**/*.ts"],
"testInclude": ["test/**/*.test.ts"]
},
"formal": { "integerDomain": { "min": "-1000000", "max": "1000000" } },
"pbt": { "numRuns": 500 },
"policy": {
"confirmedViolation": "fail",
"inconclusiveBehavior": "fail",
"maxNewSurvivors": 0
},
"storage": { "retainRuns": 10 }
}analysis.includeandanalysis.testIncludeselect the source and test files.veritas initfills them in from what it detects.formal.integerDomainsets the integer range of formal checks. The bounds are decimal strings.policy.inconclusiveBehavior: "fail"makes inconclusive results end with exit code 4, which suits a CI gate.policy.maxNewSurvivors: 0fails the run when any mutant in scope survives.storage.retainRuns: 10keeps the ten most recent finished runs; runs still in progress are never removed.
Where configuration lives
Veritas reads .veritas/config.json in the project root. veritas init creates it. The file is validated against schemas/config.json; an unknown key or an invalid value fails with CONFIG_INVALID (exit code 2) and lists every invalid field.
You can write the configuration as code instead, in veritas.config.ts, veritas.config.mjs or veritas.config.js in the project root, with the same shape as its default export. Loading it runs project code, so Veritas loads it only with the global --allow-code-config option and otherwise fails with CONFIG_CODE_NOT_ALLOWED. A project may have only one configuration file (CONFIG_AMBIGUOUS otherwise), and a configuration file that is a symbolic link to a location outside the project is refused.
export default {
project: { packageManager: 'pnpm', tsconfig: 'tsconfig.json' },
analysis: { include: ['src/**/*.ts'], testInclude: ['test/**/*.test.ts'] },
policy: { inconclusiveBehavior: 'fail', maxNewSurvivors: 0 },
};Commit .veritas/config.json and .veritas/approvals.json; the GitHub Action needs the configuration in the repository. Keep .veritas/runs/ and .veritas/cache/ out of version control.
All settings
Every setting, with its type, default and allowed values, as validated by schemas/config.json. A setting whose allowed value is marked fixed accepts only that value. unset means the setting has no default value. Unknown keys are rejected.
Top level
| Setting | Type | Default | Allowed values |
|---|---|---|---|
$schema | string | unset | |
schemaVersion | string | "1.0.0" | only "1.0.0" (fixed) |
project
| Setting | Type | Default | Allowed values |
|---|---|---|---|
project.packageManager | string | "unknown" | pnpm, npm, yarn, bun, unknown |
project.tsconfig | string or null | null |
sources
| Setting | Type | Default | Allowed values |
|---|---|---|---|
sources.local | boolean | true | |
sources.github.enabled | boolean | false | |
sources.github.repo | string | unset | matches ^[A-Za-z0-9](?:[A-Za-z0-9-]{0,38})\/(?!\.\.?$)[A-Za-z0-9._-]{1,100}$ |
sources.web.enabled | boolean | false | |
sources.web.allowDomains | array of string | [] | items match ^[a-z0-9.-]+$ |
sources.web.maxPages | integer | 30 | > 0, <= 1000 |
sources.web.maxDepth | integer | 1 | >= 0, <= 5 |
sources.web.maxChars | integer | 200000 | > 0 |
sources.web.timeoutMs | integer | 30000 | > 0 |
sources.web.maxDurationMs | integer | 120000 | > 0 |
sources.sendFullTextToLlm | boolean | false |
analysis
| Setting | Type | Default | Allowed values |
|---|---|---|---|
analysis.include | array of string (at least 1) | ["src/**/*.{ts,tsx,js,mjs}"] | |
analysis.exclude | array of string | ["**/*.generated.*","**/node_modules/**","**/dist/**"] | |
analysis.testInclude | array of string | ["**/*.{test,spec}.{ts,tsx,js,mjs}"] | |
analysis.testFramework | string | "vitest" | only "vitest" (fixed) |
analysis.inferSpecsFromCode | boolean | true | |
analysis.requireApprovalForNormativeClaims | boolean | true | only true (fixed) |
mutation
| Setting | Type | Default | Allowed values |
|---|---|---|---|
mutation.backend | string | "mizchi" | only "mizchi" (fixed) |
mutation.mode | string | "diff" | diff, full |
mutation.timeoutMs | integer | 120000 | > 0 |
pbt
| Setting | Type | Default | Allowed values |
|---|---|---|---|
pbt.numRuns | integer | 1000 | > 0, <= 1000000 |
pbt.seed | integer | unset |
formal
| Setting | Type | Default | Allowed values |
|---|---|---|---|
formal.backend | string | "z3" | z3, lean |
formal.integerDomain.min | string | "-10000" | matches ^-?\d+$ |
formal.integerDomain.max | string | "10000" | matches ^-?\d+$ |
formal.maxSolverMs | integer | 30000 | > 0 |
formal.maxArrayLength | integer | 3 | >= 1, <= 8 |
formal.rejectUnsupportedSemantics | boolean | true | only true (fixed) |
llm
| Setting | Type | Default | Allowed values |
|---|---|---|---|
llm.provider | string | "none" | none, claude, claude-code, openai, codex |
llm.model | string | unset | |
llm.maxTokensPerRun | integer | 200000 | >= 0 |
llm.allowCodexFileReads | boolean | false |
improvement
| Setting | Type | Default | Allowed values |
|---|---|---|---|
improvement.autoApply | boolean | false | only false (fixed) |
improvement.testFilesOnly | boolean | true | only true (fixed) |
improvement.maxIterations | integer | 3 | > 0, <= 20 |
improvement.maxPatchFiles | integer | 5 | > 0, <= 50 |
reports
| Setting | Type | Default | Allowed values |
|---|---|---|---|
reports.formats | array of string | ["json","markdown","html","sarif"] | text, json, markdown, html, sarif |
policy
| Setting | Type | Default | Allowed values |
|---|---|---|---|
policy.confirmedViolation | string | "fail" | fail, warn |
policy.inconclusiveBehavior | string | "warn" | fail, warn, ignore |
policy.maxNewSurvivors | integer | unset | >= 0 |
policy.minPropertyCoverage | number | unset | >= 0, <= 1 |
sandbox
| Setting | Type | Default | Allowed values |
|---|---|---|---|
sandbox.allowNetworkWithoutIsolation | boolean | false |
storage
| Setting | Type | Default | Allowed values |
|---|---|---|---|
storage.retainRuns | integer | 20 | > 0 |
storage.storePrompts | boolean | false | only false (fixed) |
cache
| Setting | Type | Default | Allowed values |
|---|---|---|---|
cache.enabled | boolean | true |
limits
| Setting | Type | Default | Allowed values |
|---|---|---|---|
limits.memoryMb | integer | 2048 | >= 256, <= 65536 |
What the main settings do
| Setting | Default | Effect |
|---|---|---|
sources.web.enabled, sources.github.enabled | false | Collect evidence from the web or from GitHub. The web source also needs allowDomains; the GitHub source reads sources.github.repo (owner/name). Neither runs with --offline |
sources.web.maxPages, maxDepth, maxChars, timeoutMs, maxDurationMs | 30, 1, 200000, 30000, 120000 | Limits of the web crawl: pages, link depth, characters kept, time per page, and time for the whole crawl. Pages not fetched in time are reported as skipped |
analysis.inferSpecsFromCode | true | Propose candidate properties inferred from the code. With false, only documented sources produce properties |
mutation.mode | diff | diff: you are expected to pass --since; without it, all mutants in scope run and the stage messages say so. full: all mutants in scope run, without that message. In both modes, --since limits mutants to changed code |
formal.integerDomain | -10000 to 10000 | Integer range of formal checks, within the safe-integer range |
formal.maxSolverMs | 30000 | Solver time limit per query |
formal.maxArrayLength | 3 | Longest array (1 to 8) that formal checks cover; longer arrays are not covered |
pbt.numRuns, pbt.seed | 1000, per property | Number of property-based test runs, and the seed. Without seed, each property gets a fixed seed derived from its id, so results are reproducible |
llm.provider | none | LLM used to read free-text statements; see LLM providers. llm.maxTokensPerRun limits the tokens of one run |
policy.confirmedViolation | fail | fail: a confirmed violation ends with exit code 1. warn: it is reported as a warning |
policy.inconclusiveBehavior | warn | fail: inconclusive results end with exit code 4. warn and ignore: exit code 0, with the verdict pass_with_warnings and every inconclusive result listed |
policy.maxNewSurvivors | unset | Exit code 1 when more mutants survive in the run's scope (the changed code with --since). Inconclusive when there are no mutation results |
policy.minPropertyCoverage | unset | Exit code 1 when the share (0 to 1) of accepted properties with a meaningful_with_evidence test is lower. Inconclusive when no property is accepted or the run has no test assessments |
sandbox.allowNetworkWithoutIsolation | false | Run project code even without a Node.js 25 or later that can block its network access. Otherwise those results stay inconclusive |
storage.retainRuns | 20 | Number of finished runs kept in .veritas/runs/, the current run included. Older finished runs are deleted when a run finishes; runs still in progress are kept |
cache.enabled | true | Reuse results from .veritas/cache/ (see Caching) |
limits.memoryMb | 2048 | Memory limit (MiB, at least 256) for processes that run project code, the project's tests, mutator and Z3. Lean is not limited. Running out of memory is an error |
Inconclusive results are claims that are unknown, timeout, unsupported, semantic_mismatch or error, and stages that are partial, skipped, unsupported, timeout or cancelled.
Settings with a single allowed value
These settings state a rule and accept only one value. Any other value is an invalid configuration.
| Setting | Only value | Rule |
|---|---|---|
analysis.requireApprovalForNormativeClaims | true | A property becomes accepted only through a recorded decision |
improvement.testFilesOnly | true | improve only adds test files and never edits production code |
improvement.autoApply | false | A plan is applied only with --apply, its plan id and its approval token |
storage.storePrompts | false | Prompts sent to an LLM are not stored |
formal.rejectUnsupportedSemantics | true | Code outside the formal subset is unsupported, never approximated |
analysis.testFramework | vitest | Vitest is the supported test runner |
mutation.backend | mizchi | @mizchi/mutator runs mutation testing |
Caching
Veritas keeps three kinds of results in .veritas/cache/ and reuses them when the inputs are identical:
| Result | Reused when these are identical |
|---|---|
Decided Z3 results (sat, unsat) | The SMT query, the solver build and the time limit |
| Successful LLM responses | The provider, the model and the request |
| Complete mutation runs | The content of every file git ls-files lists, the mutator, Vitest and Node.js versions, the configuration, --since and the scope |
Undecided or failed results are not reused. A reused counterexample is still replayed in JavaScript, and the stage messages say when a result was reused. Without git, mutation results are not cached.
Entries are signed with a key stored outside the project, in ~/.cache/veritas/cache-key (%LOCALAPPDATA%\veritas\cache-key on Windows) or the file named by VERITAS_CACHE_KEY_FILE. Entries signed with a different key, for example ones copied in with a repository or restored on a CI runner without the key, are ignored. A cache directory tracked by git is ignored as a whole.
The project's own tests, which mutation testing runs, can read the key. For code you do not trust, set cache.enabled: false (see Security model).