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.

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
  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 the lowest-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 and --theme / theme, which track whether the flag was explicitly passed on the command line. --yolo / YOLO and --hide-tool-results / hide_tool_results don't: they're plain booleans with no "was this explicitly set" tracking, so passing --yolo=false or --hide-tool-results=false cannot turn a saved YOLO: true / 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 either on (--yolo, --hide-tool-results) works as expected regardless of the saved setting.
• Aliases sit between CLI flags and user settings. An alias (docker agent alias add ...) can bundle its own yolo, 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.