Documentation

`vectron.stack.toml` reference

Exhaustive reference for the stack configuration file, including defaults and required fields.

This page is the normative reference for vectron.stack.toml.

For copyable configurations that combine multiple plugin sections, see the stack examples.

Unlike vectron.toml, many stack fields are plugin-specific. This page documents which fields are required, which have fixed defaults, and which are derived at provision time.

Resolution rules

schema_version, tld, and enabled are required top-level fields.
Relative paths are resolved from the directory containing vectron.stack.toml.
Plugin-specific sections are optional unless their plugin requires them.
vectron stack check and vectron stack provision validate the same file model before side effects.

Top-level fields

Field	Type	Required	Default / Inherits / Derived	Notes
`schema_version`	integer	Yes	None	Currently must be `1`
`tld`	string	Yes	None	Lowercase DNS-like root domain
`enabled`	array of strings	Yes	None	Non-empty unique plugin ID list; see accepted values below
`brew`	table	No	Default: none	Extra Homebrew dependencies
`monitoring`	table	No	Default: none	Monitoring group behavior
`kubernetes`	table	No	Default: none	Local cluster provisioning
`nginx`	table	No	Default: none	Reverse proxy configuration
`grafana`	table	No	Default: none	Grafana provisioning
`prometheus`	table	No	Default: none	Prometheus provisioning
`alloy`	table	No	Default: none	Alloy provisioning
`rabbitmq`	table	No	Default: none	RabbitMQ provisioning
`neo4j`	table	No	Default: none	Neo4j provisioning

Plugin IDs

enabled accepts these plugin IDs:

ID	Category
`certificates`	Foundation
`dnsmasq`	Foundation
`ssh`	Foundation
`nginx`	Reverse proxy
`prometheus`	Observability
`loki`	Observability
`alloy`	Observability
`grafana`	Observability
`mongodb`	Datastore
`rabbitmq`	Messaging
`redis`	Datastore
`neo4j`	Datastore
`minio`	Datastore
`qdrant`	Datastore
`postgresql`	Datastore
`influxdb`	Datastore
`mosquitto`	Messaging and IoT
`zigbee2mqtt`	Messaging and IoT
`docker`	Containers
`kubernetes`	Containers and clusters

Rules:

enabled must be non-empty.
Plugin IDs must be unique after trimming.
Empty plugin IDs are invalid.
nginx implicitly adds certificates.
alloy implicitly adds loki.
vectron stack provision/check/landing-ids --only replaces the initial enabled selection with the requested plugin IDs before implicit dependencies are added.
vectron stack provision/check/landing-ids --skip removes plugin IDs from the selected set.

See the built-in plugins page for roles and plugin-specific configuration sections.

`[brew]`

Field	Type	Required	Default / Inherits / Derived	Notes
`taps`	array of strings	No	Default: `[]`	Additional Homebrew taps
`formulae`	array of strings	No	Default: `[]`	Additional formulae to install

`[monitoring]`

Field	Type	Required	Default / Inherits / Derived	Notes
`autostart`	boolean	No	Default: `false`	When `false`, generated monitoring processes stay disabled by default

`[kubernetes]`

Field	Type	Required	Default / Inherits / Derived	Notes
`driver`	enum	No	Default: `k3d`	Allowed: `kind`, `k3d`, `minikube`
`cluster_name`	string	No	Default: `vectron`	Lowercased during normalization
`control_planes`	integer	No	Default: `1`	Must be `>= 1`; driver-specific limits apply
`workers`	integer	No	Default: `0`	Driver-specific limits apply
`wait_seconds`	integer	No	Default: `120`	Cluster operation timeout
`kubeconfig_path`	path	No	Default: `.vectron_stack/generated/kubernetes/kubeconfig`	Must stay under the workspace root
`kubernetes_version`	string	No	Default: none	Only valid for `minikube`
`node_image`	string	No	Default: none	Valid for `kind` and `k3d`, not `minikube`
`api_server_address`	string	No	Default: `127.0.0.1`	Driver-specific restrictions apply
`api_server_port`	integer	No	Default: `6443`	Must be in `1..=65535`
`local_registry_port`	integer	No	Default: `5001`	Must be in `1..=65535`
`recreate_existing`	boolean	No	Default: `false`	Recreates an existing cluster with the same name
`stop_after_init`	boolean	No	Default: `true`	Relevant for stoppable drivers
`stop_on_vectron_stop`	boolean	No	Default: `true`	Relevant for stoppable drivers

`[nginx]`

Field	Type	Required	Default / Inherits / Derived	Notes
`https_port`	integer	Yes	None	HTTPS listen port
`landing`	table	No	Default: none	Optional landing page config
`server`	array of tables	No	Default: `[]`	Declarative server blocks

