Tool configuration

Set up the tools on a workstation: git identity, an editor's settings, a CLI's credentials, declared once and reapplied.

Installing a tool is often just the first step you have to take in order to use it. For example, Git needs your name and email, the GitHub CLI needs an access token, and an editor needs its settings. Every time you start a fresh machine, for yourself or for a coding agent, you have to do all of this over again.

In Ringleader, a toolconfig declares that setup once. You write the tool’s settings on a Workstation or a WorkstationConfig, and every machine it reaches writes the tool’s own configuration files, on every configuration pass, so the setup survives a rebuild.

Toolconfigs are the companion to devtools: devtools install software, toolconfigs configure it. For most tools you will declare both.

toolconfigs:
  - id: git
    name: git
    config:
      userName: Ada Lovelace
      userEmail: ada@example.com
FieldTypeDescription
namestringThe tool to configure.
idstringOptional stable identity for merging. Defaults to name.
configobjectThe per-tool configuration. Its shape is defined by each tool, below.

The tools

  • claude-code: user settings, operator-enforced managed settings, and MCP servers.
  • codex: ~/.codex/config.toml, as structured keys or a verbatim file.
  • vscode-web: the code-server port, authentication, bind address, and editor settings.
  • vscode-server: machine settings for desktop VS Code attached over SSH.
  • git: ~/.gitconfig, identity and arbitrary global settings.
  • gh: a headless, token-based GitHub CLI login.

A tool Ringleader does not recognize is skipped rather than treated as an error, so a newer configuration applied to an older workstation degrades quietly.

How toolconfigs behave

They are declarative and reapplied every time the workstation applies its configuration. Each file is desired state, and how much of the file that covers depends on who owns it:

  • Files Ringleader authors in full (Codex’s ~/.codex/config.toml, code-server’s ~/.config/code-server/config.yaml, Claude Code’s managed settings) are rewritten whole. Edit one by hand inside the workstation and the next pass puts it back.
  • Files the tool’s own UI writes too (~/.claude/settings.json, Claude Code’s state file, code-server’s User/settings.json) are key-scoped. Ringleader asserts the keys you declared and leaves every other key alone, so a setting the workstation’s own user changed in the tool survives. Stop declaring a key and it is withdrawn from the file; keys Ringleader never declared are still untouched.

They are safe to re-run. A file whose content already matches is not rewritten, so steady-state runs touch nothing and a tool’s own timestamps and formatting are left alone.

They are applied after devtools install, and before your files, sources, scripts, and services. So a script that depends on a tool being on its declared port (rather than its default) sees the configured tool.

They merge by id, last-wins on the whole entry. Two layers declaring the same id do not deep-merge: the higher-priority layer’s config replaces the lower one. When you override one field, re-declare the neighbours you still want.

# base config, priority 100
toolconfigs:
  - id: vscode-web
    name: vscode-web
    config: { port: 8080, auth: none }

# overlay, priority 200: replaces the entry above entirely
toolconfigs:
  - id: vscode-web
    name: vscode-web
    config: { port: 8080, auth: password, password: "${secret:ide-password}" }

Some are synthesised for you. Installing the claude-code or vscode-web devtool applies Ringleader’s permission defaults even with no toolconfig declared. An explicit toolconfig always wins.

Secrets

Any string in a config may carry a ${secret:NAME} reference, or ${secret:NAME/key} to select one key of a multi-key Secret. The reference travels through the system unresolved and is materialised inside the workstation, so no literal secret is ever stored in the object, its status, or its hashes.

If the Secret does not exist, the file is not written at all, and no placeholder goes in its place. Only that tool is affected: every other tool still gets its configuration, and the workstation reports the failing step. To avoid this, create the Secret before applying a config that references it.

toolconfigs:
  - name: gh
    config:
      token: "${secret:gh-token/token}"

Workspace trust

Coding tools ask “do you trust the authors of the files in this folder?”. Ringleader answers for them, on a workstation that exists to work on exactly those folders.

Every path in sources[].path is pre-trusted automatically, and trustedFolders adds more:

sources:
  - name: app
    git: { url: https://github.com/acme/app.git }
    path: /home/dev/src/app        # trusted automatically
trustedFolders:
  - /home/dev/scratch              # trusted as well

The resolved set is applied to every trust-aware tool on the workstation: claude-code, codex, vscode-web, and vscode-server. The first three pick it up from their devtool install alone, with no toolconfig needed. vscode-server installs nothing inside the workstation, so it must be declared explicitly to be trusted.

Paths are matched exactly, and a relative path resolves against the login user’s home directory.