claude-code | Ringleader Docs

Install Claude Code with the claude-code devtool and it is ready to use: it opens without permission prompts, because a workstation is the sandbox those prompts exist to protect, and its background auto-updater is off, because the recipe pins the version. You do not need a toolconfig for that.

Add one when you want more:

toolconfigs:
  - id: claude-code
    name: claude-code
    config:
      mcpServers:
        linear:
          type: http
          url: https://mcp.linear.app/mcp

That gives every developer on the workstation the Linear MCP server, in both the terminal claude and the editor panels. The rest of this page covers MCP servers in full, your own settings, changing the two defaults, and the field list.

MCP servers

mcpServers is a map of server name to definition. Ringleader adds them the way you would yourself, with claude mcp add --scope user as the login user, so they land where the terminal and the editor panels both read them, and you can still add your own by hand.

Field	Type	Description
`type`	`string`	`http`, `sse`, or `stdio`. Defaults to `stdio` when `command` is set, otherwise `http`.
`url`	`string`	Required for `http` and `sse`.
`headers`	`object`	Header name to value, for `http`/`sse`. May carry secret references.
`command`	`string`	Required for `stdio`.
`args`	`array` of `string`	Arguments for `stdio`.
`env`	`object`	Environment for a `stdio` server. May carry secret references.

toolconfigs:
  - id: claude-code
    name: claude-code
    config:
      mcpServers:
        linear:
          type: http
          url: https://mcp.linear.app/mcp
        github:
          type: http
          url: https://api.githubcopilot.com/mcp/
          headers:
            Authorization: "Bearer ${secret:gh-token/token}"

Servers are applied the first time the workstation sets itself up and again only when the declared set changes, so a login you completed interactively (with /mcp in Claude) is not disturbed by a routine re-apply. When the set changes, each declared server is re-added and any server Ringleader previously added that you have since removed is removed. Servers you added yourself are never touched. An empty mcpServers: {} is valid: manage zero servers, which removes the ones Ringleader added.

Servers arrive unauthenticated

Declaring an MCP server does not log you in to it. Unless you supply a header or environment token, run /mcp in Claude and authenticate in the browser. Pair with passthrough-www-browser to have that page open on your laptop.

Settings

Claude Code reads two settings files, and this toolconfig can write both:

settings is the user layer, ~/.claude/settings.json, owned by the login user. Ringleader writes only the keys you declare and leaves every other key alone, so a setting a developer changed inside Claude Code survives every configuration pass. Remove a key from your declaration and it is removed from the file on the next pass.
managedSettings is the managed layer, /etc/claude-code/managed-settings.json, owned by root. It is the same file a corporate device-management policy would write, it takes precedence over the user layer, and Ringleader writes it in full.

Put a preference in settings and a rule in managedSettings.

The two defaults

Installing the devtool alone puts two things in the managed layer:

permissions.defaultMode: "bypassPermissions", so Claude Code does not prompt.
env.DISABLE_AUTOUPDATER: "1", so the background updater does not run. It runs as the workstation user, cannot write the root-owned install, and would move the workstation off its pinned version if it could; all it produced was an Auto-update failed warning. claude update still works by hand, and changing the devtool’s version is the declarative way to move a workstation.

Set either key yourself and your value stands. Setting permissions.defaultMode or permissions.disableBypassPermissionsMode leaves your whole permissions block as you wrote it; allow, deny and ask are preserved either way.

toolconfigs:
  - id: claude-code
    name: claude-code
    config:
      managedSettings:
        permissions:
          defaultMode: default        # prompts return
          deny:
            - "Bash(rm -rf *)"
        env:
          DISABLE_AUTOUPDATER: "0"    # background auto-update returns

Workspace trust

Folders in sources[].path and trustedFolders are pre-trusted for the CLI, so it never opens with a trust prompt on the code the workstation exists to work on. Ringleader merges those flags into Claude’s own state file; a folder already trusted is left alone.

`config` fields

Field	Type	Description
`mcpServers`	`object`	MCP servers to add at user scope, as above.
`settings`	`object`	The user settings layer; only the keys you declare are managed.
`managedSettings`	`object`	The managed settings layer, written in full, root-owned.

Example

A workstation whose terminal claude and editor panel both open without prompts, with an MCP server wired up and browser logins relayed to your laptop:

apiVersion: workstations.ringleader.dev/v1
kind: WorkstationConfig
metadata:
  name: ai-box
  namespace: local
spec:
  selector:
    matchLabels:
      tier: dev
  identity:
    user: dev
    shell: /bin/bash
  devtools:
    - name: nodejs
      version: "24"
    - name: claude-code
    - name: vscode-web
    - name: passthrough-www-browser
  toolconfigs:
    - id: claude-code
      name: claude-code
      config:
        mcpServers:
          linear:
            type: http
            url: https://mcp.linear.app/mcp
  sources:
    - name: app
      git:
        url: https://github.com/acme/app.git
        ref: main
      path: /home/dev/src/app         # pre-trusted
  defaultLocalBinding:
    enabled: true
    autoForward:
      forwardAll: true
    urlForward:
      enabled: true
      open: true

Notes

mcpServers needs the claude CLI on the workstation; declare the claude-code devtool or the apply step fails with a clear message.
Secret-bearing headers and environment values reach Claude through the environment and are never written into a script or a diagnostic record.
The editor panels ignore the CLI’s managed settings. To set panel behavior, use the vscode-web or vscode-server toolconfig.