OpenGauss config.yaml Reference: All Settings and Defaults

OpenGauss stores all persistent settings in a single YAML file at ~/.gauss/config.yaml. Every key has a sensible default so the file starts minimal and you only add what you want to change. API keys and secrets are kept separate in ~/.gauss/.env — the config file never holds credentials.

Location and editing

The config directory defaults to ~/.gauss/. Set the GAUSS_HOME environment variable to move it anywhere:

export GAUSS_HOME=/srv/gauss   # config lives at /srv/gauss/config.yaml

Open the config in your $EDITOR with:

gauss config edit

Or set individual keys directly from the command line:

gauss config set model anthropic/claude-sonnet-4
gauss config set terminal.backend docker
gauss config set display.skin ares

API keys belong in ~/.gauss/.env, not in config.yaml. Running gauss config set OPENROUTER_API_KEY sk-or-... automatically routes the value to .env instead of the config file.

Full example

Below is an annotated config.yaml that shows every major section with its defaults. You only need to include the keys you want to change.

# ~/.gauss/config.yaml

# ── Model ──────────────────────────────────────────────────────────────────
model: "anthropic/claude-opus-4.6"

toolsets:
  - gauss-cli

# ── Agent behavior ─────────────────────────────────────────────────────────
agent:
  max_turns: 90

# ── Terminal backend ────────────────────────────────────────────────────────
terminal:
  backend: "local"           # local | docker | ssh | modal | singularity | daytona
  cwd: "."
  timeout: 180
  docker_image: "nikolaik/python-nodejs:python3.11-nodejs20"
  container_cpu: 1
  container_memory: 5120     # MB (5 GB)
  container_disk: 51200      # MB (50 GB)
  container_persistent: true
  persistent_shell: true
  docker_volumes: []
  docker_mount_cwd_to_workspace: false

# ── Browser ─────────────────────────────────────────────────────────────────
browser:
  inactivity_timeout: 120
  record_sessions: false

# ── Context compression ─────────────────────────────────────────────────────
compression:
  enabled: true
  threshold: 0.50
  summary_model: "google/gemini-3-flash-preview"
  summary_provider: "auto"

# ── Filesystem checkpoints ──────────────────────────────────────────────────
checkpoints:
  enabled: true
  max_snapshots: 50

# ── CLI handoff ─────────────────────────────────────────────────────────────
cli:
  handoff:
    mode: auto
    launchers: {}

# ── Auxiliary side-task models ──────────────────────────────────────────────
auxiliary:
  vision:
    provider: "auto"
    model: ""
    base_url: ""
    api_key: ""
  web_extract:
    provider: "auto"
    model: ""
    base_url: ""
    api_key: ""
  compression:
    provider: "auto"
    model: ""
    base_url: ""
    api_key: ""
  session_search:
    provider: "auto"
    model: ""
    base_url: ""
    api_key: ""

# ── Display / theme ─────────────────────────────────────────────────────────
display:
  compact: false
  personality: "kawaii"
  resume_display: "full"
  bell_on_complete: false
  show_reasoning: false
  show_cost: false
  skin: "default"

# ── Privacy ─────────────────────────────────────────────────────────────────
privacy:
  redact_pii: false

# ── Text-to-speech ──────────────────────────────────────────────────────────
tts:
  provider: "edge"           # edge | elevenlabs | openai
  edge:
    voice: "en-US-AriaNeural"
  elevenlabs:
    voice_id: "pNInz6obpgDQGcFmaJgB"
    model_id: "eleven_multilingual_v2"
  openai:
    model: "gpt-4o-mini-tts"
    voice: "alloy"

# ── Speech-to-text ──────────────────────────────────────────────────────────
stt:
  enabled: true
  provider: "local"          # local | groq | openai
  local:
    model: "base"            # tiny | base | small | medium | large-v3
  openai:
    model: "whisper-1"

# ── Voice input ─────────────────────────────────────────────────────────────
voice:
  record_key: "ctrl+b"
  max_recording_seconds: 120
  auto_tts: false
  silence_threshold: 200
  silence_duration: 3.0

# ── Memory ──────────────────────────────────────────────────────────────────
memory:
  memory_enabled: true
  user_profile_enabled: true
  memory_char_limit: 2200    # ~800 tokens
  user_char_limit: 1375      # ~500 tokens

# ── Subagent delegation ─────────────────────────────────────────────────────
delegation:
  model: ""
  provider: ""
  base_url: ""
  api_key: ""

# ── Approvals ───────────────────────────────────────────────────────────────
approvals:
  mode: "manual"             # manual | smart | off

Section reference

`gauss`

Top-level Gauss feature flags and integration settings.

