Tool configuration | Ringleader Docs

toolconfigs is the configure channel of a Workstation or a WorkstationConfig. Where devtools install software, a toolconfig configures software — it writes the tool’s own configuration files inside the workstation and installs nothing.

toolconfigs:
  - id: git
    name: git
    config:
      userName: Ada Lovelace
      userEmail: ada@example.com

Field	Type	Description
`name`	`string`	The tool to configure.
`id`	`string`	Optional stable identity for merging. Defaults to `name`.
`config`	`object`	The 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 recognise 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. If you edit it by hand inside the workstation, the next run puts it back. Where a tool owns part of its own file — Claude Code’s state file, for instance — Ringleader merges into it rather than overwriting.

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.

A reference that cannot be resolved fails the workstation loudly rather than writing a placeholder: the file is not written with a placeholder in it. 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 — 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.