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:
- In a session —
/configshows the active configuration,/config initcreates the default file,/config editopens it in$EDITOR. - By editing
~/.rayu/config.toml— every key below is optional. - 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.
| Path | Purpose |
|---|---|
config.toml | The configuration file described on this page |
sessions/ | Session transcripts, one JSON file per session |
rayu-auth.json | Rayu account session (tokens refresh automatically) |
providers.json | Provider/credential metadata |
mcp.json | Global 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.json | Paired 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#
[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.
| Key | Meaning |
|---|---|
diff_mode | off, inline, full-inline (default inline). /diff cycles it. |
queue_mode | Send without interrupting the running turn (default false). Ctrl+Tab. |
auto_server_reload | Reload the shared server when a newer binary appears. |
mouse_capture | Mouse wheel scroll and click (default true). Disable to keep native text selection. |
debug_socket | Enable the debug socket. |
emoji | Render emoji. |
centered | Center the conversation column. /alignment. |
show_thinking | Show reasoning by default. /thinking-display. |
compact_thinking | Drop blank rows before thinking. |
diagram_mode | none, margin, pinned. |
markdown_spacing | compact or document. |
show_link_urls | Append link destinations after labels. |
latex_rendering | image, unicode, or none. /latex. |
pin_images | Pin read images to the side pane. |
pin_todos | Pin the todo list. |
[tools]#
Controls which tools the model can see.
[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 = 3000The 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.
[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.
[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 = 500Every 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:
[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#
[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 = trueRun /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.jsonread-only if it exists, - reads legacy credentials from
~/.rayu/providers.json, - imports known provider keys from the environment,
- keeps your sessions and
~/.rayuintact.
Nothing in ~/.rayu is deleted by the upgrade.
Next: CLI Reference →