Documentation

Groups, labels, and filters

Organize processes into one display group and use labels for startup-only filtering.

Why use groups and labels

Groups and labels let you start only part of a workspace. This is useful when a single vectron.toml covers:

Use each field for a different job:

group is a single optional process group. It is used by the TUI groups view and by group filters.
labels is an optional list. Labels are only used for startup filtering.

[[process]]
name = "web"
command = "npm run dev"
group = "frontend"
labels = ["public"]

The TUI still displays processes by group or by process. Labels do not create TUI groups.

Use global.disabled_groups or global.disabled_labels when some processes should be off unless explicitly re-enabled.

[global]
disabled_groups = ["experiments"]
disabled_labels = ["optional"]

For example, keep Storybook out of the default startup but allow an explicit opt-in:

[global]
disabled_labels = ["optional"]

[[process]]
name = "storybook"
command = "npm run storybook"
group = "frontend"
labels = ["optional"]

vectron start --enable-labels optional
vectron check --enable-labels optional

The optional label only affects startup filtering. The TUI groups view still uses group = "frontend" and does not create an optional group.

For groups, Vectron supports:

For labels, Vectron supports:

only and skip filters apply to start. enable-groups and enable-labels also apply to check.

When group and label filters are combined, a process must satisfy both dimensions:

vectron start --only-groups frontend --only-labels public

use group for the main UI bucket, such as frontend, backend, or monitoring
use labels for cross-cutting startup filters, such as public, jobs, or optional
keep production-like essentials outside disabled groups and disabled labels
document group and label intent for your team