gauss.compatibility.legacy_skill_surface

boolean

default:"false"

Enable the legacy skill invocation surface for older skill scripts.

gauss.compatibility.legacy_cli_surface

boolean

default:"false"

Enable the legacy CLI command surface for backward compatibility.

gauss.autoformalize.backend

string

default:"claude-code"

Backend used when autoformalizing agent outputs. Supported value: claude-code.

gauss.autoformalize.handoff_mode

string

default:"auto"

How autoformalization hands off to the backend: auto detects the best strategy.

gauss.autoformalize.auth_mode

string

default:"auto"

Authentication mode for the autoformalization backend.

gauss.autoformalize.managed_state_dir

string

default:""

Directory for managed autoformalization state. Defaults to the Gauss home directory.

gauss.project.template_source

string

default:""

URL or path to a project template used by /project setup.

`model`

model

string

default:"anthropic/claude-opus-4.6"

The default model for all agent conversations. Use provider/model-name format for OpenRouter and multi-provider setups. Switch at runtime with /model or gauss model.

`toolsets`

toolsets

list

default:"[\"gauss-cli\"]"

List of toolsets to enable. Use ["all"] for everything, or pick individual toolsets: web, terminal, file, browser, vision, image_gen, skills, todo, tts, cronjob, etc. Run gauss chat --list-toolsets to see all available options.

`agent`

agent.max_turns

integer

default:"90"

Maximum number of tool-calling iterations per conversation before the agent stops. Increase for long autonomous tasks; decrease to cap cost.

`terminal`

Controls which environment executes shell commands.

terminal.backend

string

default:"local"

Execution backend. One of local, docker, ssh, modal, singularity, or daytona.

terminal.cwd

string

default:"."

Working directory for terminal commands. For local: . resolves to wherever you launched gauss. For remote backends, use an absolute path inside the target environment.

terminal.timeout

integer

default:"180"

Default command timeout in seconds.

terminal.docker_image

string

default:"nikolaik/python-nodejs:python3.11-nodejs20"

Docker image used when backend: docker.

terminal.container_cpu

integer

default:"1"

CPU cores allocated to container backends (docker, singularity, modal, daytona).

terminal.container_memory

integer

default:"5120"

Memory in MB allocated to container backends. Default is 5 GB.

terminal.container_disk

integer

default:"51200"

Disk space in MB allocated to container backends. Default is 50 GB.

terminal.container_persistent

boolean

default:"true"

When true, the container filesystem persists across sessions. When false, the container resets on each session.

terminal.persistent_shell

boolean

default:"true"

Keep a long-lived bash shell across execute() calls so cwd, environment variables, and shell variables survive between commands. Always opt-in for local; enabled by default for SSH and container backends.

terminal.docker_volumes

list

default:"[]"

Host directories to mount into the container, in standard Docker -v syntax: ["host_path:container_path"]. Example: ["/home/user/projects:/workspace/projects"].

terminal.docker_mount_cwd_to_workspace

boolean

default:"false"

Explicitly mount the host launch directory into /workspace inside the container. Off by default to preserve sandbox isolation.

`browser`

browser.inactivity_timeout

integer

default:"120"

Seconds of inactivity before an open browser session is automatically closed.

browser.record_sessions

boolean

default:"false"

Automatically record browser sessions as WebM videos.

`cli`

cli.handoff.mode

string

default:"auto"

Terminal handoff mode for /handoff. One of auto, helper, or strict.

cli.handoff.launchers

object

default:"{}"

Named launchers for /handoff. Each key is a launcher name; the value is an object with argv, optional cwd, and optional env. Example:

cli:
  handoff:
    launchers:
      claude-continue:
        argv: ["claude", "--continue"]

`checkpoints`

checkpoints.enabled

boolean

default:"true"

Automatically snapshot the working directory before any destructive file operation. Use /rollback to restore a snapshot.

checkpoints.max_snapshots

integer

default:"50"

Maximum number of checkpoints to keep per directory. Older snapshots are pruned automatically.

`compression`

compression.enabled

boolean

default:"true"

Enable automatic context compression when the conversation approaches the model’s context limit.

compression.threshold

number

default:"0.50"

Fraction of the model’s context limit at which compression triggers. 0.50 means compress at 50% full.

compression.summary_model

string

default:"google/gemini-3-flash-preview"

Model used to generate the compressed summary. Should be a fast, cheap model with a large context window.

compression.summary_provider

string

default:"auto"

Provider for the summary model. auto picks the best available. Options: auto, openrouter, nous, main.

`auxiliary`

Auxiliary models handle lightweight side tasks — image analysis, web extraction, context compression, and session search. Each task has its own provider, model, base_url, and api_key fields. All default to "auto", which picks the best available provider at runtime.

