Alpha. Vary is under active development and not ready for production use. Syntax, APIs, performance, and behaviour may change between releases.

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

CLI reference Project layout