codex | Ringleader Docs

Configures the Codex CLI by materialising ~/.codex/config.toml. Install Codex with the codex devtool.

The file is owned by the login user with mode 0600, because it may hold a provider API key.

`config` fields

Provide one of these. Ringleader does not interpret Codex’s settings; it only decides how to render them.

Field	Type	Description
`config`	`object`	A JSON object rendered to TOML. Wins if both are present.
`userConfig`	`object`	An alias for `config`.
`configToml`	`string`	A raw TOML document written verbatim. The escape hatch.

Structured form

toolconfigs:
  - id: codex
    name: codex
    config:
      config:
        model: o4-mini              # a top-level scalar
        some_section:               # an object becomes a [section] table
          key: value
          enabled: true

renders as:

model = "o4-mini"

[some_section]
enabled = true
key = "value"

The renderer supports exactly that shape: top-level scalar key = value pairs, then one level of [section] tables with their own scalar pairs. Key names are Codex’s, not Ringleader’s — nothing is validated or renamed. Keys are sorted, so the output is stable and re-applying identical input changes nothing.

Anything deeper — a nested table inside a section, an array of tables — is a clear error rather than silently-wrong TOML. Use configToml for those.

Verbatim form

toolconfigs:
  - id: codex
    name: codex
    config:
      configToml: |
        model = "o4-mini"

        [model_providers.openai]
        name = "OpenAI"
        base_url = "https://api.openai.com/v1"
        env_key = "OPENAI_API_KEY"

Whatever you write is what lands on disk, after secret references are resolved.

Workspace trust

Folders in sources[].path and trustedFolders are appended to the file as [projects."<absolute path>"] tables with trust_level = "trusted" — Codex’s own per-project trust lever. A path you have already declared yourself is left alone, so your configuration always wins.

This happens whenever the workstation declares any trusted folders, even with no codex toolconfig at all.

Example

apiVersion: workstations.ringleader.dev/v1
kind: WorkstationConfig
metadata:
  name: codex-box
  namespace: local
spec:
  selector:
    matchLabels:
      tier: dev
  identity:
    user: dev
  devtools:
    - name: nodejs
      version: "24"
    - name: codex
  toolconfigs:
    - id: codex
      name: codex
      config:
        configToml: |
          model = "o4-mini"
  sources:
    - name: app
      git:
        url: https://github.com/acme/app.git
      path: /home/dev/src/app     # appended as a trusted project

Notes

Codex has no managed (operator-enforced) layer here — a single user-owned file.
The file is rewritten every time the workstation applies its configuration, so edits made inside it revert.
Secret references are resolved before the file is rendered, in either form.

config fields