Configuration

vary.toml

Every Vary project can have a vary.toml file at its root. The compiler searches upward from the current directory to find it. If no config file exists, defaults are used for everything.

Create one with:

vary init

Or view the active configuration with:

vary config --verbose

Minimal example

Most projects only need a few lines:

[project]
name = "my-app"
version = "0.1.0"

[source]
directories = ["src"]
test_directories = ["tests"]

Full reference

[project]

Project metadata. Used in build output and artifact naming.

Field	Type	Default	Description
name	Str	"unnamed"	Project name
version	Str	"0.1.0"	Version string (available as __project_version__ in code)
description	Str	""	Short description

[source]

Where the compiler looks for .vary files.

Field	Type	Default	Description
directories	Array	["src"]	Source code directories
test_directories	Array	["tests"]	Test file directories
excludes	Array	[]	Patterns to skip during compilation

roots is accepted as an alias for directories.

[compiler]

Controls how code is compiled.

Field	Type	Default	Description
target	Str	"17"	JVM target version (e.g. "17", "21")
stdlib	Str	null	Custom path to stdlib (rarely needed)
output_dir	Str	"build"	Where compiled output goes
warnings_as_errors	Bool	false	Treat warnings as errors
verbose	Bool	false	Verbose compiler output
optimization	Int	0	Optimization level: 0 = none, 1 = basic, 2 = aggressive
debug_info	Bool	true	Include debug info in bytecode
strict_null_checks	Bool	true	Enforce null safety

[test]

Test execution settings.

Field	Type	Default	Description
parallel	Int	1	Number of parallel test runners
coverage	Bool	false	Enable coverage tracking
coverage_threshold	Int	0	Minimum coverage percentage (0 = no gate)
timeout	Int	300	Test timeout in seconds

[mutation]

Mutation testing settings used by vary mutate.

Field	Type	Default	Description
operators	Str	"all"	Which mutation operators to apply, comma-separated or "all"
quick_limit	Int	20	Maximum mutants in --quick mode
timeout	Int	5000	Per-mutant timeout in milliseconds
report_format	Str	"text"	Output format: "text", "html", or "json"
report_dir	Str	"mutation-reports"	Where reports are written
min_score	Float	0.0	Minimum mutation score (0-100), fails the run if not met
fail_on_decrease	Bool	false	Fail if mutation score dropped since last run
max_survivors	Int	unlimited	Maximum allowed surviving mutants
pairing_mode	Str	"fallback_all_tests"	How mutants are paired with tests: "fallback_all_tests" or "strict"
emit_manifest	Bool	true	Emit mutation manifest (.vary/mutation-manifest.json) during builds
max_pure_survivors	Int	unlimited	Maximum surviving mutants in pure def regions
require_contracts_in_pure	Bool	false	Require contracts on pure functions touched by mutants
min_contract_kills	Int	0	Minimum contract kills (PRE+POST+INVARIANT) required
min_contract_adequacy	Float	0.0	Minimum contract adequacy score (0-100)
allow_no_oracle_tests	Bool	false	Allow tests without oracles (otherwise warned/errored)
min_integrity	Float	0.0	Minimum integrity score gate (0-100)

[validate]

Settings for vary validate.

Field	Type	Default	Description
contracts	Bool	false	Enable structured contract violation reporting in test output

When contracts is true, contract violations detected during test execution are reported in a structured block showing the violation kind, function name, source location, and failing expression.

[format]

Code formatting settings used by vary fmt.

Field	Type	Default	Description
indent_size	Int	4	Spaces per indent level
max_line_length	Int	100	Maximum line length
use_spaces	Bool	true	Spaces instead of tabs
trailing_newline	Bool	true	Ensure files end with a newline
sort_imports	Bool	true	Sort and group import statements

[cache]

Controls the content-addressed artifact cache in .vary/artifacts/.

Field	Type	Default	Description
enabled	Bool	true	Enable caching
directory	Str	".vary/artifacts"	Cache directory path
max_size_mb	Int	500	Maximum cache size in MB
max_age_days	Int	30	Evict artifacts older than this
eviction_policy	Str	"lru"	"lru" (least recently used), "lfu" (least frequently used), or "none"
auto_gc	Bool	true	Run garbage collection automatically
validate_on_load	Bool	true	Validate artifacts before using them

[check]

Settings for vary check diagnostics.

Field	Type	Default	Description
profile	Str	"local"	Check profile: "local" (default) or "ci" (JSON output, warnings as errors)
warnings	Str	"all"	Warning mode: "all", "none", or "error"

[check.analysis]

Field	Type	Default	Description
broad_effects_threshold	Int	3	Warn if a function produces more than this many distinct effect classes

[check.effects]

Field	Type	Default	Description
deny	Array	[]	Effect classes to forbid (e.g. ["PROCESS", "NETWORK"]). Functions producing denied effects are flagged as errors.

Available effect classes: IO, NETWORK, FILESYSTEM, PROCESS, STATE, CONCURRENCY, TIME, RANDOM.

[lsp]

Language server configuration.

Field	Type	Default	Description
enabled	Bool	true	Enable the LSP server
port	Int	0	TCP port (0 = use stdio mode)
log_file	Str	null	Optional path for LSP logs

[services]

Network host restrictions for service declarations (typed HTTP clients).

Field	Type	Default	Description
allowed_hosts	Array	[]	Hosts the project may connect to (empty = all allowed)
denied_hosts	Array	[]	Hosts explicitly blocked

Host patterns support wildcard subdomains: *.example.com matches api.example.com and foo.bar.example.com.

[services]
allowed_hosts = ["api.example.com", "*.internal.example.com"]
denied_hosts = ["untrusted.com"]

When allowed_hosts is non-empty, any service targeting a host not in the list is flagged by VCS008. Hosts in denied_hosts are always blocked.

[profiles.*]

Custom validation profiles for vary validate --profile <name>. Each profile defines which checks to run and their thresholds.

Field	Type	Default	Description
checks	Array	[]	Stages to run (e.g., "check", "test", "mutation")
timeout	Int	300	Timeout in seconds

Thresholds are nested under [profiles.<name>.thresholds]:

[profiles.local]
checks = ["check", "test"]

[profiles.local.thresholds]
coverage = 70

[profiles.ci]
checks = ["check", "test", "mutation"]

[profiles.ci.thresholds]
coverage = 80
mutation = 80

[profiles.nightly]
checks = ["check", "test", "mutation"]
timeout = 600

[profiles.nightly.thresholds]
coverage = 90
mutation = 90

[dependencies]

Dependencies use a different format from other sections. Each dependency is a key-value pair where the key is the dependency name:

[dependencies]
my-lib = "1.0.0"
local-lib = { version = "2.0.0", path = "./libs/local-lib" }

The path form points to a local directory containing another Vary project with its own vary.toml.

Bigger example

A project that gates on mutation score and runs tests in parallel:

[project]
name = "my-api"
version = "0.2.0"
description = "Order management API"

[source]
directories = ["src"]
test_directories = ["tests"]
excludes = ["src/scratch"]

[compiler]
target = "21"
warnings_as_errors = true
optimization = 1

[test]
parallel = 4
timeout = 60

[mutation]
min_score = 75.0
fail_on_decrease = true
max_survivors = 10
timeout = 3000

[validate]
contracts = true

[cache]
max_size_mb = 200
max_age_days = 7