Documentation

`vectron.toml` reference

Exhaustive reference for the main Vectron configuration file, including defaults and inheritance rules.

This page is the normative reference for vectron.toml.

When a field is optional, the table tells you whether its behavior comes from:

a fixed default value
inheritance from a parent field
a derived runtime rule

Resolution rules

Relative paths are resolved from the directory containing vectron.toml.
Process-level fields can override global fields.
Some fields have an effective runtime default even when the TOML field itself is omitted.
At least one [[process]] entry must exist for the config to validate.

Top-level sections

Field	Type	Required	Default / Inherits / Derived	Notes
`global`	table	No	Optional table	Global defaults applied to processes
`process`	array of tables	Yes	None	At least one `[[process]]` is required
`log_templates`	table	No	Default: empty table	Named rendering presets

`[global]`

Field	Type	Required	Default / Inherits / Derived	Notes
`log_dir`	path	No	Default: `.vectron/logs`	File log directory
`before`	string or array of strings	No	Default: none	Preflight command(s) run before process startup
`show_timestamps`	boolean	No	Effective default: `true`	Inherits into processes
`log_mode`	enum	No	Default: `console`	Allowed: `console`, `files`, `both`
`log_format`	enum	No	Default: `text`	Allowed: `text`, `logfmt`, `json`, `json_pretty`
`lifecycle`	enum	No	Default: `fail-fast`	Current lifecycle policy
`readiness`	table	No	Default: none	Global readiness model
`color`	color	No	Default: none	Default process color; accepts CSS-like color strings such as `red` or `#808080`
`log_template`	table	No	Default: none	Default rendering preset binding
`disable_color_env`	boolean	No	Default: `false`	Disables ANSI color-related env vars in child processes
`disabled_groups`	array of strings	No	Default: `[]`	Groups disabled unless re-enabled at runtime
`disabled_labels`	array of strings	No	Default: `[]`	Labels disabled unless re-enabled at runtime
`cleanup_logs`	boolean	No	Default: `true`	Recreates `log_dir` on start
`env`	string map	No	Default: `{}`	Base env vars for all processes
`env_file`	path	No	Default: none	Loaded after `global.env`
`instance_env_suffix`	string	No	Default: none	Must contain `{index}`
`port_start`	integer	No	Default: `5000`	Base port allocation; legacy alias: `port_base`
`port_step`	integer	No	Default: `100`	Port spacing between processes
`formation_port_step`	integer	No	Default: `1`	Port spacing between instances
`shutdown_timeout_secs`	integer	No	Default: `90`	Graceful shutdown window before escalation
`working_dir`	path	No	Default: none	Effective behavior: workspace/config root when omitted
`tui`	table	No	Default: empty table with threshold defaults	TUI-only settings

`[global.readiness]`

Log readiness

Field	Type	Required	Default / Inherits / Derived	Notes
`type`	string	Yes	Required value: `log`	Selects log-based readiness
`ready`	table	No	Default: none	Success pattern
`error`	table	No	Default: none	Error pattern
`ready.pattern`	string	Yes, if `ready` exists	None	Regex pattern
`ready.stream`	enum	No	Default: `stdout`	Allowed: `stdout`, `stderr`
`error.pattern`	string	Yes, if `error` exists	None	Regex pattern
`error.stream`	enum	No	Default: `stdout`	Allowed: `stdout`, `stderr`

At least one of ready or error must be present.

TCP readiness

Field	Type	Required	Default / Inherits / Derived	Notes
`type`	string	Yes	Required value: `tcp`	Selects TCP readiness
`host`	string	No	Default: `127.0.0.1`	Probe host
`port`	string or integer	No	Default: `auto`	`auto` follows the allocated instance port
`interval_ms`	integer	No	Default: `500`	Poll interval

`[global.log_template]`

Field	Type	Required	Default / Inherits / Derived	Notes
`preset`	string	No	Default: none	Applied to both streams unless overridden
`stdout_preset`	string	No	Default: none	Stdout-only override
`stderr_preset`	string	No	Default: none	Stderr-only override

`[global.tui.metrics.thresholds]`

Field	Type	Required	Default / Inherits / Derived	Notes
`cpu_warn`	float	No	Default: `60.0`	Per-instance CPU warn threshold
`cpu_crit`	float	No	Default: `85.0`	Per-instance CPU crit threshold
`rss_warn`	bytes or IEC string	No	Default: `256MiB`	Per-instance RSS warn threshold
`rss_crit`	bytes or IEC string	No	Default: `1GiB`	Per-instance RSS crit threshold
`total_cpu_warn`	float	No	Default: none; derived if omitted	UI status-bar total threshold
`total_cpu_crit`	float	No	Default: none; derived if omitted	UI status-bar total threshold
`total_rss_warn`	bytes or IEC string	No	Default: none; derived if omitted	UI status-bar total threshold
`total_rss_crit`	bytes or IEC string	No	Default: none; derived if omitted	UI status-bar total threshold

When total thresholds are omitted, the UI derives totals from per-instance thresholds.

`[[process]]`