auxiliary:
  vision:
    provider: "auto"     # auto | openrouter | nous | codex | custom
    model: ""            # leave empty for provider default
    base_url: ""         # direct OpenAI-compatible endpoint
    api_key: ""          # key for base_url (falls back to OPENAI_API_KEY)
  web_extract:
    provider: "auto"
    model: ""
  compression:
    provider: "auto"
    model: ""
  session_search:
    provider: "auto"
    model: ""

You normally don’t need to change auxiliary settings. They automatically use Gemini Flash via your active provider. Only override if you want a specific model for one side task — for example, a local vLLM endpoint for compression but OpenRouter for vision.

`display`

display.compact

boolean

default:"false"

Use the compact banner mode (shorter startup banner).

display.personality

string

default:"kawaii"

Default personality for the agent. Built-in options include kawaii, concise, technical, creative, pirate, noir, and many others. Define custom personalities under the personalities key.

display.resume_display

string

default:"full"

How to display resumed sessions. full shows the complete session history.

display.bell_on_complete

boolean

default:"false"

Ring the terminal bell when the agent finishes a response. Useful for long-running tasks.

display.show_reasoning

boolean

default:"false"

Display the model’s reasoning/thinking block above each response. Toggle at runtime with /reasoning show or /reasoning hide.

display.show_cost

boolean

default:"false"

Show the running token cost in the status bar.

display.skin

string

default:"default"

Active skin name. Built-in skins: default, ares, mono, slate, poseidon, sisyphus, charizard. Custom skins go in ~/.gauss/skins/<name>.yaml. Switch at runtime with /skin <name>.

`privacy`

privacy.redact_pii

boolean

default:"false"

When true, phone numbers are stripped and user/chat IDs are replaced with deterministic hashes before being sent to the model. Names and usernames are not affected.

`tts`

tts.provider

string

default:"edge"

Text-to-speech provider. Options: edge (free, Microsoft Edge TTS), elevenlabs (premium), openai.

tts.edge.voice

string

default:"en-US-AriaNeural"

Edge TTS voice name. Popular choices: AriaNeural, JennyNeural, AndrewNeural, BrianNeural, SoniaNeural.

tts.elevenlabs.voice_id

string

default:"pNInz6obpgDQGcFmaJgB"

ElevenLabs voice ID. The default is the “Adam” voice.

tts.elevenlabs.model_id

string

default:"eleven_multilingual_v2"

ElevenLabs model ID.

tts.openai.model

string

default:"gpt-4o-mini-tts"

OpenAI TTS model.

tts.openai.voice

string

default:"alloy"

OpenAI TTS voice. Options: alloy, echo, fable, onyx, nova, shimmer.

`stt`

stt.enabled

boolean

default:"true"

Enable speech-to-text voice input.

stt.provider

string

default:"local"

STT provider. local uses faster-whisper on your machine (free, no API key). groq uses the Groq Whisper API. openai uses the OpenAI Whisper API.

stt.local.model

string

default:"base"

Whisper model size for the local provider. Options: tiny, base, small, medium, large-v3. Larger models are more accurate but require more RAM and download time.

stt.openai.model

string

default:"whisper-1"

OpenAI transcription model. Options: whisper-1, gpt-4o-mini-transcribe, gpt-4o-transcribe.

`voice`

voice.record_key

string

default:"ctrl+b"

Keyboard shortcut to start/stop voice recording in the CLI.

voice.max_recording_seconds

integer

default:"120"

Maximum recording length before auto-stop.

voice.auto_tts

boolean

default:"false"

Automatically read agent responses aloud using the configured TTS provider.

voice.silence_threshold

integer

default:"200"

RMS amplitude below which audio is considered silence (0–32767 scale).

voice.silence_duration

number

default:"3.0"

Seconds of silence before the recording auto-stops.

`memory`

memory.memory_enabled

boolean

default:"true"

Enable the agent’s personal notes memory (MEMORY.md). Injected into the system prompt each session.

memory.user_profile_enabled

boolean

default:"true"

Enable the user profile memory (USER.md). Stores preferences, communication style, and learned facts about the user.

memory.memory_char_limit

integer

default:"2200"

Maximum characters for the agent’s notes memory (approximately 800 tokens at 2.75 chars/token).

memory.user_char_limit

integer

default:"1375"

Maximum characters for the user profile memory (approximately 500 tokens at 2.75 chars/token).

`approvals`

approvals.mode

string

default:"manual"

Approval mode for potentially dangerous commands. manual always prompts the user. smart uses an auxiliary LLM to auto-approve low-risk commands. off skips all prompts (equivalent to --yolo).

