Configuration schema

~/.config/loadout/config.yaml. Every section is optional except version.

~/.config/loadout/local.yaml uses the same schema and overlays this file. It is never synced.

version

version: 1

Schema version. Required. The current version is 1.

paths

paths:
  project_root: ~/Projects
  venv_root: ~/.venv

Field	Type	Default	Read by
project_root	path	~/Projects	p, pv, pw, clone-sources
venv_root	path	~/.venv	venv, activate, denv, lenv

Paths are written into the generated shell in $HOME form, never as a literal tilde, because a tilde does not expand inside double quotes.

git

git:
  main_branch: main
  dev_branch: development

Field	Type	Default	Read by
main_branch	string	main	The git aliases
dev_branch	string	development	The git aliases

ssh

ssh:
  default_key: ~/.ssh/id_ed25519
  default_user: root
  default_host: 10.0.0.10
  default_port: 22
  subnet_prefix: "10.0.0."

Field	Type	Default	Notes
default_key	path	—	Fallback key for msh
default_user	string	root	Fallback user
default_host	string	—	Used when msh is called bare
default_port	int	22
subnet_prefix	string	—	Lets a bare number be the last octet: 10.0.0. plus 5 is 10.0.0.5. Empty disables the shorthand.

identities

identities:
  - id: personal
    git_user: Your Name
    email: you@example.com
    ssh_key: ~/.ssh/id_ed25519
    default: true
    activates:
      npm_token: personal

Field	Type	Notes
id	string	What you pass to loadout identity activate
git_user	string	git user.name
email	string	git user.email
ssh_key	path	Added to the agent on activation
default	bool	Active on a fresh machine
activates	map	Credential name to entry name

Every credential and entry named in activates must exist. See Identities.

credentials

credentials:
  npm_token:
    active: personal
    entries: [personal, work]
  gh_token:
    env: GHP_TOKEN
    active: personal
    entries: [personal, work]

Field	Type	Notes
active	string	Must be one of entries
entries	list	The named entries that exist for this secret
env	string	Override the exported variable name

No values here, ever. They live in the OS keychain, addressed as loadout/<credential>/<entry>.

env defaults to the key upper-cased with -, . and / turned into underscores, so npm_token gives NPM_TOKEN. Two credentials resolving to the same variable is rejected at load time.

hosts

hosts:
  - alias: staging
    hostname: staging.example.com
    user: deploy
    port: 22
    key: ~/.ssh/deploy
    upload_path: /srv/app
    shortcut: true

Field	Type	Notes
alias	string	What msh -m takes
hostname	string	Host or IP
user	string
port	int	Defaults to ssh.default_port
key	path
password	string	Must be cred:<name>. A literal is rejected
upload_path	path	Destination for mpush
shortcut	bool	Also emit a bare ssh <alias> alias

workspaces

workspaces:
  - name: api
    path: ~/Projects/api/api.code-workspace
    tmux_session: api

Field	Type	Notes
name	string	Also becomes an alias that opens it
path	path	Workspace or project directory
tmux_session	string	Pairs opening the workspace with a tmux session

clone_sources

clone_sources:
  - alias: work
    org: example-org

Generates a command that clones a repository from that organisation, so work myrepo clones example-org/myrepo.

editors

editors:
  - name: code
    command: code
  - name: nvim
    command: nvim

The first entry is the default. Read by pv and pw.

node_versions, npm_globals

node_versions: ["20", "22"]
npm_globals: [pm2, serve, prettier, "@nestjs/cli"]

Lists used by the node and npm helpers.

binaries

binaries:
  - name: duckdb
    version: v1.1.3
    source:
      github: duckdb/duckdb
      asset:
        linux-amd64: duckdb_cli-linux-amd64.zip
        darwin-arm64: duckdb_cli-osx-universal.zip
    checksum:
      linux-amd64: sha256:abc...
      darwin-arm64: sha256:def...

Field	Type	Notes
name	string	The name it takes on PATH
version	string	Pinned
source.github	string	owner/repo
source.asset	map	Platform key to release asset name
source.url	map	Platform key to direct URL, instead of github
checksum	string or map	One hash, or one per platform

Platform keys are <os>-<arch>. checksum accepts a bare string when only one platform is declared, and a map otherwise — a single hash describes one artefact and is wrong everywhere else. See Managed binaries.

scripts

scripts:
  - name: csf
    source: builtin
  - name: deploy
    source: ~/dev/scripts/deploy.sh

source is either builtin — one of the shipped scripts, written out from the binary — or a path, which is symlinked and stays where it lives.

packs

packs: [flutter, cloudflared]

Opt-in bundles, off unless listed. See the packs reference.

aliases

aliases:
  disabled: [ls, py]
  custom:
    - name: deploy
      command: ./scripts/deploy.sh
      platform: [linux]

Field	Type	Notes
disabled	list	Shipped aliases not to generate
custom[].name	string	Overrides a shipped alias of the same name
custom[].command	string
custom[].platform	list	linux, darwin, or omitted for both

Merge rules for local.yaml

Kind	Behaviour
Scalar	Replaced
Map	Merged key by key
List	Replaced wholesale

A local.yaml that sets packs replaces the list rather than adding to it.