Field	Type	Required	Default / Inherits / Derived	Notes
`name`	string	Yes	None	Stable process identifier
`command`	string	Yes	None	Child command line
`instances`	integer	No	Default: `1`	Number of copies to launch
`working_dir`	path	No	Inherits `global.working_dir`; effective default: workspace/config root	Spawn directory
`log_mode`	enum	No	Inherits `global.log_mode`; effective default: `console`	Allowed: `console`, `files`, `both`
`log_format`	enum	No	Inherits `global.log_format`; effective default: `text`	Allowed: `text`, `logfmt`, `json`, `json_pretty`
`group`	string	No	Default: none	Single process group used by the TUI and group filters
`labels`	array of strings	No	Default: `[]`	Startup-only labels used by label filters
`show_timestamps`	boolean	No	Inherits `global.show_timestamps`; effective default: `true`	Console/TUI timestamp display
`lifecycle`	enum	No	Inherits `global.lifecycle`; effective default: `fail-fast`	Lifecycle policy
`readiness`	table	No	Inherits `global.readiness`	Per-process readiness override
`color`	color	No	Default: none	Process color; accepts CSS-like color strings such as `red` or `#808080`
`instance_colors`	array of colors	No	Default: `[]`	Optional per-instance CSS-like colors
`log_template`	table	No	Inherits `global.log_template`	Rendering preset override
`disable_color_env`	boolean	No	Inherits `global.disable_color_env`; effective default: `false`	Child ANSI handling override
`env`	string map	No	Default: `{}`	Per-process env vars
`env_file`	path	No	Default: none	Loaded after process env
`instance_env_suffix`	string	No	Inherits `global.instance_env_suffix`	Must contain `{index}`
`port_env`	string	No	Field default: none; effective env var: `PORT`	Overrides the environment variable that receives the allocated port
`port_start`	integer	No	Derived from the current allocation cursor	Not a fixed constant default
`port_step`	integer	No	Inherits `global.port_step`; effective default: `100`	Port spacing for this process
`formation_port_step`	integer	No	Inherits `global.formation_port_step`; effective default: `1`	Instance spacing for the next allocation base
`log_dir`	path	No	Inherits `global.log_dir`	Per-process file log directory
`tui.metrics.thresholds.cpu_warn`	float	No	Inherits global threshold; effective default: `60.0`	Per-process override
`tui.metrics.thresholds.cpu_crit`	float	No	Inherits global threshold; effective default: `85.0`	Per-process override
`tui.metrics.thresholds.rss_warn`	bytes or IEC string	No	Inherits global threshold; effective default: `256MiB`	Per-process override
`tui.metrics.thresholds.rss_crit`	bytes or IEC string	No	Inherits global threshold; effective default: `1GiB`	Per-process override

`[log_templates.<name>]`

Field	Type	Required	Default / Inherits / Derived	Notes
`extends`	string	No	Default: none	Inherit from another preset
`fields`	table	No	Default: none	Shared layout for stdout and stderr
`stdout_fields`	table	No	Default: none	Stdout-only layout
`stderr_fields`	table	No	Default: none	Stderr-only layout

`[log_templates.<name>.*_fields]`

Field	Type	Required	Default / Inherits / Derived	Notes
`separator`	string	No	Effective default: `" "`	Inserted between rendered fields
`missing`	string	No	Default: none	Replacement text for missing keys
`fields`	array of tables	No	Default: `[]`	Rendered in order

`[[log_templates.<name>.*_fields.fields]]`

Field	Type	Required	Default / Inherits / Derived	Notes
`key`	string	Yes	None	Extracted field key
`prefix`	string	No	Default: none	Prepended before the value
`suffix`	string	No	Default: none	Appended after the value
`default`	string	No	Default: none	Fallback value when key is missing
`map`	string map	No	Default: `{}`	Value remapping
`format`	enum	No	Effective default: `none`	Allowed: `none`, `lowercase`, `uppercase`, `number`, `duration_ms`
`visible_if`	enum	No	Effective default: `always`	Allowed: `always`, `present`, `non_empty`
`color`	color	No	Default: none	Value color
`color_rules`	array of tables	No	Default: `[]`	Regex-based color overrides

Color values are parsed as CSS-like color strings. Common examples include named colors such as red and hex colors such as #808080 or #112233.

`[[log_templates.<name>.*_fields.fields.color_rules]]`

Field	Type	Required	Default / Inherits / Derived	Notes
`regex`	string	Yes	None	Regex matched against the field value
`color`	color	Yes	None	CSS-like color applied when `regex` matches

Example:

[log_templates.api.fields]
fields = [
  { key = "level", color_rules = [
    { regex = "WARN|ERROR", color = "red" },
  ] },
]

Validation rules

Validation includes checks for:

at least one process
non-empty commands
valid process names, groups, and labels
valid disabled_groups and disabled_labels labels
valid port_step and formation_port_step values
port allocation overflow
existing referenced env_file paths
valid readiness configuration
valid log-template references
valid instance_env_suffix values containing {index}

Source of truth

Use vectron.example.toml as the main onboarding example when you want a full commented config. Use this page when you need the exact field behavior.