Writing a config

Every key of the zc-workstation config file, per provider.

.md

The config is found in this order: -config, $ZC_WORKSTATION_CONFIG, ./zc-workstation.yaml, then ~/.config/zc-workstation/zc-workstation.yaml. -config - reads standard input.

Keep the config in your dotfiles repository next to the manifests it names. Relative paths are relative to the config file, and ~ is your home directory, so the same file works on every machine.

version: 1
targets:
  - name: brew
    provider: packages
    os: [darwin]
    file: packages/Brewfile

  - name: dotfiles
    provider: dotfiles
    source: home
    mode: symlink

  - name: runtimes
    provider: tools
    file: mise.toml

Every target

Key Meaning

Key	Meaning
`version`	Always `1`. A future format bumps it.
`name`	Lowercase kebab case, unique. `-target` selects by it.
`provider`	`packages`, `dotfiles`, `tools`, `desktop`, `settings`, `services`, `keyboard`, `agents` or `localdir`.
`os`	The systems the target is for: `darwin`, `linux`, `windows`. Empty means every system.

version

Always 1. A future format bumps it.

name

Lowercase kebab case, unique. -target selects by it.

provider

packages, dotfiles, tools, desktop, settings, services, keyboard, agents or localdir.

os

The systems the target is for: darwin, linux, windows. Empty means every system.

Per provider

Provider Key Meaning

Provider	Key	Meaning
`packages`	`file`	Required. The manifest: a Brewfile, a package list, or a winget import file.
	`manager`	`brew`, `apt`, `dnf` or `winget`. Empty picks the system’s: brew on macOS, winget on Windows, apt on Linux unless only dnf is installed.
	`upgrade`	Also plan an `UPDATE` for each declared package with a newer version. Off by default.
`dotfiles`	`source`	Required. The chezmoi source directory.
	`destination`	Where the files land. Empty means your home directory.
	`mode`	`file` copies (the default); `symlink` links back into the source.
`tools`	`file`	Required. The mise config file whose tools to install.
	`upgrade`	Also plan an `UPDATE` for each runtime with a newer version that its request allows. Off by default.
`desktop`	`wallpaper`	The picture to show on every desktop.
	`screensaver`	The web page for WebViewScreenSaver to show. Set this, `wallpaper`, `accent`, or any of them. The target needs `os: [darwin]`.
	`accent`	The macOS accent colour: `blue`, `purple`, `pink`, `red`, `orange`, `yellow`, `green` or `graphite`.
`settings`	`defaults`	Required on macOS. A macOS preferences domain, such as `com.apple.dock` or `NSGlobalDomain`, to its keys and values: a bool, an integer, a number or a string. A string starting with `~/` is a path in your home directory. The target needs `os: [darwin]`.
	`gsettings`	Required on Linux. A GNOME schema, such as `org.gnome.desktop.interface`, to its keys and values: a bool, a number, a string or a list of strings. The target needs `os: [linux]`.
	`registry`	Required on Windows. A registry key under `HKCU`, such as `'HKCU\Software\Microsoft\Windows\CurrentVersion\Themes\Personalize'`, to its values: a bool or an integer, stored as a DWORD, or a string. The target needs `os: [windows]`.
`services`	`services`	Homebrew services to keep running. Set this, `agents`, or both. The target needs `os: [darwin]` or `os: [linux]`.
	`agents`	launchd agent plists to keep loaded, the label being the file name without `.plist`; on Linux, systemd user `.service` and `.timer` files to keep enabled and active; on Windows, Task Scheduler `.xml` files to keep registered and enabled. The target needs one `os`.
`keyboard`	`file`	Required. The keyd config to install as `/etc/keyd/default.conf`, such as `assets/keyd/default.conf`. The target needs `os: [linux]`.
`localdir`	`path`	Required. The directory to keep.
	`files`	File name to content. Names must stay inside `path`.
	`prune`	Also delete files in `path` the config does not list.

packages

file

Required. The manifest: a Brewfile, a package list, or a winget import file.

manager

brew, apt, dnf or winget. Empty picks the system’s: brew on macOS, winget on Windows, apt on Linux unless only dnf is installed.

upgrade

Also plan an UPDATE for each declared package with a newer version. Off by default.

dotfiles

source

Required. The chezmoi source directory.

destination

Where the files land. Empty means your home directory.

mode

file copies (the default); symlink links back into the source.

tools

file

Required. The mise config file whose tools to install.

upgrade

Also plan an UPDATE for each runtime with a newer version that its request allows. Off by default.

desktop

wallpaper

The picture to show on every desktop.

screensaver

The web page for WebViewScreenSaver to show. Set this, wallpaper, accent, or any of them. The target needs os: [darwin].

accent

The macOS accent colour: blue, purple, pink, red, orange, yellow, green or graphite.

settings

defaults

Required on macOS. A macOS preferences domain, such as com.apple.dock or NSGlobalDomain, to its keys and values: a bool, an integer, a number or a string. A string starting with ~/ is a path in your home directory. The target needs os: [darwin].

gsettings

Required on Linux. A GNOME schema, such as org.gnome.desktop.interface, to its keys and values: a bool, a number, a string or a list of strings. The target needs os: [linux].

registry

Required on Windows. A registry key under HKCU, such as 'HKCU\Software\Microsoft\Windows\CurrentVersion\Themes\Personalize', to its values: a bool or an integer, stored as a DWORD, or a string. The target needs os: [windows].

services

Homebrew services to keep running. Set this, agents, or both. The target needs os: [darwin] or os: [linux].

agents

launchd agent plists to keep loaded, the label being the file name without .plist; on Linux, systemd user .service and .timer files to keep enabled and active; on Windows, Task Scheduler .xml files to keep registered and enabled. The target needs one os.

keyboard

file

Required. The keyd config to install as /etc/keyd/default.conf, such as assets/keyd/default.conf. The target needs os: [linux].

localdir

path

Required. The directory to keep.

files

File name to content. Names must stay inside path.

prune

Also delete files in path the config does not list.

Providers describes what each one reads and runs.

Mistakes are errors

An unknown key is an error, not a warning: a typo should not silently mean the default. A key a provider ignores, such as mode on a packages target, is an error too. validate reports every problem at once:

$ zc-workstation validate
zc-workstation.yaml: target brew: manager "pacman" is not one of brew, apt, dnf, winget
target dotfiles: source is required for provider dotfiles

Edit this page Last updated October 16, 2026