`[nginx.landing]`

Field	Type	Required	Default / Inherits / Derived	Notes
`quick_links`	array of strings	No	Default: `[]`	Ordered landing-page links

`[[nginx.server]]`

Field	Type	Required	Default / Inherits / Derived	Notes
`server_names`	array of strings	Yes	None	Hostnames served by this block
`link`	table	No	Default: none	Optional landing-page link
`upstreams`	string map	No	Default: `{}`	Upstream name to URL
`route`	array of tables	No	Default: `[]`	Evaluated in order

`[[nginx.server]].link`

Field	Type	Required	Default / Inherits / Derived	Notes
`label`	string	Yes	None	Human-facing link label
`path`	string	No	Default: `/`	Must start with `/`

`[[nginx.server]].route`

Field	Type	Required	Default / Inherits / Derived	Notes
`match.prefix`	string	Yes	None	Must start with `/`
`to.upstream`	string	Yes	None	Must exist in `upstreams`
`to.pass_path`	string	No	Default: none	Optional upstream path rewrite
`to.websocket`	boolean	No	Default: `false`	Enables WebSocket proxy mode
`to.grpc`	boolean	No	Default: `false`	Enables gRPC proxy mode

`[grafana]`

Field	Type	Required	Default / Inherits / Derived	Notes
`dashboard_dirs`	array of tables	No	Default: `[]`	Dashboard import sources

`[[grafana.dashboard_dirs]]`

Field	Type	Required	Default / Inherits / Derived	Notes
`dir`	path	Yes	None	Directory containing `*.json` dashboards
`folder`	string	Yes	None	Grafana folder name

`[prometheus]`

Field	Type	Required	Default / Inherits / Derived	Notes
`scrape_config_files`	array of paths	No	Default: `[]`	Extra YAML scrape configs

`[alloy]`

Field	Type	Required	Default / Inherits / Derived	Notes
`import_files`	array of tables	No	Default: `[]`	Imported Alloy modules
`blocks`	array of strings	No	Default: `[]`	Raw Alloy blocks appended to generated config
`docker_logs`	table	No	Default: none	Optional Docker logs ingestion

`[[alloy.import_files]]`

Field	Type	Required	Default / Inherits / Derived	Notes
`name`	string	Yes	None	Import namespace
`path`	path	Yes	None	Must point to a `.alloy` file

`[alloy.docker_logs]`

Field	Type	Required	Default / Inherits / Derived	Notes
`enabled`	boolean	No	Default: `false`	Enables Docker log ingestion into Loki
`host`	string	No	Derived	Primary: `unix://$HOME/.docker/run/docker.sock`; fallback: `unix:///var/run/docker.sock`
`refresh_interval`	duration string	No	Default: `5s`	Used by `loki.source.docker`
`labels`	string map	No	Default: `{}`	Static labels applied to all Docker log entries
`relabel`	array of tables	No	Default: `[]`	Docker metadata relabel rules

`[[alloy.docker_logs.relabel]]`

Field	Type	Required	Default / Inherits / Derived	Notes
`source_labels`	array of strings	No	Default: `[]`	Metadata labels to read
`target_label`	string	Yes	None	Destination Loki label

`[rabbitmq]`

Field	Type	Required	Default / Inherits / Derived	Notes
`vhost`	array of tables	Yes	None	Must contain at least one entry
`dead_letter_exchange`	string	No	Default: `dead-letter-exchange`	Created per vhost
`dead_letter_queue`	string	No	Default: `dead-letter`	Created per vhost
`policy_name`	string	No	Default: `all`	RabbitMQ policy name
`policy_pattern`	string	No	Default: `.*`	RabbitMQ policy regex
`consumer_timeout_ms`	integer	No	Default: `7200000`	Must be `> 0`

`[[rabbitmq.vhost]]`

Field	Type	Required	Default / Inherits / Derived	Notes
`name`	string	Yes	None	Vhost name
`queues`	array of strings	No	Default: `[]`	Queues created in the vhost

`[neo4j]`

Field	Type	Required	Default / Inherits / Derived	Notes
`schema_files`	array of paths	No	Default: `[]`	Cypher schema files applied during provisioning

Validation rules

Validation includes checks for:

schema_version == 1
non-empty enabled
known, unique, non-empty plugin IDs
valid driver-specific Kubernetes constraints
valid relative workspace-safe kubeconfig_path
non-empty required strings in plugin config
deduplicated names and paths where required
valid Alloy Docker logs scheme and interval
valid RabbitMQ provisioning config before side effects

Recommendation

Use vectron.stack.example.toml as the onboarding example, then use this page when you need exact field behavior.

Platform note

Stack mode is currently macOS-only.