User Settings

Full reference for the global settings block in your user config file.

Where Settings Live

Docker Agent reads a single user-level config file, independent of any agent YAML:

~/.config/cagent/config.yaml

The settings: block inside it holds preferences that apply to every agent you run — appearance, behavior, notifications, and a few global safety defaults. Everything under settings: is optional; an unset field falls back to the documented default.

# ~/.config/cagent/config.yaml
settings:
  theme: dracula
  lean: false
  sound: true

You rarely need to hand-edit this file. Most fields are managed from the TUI's /settings dialog (Appearance, Behavior, Notifications tabs) — press Enter there to apply and persist a change. A few fields (permissions, hooks, keybindings) have no dialog UI and are only set by editing the file directly.

Note

This page documents settings:. The user config file also has top-level sections outside settings: — aliases:, providers:, board:, credential_helper:, sandbox_allowlist: — which are not covered here.

Settings Reference

Layout Settings

layout customizes the TUI's sidebar. The zero value (an omitted layout: block, or any field left out) is the default: sidebar on the right, every section visible, normal spacing.

settings:
  layout:
    sidebar_position: left
    section_spacing: compact
    hide_usage: true

Complete Example

# ~/.config/cagent/config.yaml
settings:
  theme: auto
  theme_dark: dracula
  theme_light: default-light
  lean: false
  expand_thinking: false
  split_diff_view: true
  render_images: true
  hide_tool_results: false
  sound: true
  sound_threshold: 10
  snapshot: true
  cache_stable_prompts: true
  warn_on_cache_miss: true
  busy_send_mode: queue
  interrupt_confirmation: double-tap
  restore_tabs: true
  tab_title_max_length: 24
  layout:
    sidebar_position: right
    section_spacing: normal
  permissions:
    deny:
      - "shell:cmd=sudo*"
    allow:
      - "read_*"
  hooks:
    session_start:
      - type: command
        command: "~/.config/cagent/hooks/session-start.sh"
  keybindings:
    - action: "commands"
      keys: ["f2", "ctrl+k"]

Precedence Rules

User settings are a low-priority source: they establish defaults, and anything more specific wins.

• CLI flags over user settings — except plain boolean flags going from true to false. Where a docker agent run flag mirrors a setting, passing the flag for a specific run takes precedence over the setting for that run only, and the flag never modifies the saved user config file. This holds cleanly for --lean / lean, --theme / theme, and the safety flags --safety / --yolo (see below), which track whether the flag was explicitly passed on the command line. --hide-tool-results / hide_tool_results doesn't: it's a plain boolean with no "was this explicitly set" tracking, so passing --hide-tool-results=false cannot turn a saved hide_tool_results: true setting off for that run — the saved true wins and is reapplied on top of the flag. Passing the flag to turn it on works as expected regardless of the saved setting.
• Safety has its own, fully-specified chain. For a new session the first source in this order wins: explicit --safety flag > explicit --yolo flag > alias safety/yolo option > settings.safety/settings.YOLO > the agent YAML's agents.<name>.safety > the agent YAML's runtime.safety > the built-in default (read-only tools auto-approve, everything else asks). At each scope the safety field wins over the legacy YOLO/yolo boolean. Your settings therefore beat anything an agent author declared in YAML — an agent config loaded from a file, URL, or OCI registry can never override your settings.safety, alias option, or CLI flag. An explicit --yolo=false suppresses a saved YOLO: true / alias yolo for that run (other settings and YAML defaults still apply). Resumed sessions keep their stored mode: settings and alias defaults never touch them; only an explicit --safety or --yolo flag overrides a resume. See Safety Modes.
• Aliases sit between CLI flags and user settings. An alias (docker agent alias add ...) can bundle its own yolo, safety, model, hide_tool_results, and sandbox defaults; those apply when the corresponding flag was not explicitly passed, the same way user settings do, but are resolved after user settings so an alias's own choices take priority over your global defaults.
• Permissions are merged, not overridden. Global settings.permissions and an agent's own permissions: are combined into a single set of deny → allow → ask patterns before evaluation — a global deny always blocks, regardless of what the agent config allows. See Merging Behavior.
• Hooks are additive, not overridden. For a given lifecycle event, hooks from the agent config, settings.hooks, hooks.d/ drop-ins, and --hook-* CLI flags all run, in that order. Global hooks cannot be suppressed by an individual agent.
• Everything else is a plain default. Fields with no CLI or agent-config equivalent (sound, sound_threshold, restore_tabs, tab_title_max_length, split_diff_view, render_images, cache_stable_prompts, warn_on_cache_miss, busy_send_mode, keybindings, layout) only ever come from settings: (or the /settings dialog that writes it) — there is nothing to override them per run.