Configuration
Reference

Configuration

5. Configuration#

RayuCode v3 is configured in TOML at ~/.rayu/config.toml. There is one file, not a JSON settings hierarchy, and no settings.json merge chain.

Three ways to change it:

  1. In a session — /config shows the active configuration, /config init creates the default file, /config edit opens it in $EDITOR.
  2. By editing ~/.rayu/config.toml — every key below is optional.
  3. Per run, with flags — --model, --provider, --tool-profile, --tools, --disabled-tools, --mcp-tools, --no-update.

Environment overrides exist for the settings you would normally script: RAYU_TOOL_PROFILE, RAYU_TOOLS, RAYU_DISABLED_TOOLS, RAYU_WAKE_MODE, RAYU_BROWSER_HANDOFF, RAYU_HOOK_*, and the keybinding keys. Environment wins over the file.

Where Rayu stores state#

Everything user-level lives under ~/.rayu, unless RAYU_HOME or RAYU_CONFIG_DIR redirects it.

PathPurpose
config.tomlThe configuration file described on this page
sessions/Session transcripts, one JSON file per session
rayu-auth.jsonRayu account session (tokens refresh automatically)
providers.jsonProvider/credential metadata
mcp.jsonGlobal MCP server definitions
skills/Global skills (<name>/SKILL.md)
agents/Imported agent profiles
memory/Auto-memory store
plans/Saved plans
plugins/Plugin and marketplace cache
logs/Debug and trace logs
state/Durable coordination state (swarm plans, member records)
device.json, devices.jsonPaired devices for the iOS/web client

Provider API keys for third-party providers live one directory over, in ~/.config/rayucode/<provider>.env. When RAYU_HOME is set, that becomes $RAYU_HOME/config/rayucode.

The file, section by section#

toml
[cloud]
local_access_seconds = 86400

[session]
hibernation_idle_secs = 1800     # 0 disables idle hibernation
hibernation_mode = "caches"      # caches | transcript | exit

[server]
wake_mode = "internal"           # internal | external
mobile_push = true               # send mobile push when an account key exists

[features]
check_updates = true
memory = true
swarm = true
mermaid = true
auto_poke = true
message_timestamps = true
kv_cache_miss_notices = true
update_channel = "stable"         # stable | preview

[provider]
default_model = "deepseek-v4.1-flash-cloud"
default_provider = "rayu"
stream_idle_timeout_secs = 180
max_retries = 8
retry_backoff_cap_secs = 30
cross_provider_failover = "ask"

[display]#

The TUI look and interaction defaults. Most of these have a slash command that writes the same key.

KeyMeaning
diff_modeoff, inline, full-inline (default inline). /diff cycles it.
queue_modeSend without interrupting the running turn (default false). Ctrl+Tab.
auto_server_reloadReload the shared server when a newer binary appears.
mouse_captureMouse wheel scroll and click (default true). Disable to keep native text selection.
debug_socketEnable the debug socket.
emojiRender emoji.
centeredCenter the conversation column. /alignment.
show_thinkingShow reasoning by default. /thinking-display.
compact_thinkingDrop blank rows before thinking.
diagram_modenone, margin, pinned.
markdown_spacingcompact or document.
show_link_urlsAppend link destinations after labels.
latex_renderingimage, unicode, or none. /latex.
pin_imagesPin read images to the side pane.
pin_todosPin the todo list.

[tools]#

Controls which tools the model can see.

toml
[tools]
profile = "full"          # full | acp | minimal | lite | none
enabled = []              # explicit allow-list; [] means the profile decides
disabled = []             # remove these after the profile is applied
disable_base_tools = false
mcp_tools = "auto"        # auto | eager | deferred
codemode = true
browser_handoff = false
auto_background_timeout_ms = 3000

The same keys map to CLI flags: --tool-profile, --tools, --disabled-tools, --disable-base-tools, --mcp-tools. mcp_tools = "auto" advertises MCP tool names up front and loads schemas on demand; eager sends every schema immediately; deferred fetches schemas with a tool search first.

[agents]#

Model policy for spawned work.

toml
[agents]
swarm_model = "deepseek-v4.1-flash-cloud"  # omit/"inherit" to follow the parent
swarm_model_selection = false              # allow the agent to choose worker models
swarm_model_allowlist = []                 # strict allowlist when selection is on
swarm_model_autoselect = true
swarm_effort = "low"
profile_setup_hint = true

[[agents.profiles]]
name = "fast-edit"
model = "deepseek-v4.1-flash-cloud"
notes = "Mechanical multi-file edits"

[hooks]#

External commands at fixed lifecycle points. See Hooks for the contract, the variables, and the exit-code rules.

toml
[hooks]
turn_start = "~/bin/rayu-turn-busy"
turn_end = "~/bin/rayu-turn-notify"
session_start = ""
session_end = ""
pre_tool = "~/bin/rayu-tool-policy"          # exit 2 blocks the tool
post_tool = ""
post_tool_feedback = ""                       # stdout is fed back to the model
pre_tool_transform = ""
pre_tool_timeout_ms = 5000
post_tool_feedback_timeout_ms = 10000
pre_tool_transform_timeout_ms = 500

Every key accepts a string or an array of strings, and every key has an environment override (RAYU_HOOK_TURN_START, RAYU_HOOK_PRE_TOOL, …).

[ambient]#

See CLI reference → Ambient mode.

[providers.<name>]#

Named OpenAI-compatible profiles, created by rayu provider add:

toml
[providers.my-gateway]
type = "openai-compatible"
base_url = "https://llm.example.com/v1"
api_key_env = "MY_GATEWAY_API_KEY"
default_model = "qwen3-coder"

Use with --provider-profile my-gateway.

Keybindings, dictation, power, notifications#

toml
[keybindings]
side_panel_toggle = "alt+m"
new_terminal = "alt+shift+;"
voice_input = "ctrl+space"

[dictation]
command = ""
mode = "send"
key = "off"
timeout_secs = 90

[power]
prevent_sleep_while_streaming = true

Run /keys to see which bindings collide with your terminal and OS, and /terminal-setup to fix Shift+Enter in terminals that need it.

Project-level configuration#

~/.rayu/config.toml is user-level. Project-level instructions are markdown, not config: AGENTS.md, RAYU.md, .rayu/RAYU.md, RAYU.local.md, and the optional .rayu/prompt-overlay.md. MCP servers can be project-scoped in ./.mcp.json or ./.rayu/mcp.json. See Memory & project instructions.

Legacy ~/.rayu/settings.json and .rayu/settings.json from the Node v2 CLI are still read for compatibility (plans directory, extra skill dirs, effort level, fast mode, and similar), but v3 never writes them. New settings belong in config.toml.

Migrating from Node v2#

When v3 first starts after an upgrade it:

  • reads ~/.rayu/settings.json read-only if it exists,
  • reads legacy credentials from ~/.rayu/providers.json,
  • imports known provider keys from the environment,
  • keeps your sessions and ~/.rayu intact.

Nothing in ~/.rayu is deleted by the upgrade.

Next: CLI Reference →