claude-code | Ringleader Docs

Installs the Claude Code CLI (claude) as a global npm package.

devtools:
  - name: nodejs
  - name: claude-code

Version behaviour

`version`	Result
omitted	the latest published release
`1.2.3`	that exact npm version

Node.js

The recipe needs npm. If nodejs is declared first, that Node is used; otherwise the recipe installs the distribution’s Node.js and npm. Declare nodejs explicitly when you care which version Claude Code runs on.

Defaults come for free

Installing this devtool is enough to get Ringleader’s defaults; no toolconfigs entry is required, because one is synthesised for you.

Default	Why
Bypass-permissions mode	A workstation is the sandbox.
Background auto-updater off	Ringleader installs Claude Code globally as root and pins its version through the recipe. The updater runs as the workstation user, cannot write that prefix, and would move the workstation off the pinned version if it could — so it only ever printed an `Auto-update failed` warning on your status line.

Turning the background updater off does not take updating away: claude update still works as a manual escape hatch, and declaring a version (or changing it) is the declarative way to move a workstation.

To change either default, or to add MCP servers, settings, or trusted folders, add a claude-code toolconfig — what you declare there wins over the defaults.

Example

A browser-IDE workstation with Claude Code available in both the terminal and the editor panel, and OAuth logins relayed to your laptop’s browser:

apiVersion: workstations.ringleader.dev/v1
kind: WorkstationConfig
metadata:
  name: ai-box
  namespace: local
spec:
  selector:
    matchLabels:
      tier: dev
  identity:
    shell: /bin/bash
  packages:
    - git
    - curl
  devtools:
    - name: nodejs
    - name: claude-code
    - name: vscode-web
    - name: passthrough-www-browser
  ports:
    - 8080
  defaultLocalBinding:
    enabled: true
    autoForward:
      forwardAll: true
    urlForward:
      enabled: true
      open: true

claude login inside the workstation then opens its device-code URL in your browser.

Authenticating

Two options:

Interactively. rl shell <workstation> and run claude, or use the terminal in the browser IDE. Pair with passthrough-www-browser so the login URL opens on your laptop.
Non-interactively, by injecting an API key from a Secret into the workstation’s environment:
```
environment:
  ANTHROPIC_API_KEY: "${secret:anthropic-api-key}"
```

Notes

The binary lands on the system PATH, so it works for the login user and for root.
Claude Code is memory-hungry. A 1 GiB VM is not enough; give it at least a few GiB via providerConfig.
Works on Debian, Ubuntu, and Alpine.