`delegation`

Overrides the provider and model used by delegate_task for spawned subagents.

delegation:
  model: "google/gemini-3-flash-preview"   # cheaper model for subagents
  provider: "openrouter"
  base_url: ""                             # custom endpoint (optional)
  api_key: ""                              # key for base_url (optional)

All provider options supported by the main CLI are also supported here.

`human_delay`

Simulates human-like typing delays for responses on messaging platforms.

human_delay.mode

string

default:"off"

Delay mode. off disables delays. natural adds variable delays automatically. custom uses the min_ms / max_ms range.

human_delay.min_ms

integer

default:"800"

Minimum delay in milliseconds (used in custom mode).

human_delay.max_ms

integer

default:"2500"

Maximum delay in milliseconds (used in custom mode).

`timezone`

timezone

string

default:""

IANA timezone name (e.g. "Asia/Kolkata", "America/New_York"). Empty string uses the server’s local time. Affects timestamps injected into the system prompt.

`security`

Controls optional pre-execution command scanning via tirith.

security.redact_secrets

boolean

default:"true"

Strip detected secrets (API keys, tokens) from command output before it reaches the model.

security.tirith_enabled

boolean

default:"true"

Enable tirith pre-execution scanning for homograph URLs, pipe-to-shell patterns, and terminal injection.

security.tirith_path

string

default:"tirith"

Path to the tirith binary. Supports ~ expansion.

security.tirith_timeout

integer

default:"5"

Scan timeout in seconds. Commands are allowed through if tirith takes longer than this.

security.tirith_fail_open

boolean

default:"true"

When true, commands proceed if tirith is unavailable or times out. Set to false to block commands when the scanner cannot run.

`discord`

Settings for the Discord gateway mode.

discord.require_mention

boolean

default:"true"

When true, the bot only responds in server channels when directly @mentioned.

discord.free_response_channels

string

default:""

Comma-separated channel IDs where the bot responds without needing an @mention.

discord.auto_thread

boolean

default:"true"

Automatically create a thread on @mention in server channels (similar to Slack behavior).

`personalities`

Define custom named personalities that can be activated with /personality <name>.

personalities:
  # String format: name → system prompt
  focused: "You are a focused assistant. Be brief and precise."

  # Dict format: name → {description, system_prompt, tone, style}
  analyst:
    description: "Data analyst persona"
    system_prompt: "You are a data analyst. Always back claims with numbers."

`command_allowlist`

command_allowlist

list

default:"[]"

List of shell command patterns permanently allowed without an approval prompt. Entries are added automatically when you choose “Always” in an approval dialog.

`prefill_messages_file`

prefill_messages_file

string

default:""

Path to a JSON file containing a list of {"role": "...", "content": "..."} messages injected at the start of every API call for few-shot priming. These messages are never saved to sessions or logs. Can also be set via GAUSS_PREFILL_MESSAGES_FILE.

Checking and migrating config

gauss config           # Show current effective configuration
gauss config check     # Check for missing or outdated keys
gauss config migrate   # Add new keys with defaults (interactive)
gauss config path      # Print the path to config.yaml

Get Started

Core Concepts

Configuration

Guides

OpenGauss config.yaml Reference: All Settings and Defaults

Location and editing

Full example

Section reference

`gauss`

`model`

`toolsets`

`agent`

`terminal`

`browser`

`cli`

`checkpoints`

`compression`

`auxiliary`

`display`

`privacy`

`tts`

`stt`

`voice`

`memory`

`approvals`

`delegation`

`human_delay`

`timezone`

`security`

`discord`

`personalities`

`command_allowlist`

`prefill_messages_file`

Checking and migrating config

Build docs developers (and LLMs) love

Get Started

Core Concepts

Configuration

Guides

Documentation Index

​Location and editing

​Full example

​Section reference

​gauss

​model

​toolsets

​agent

​terminal

​browser

​cli

​checkpoints

​compression

​auxiliary

​display

​privacy

​tts

​stt

​voice

​memory

​approvals

​delegation

​human_delay

​timezone

​security

​discord

​personalities

​command_allowlist

​prefill_messages_file

​Checking and migrating config

Build docs developers (and LLMs) love

Location and editing

Full example

Section reference

`gauss`

`model`

`toolsets`

`agent`

`terminal`

`browser`

`cli`

`checkpoints`

`compression`

`auxiliary`

`display`

`privacy`

`tts`

`stt`

`voice`

`memory`

`approvals`

`delegation`

`human_delay`

`timezone`

`security`

`discord`

`personalities`

`command_allowlist`

`prefill_messages_file`

Checking and migrating config