Configuration reference

A Raw config is one strict JSON file. Unknown fields and duplicate keys are errors. Use raw config list to validate a file without starting a model.

File location

Raw reads one file:

Source	Used when
--config PATH	The flag is given. It replaces the default file.
$XDG_CONFIG_HOME/raw/config.json	XDG_CONFIG_HOME is set.
~/.config/raw/config.json	Otherwise.

A missing default file is allowed. A missing file named by --config is an error. raw config init creates the default file with mode 0600, and it never overwrites an existing file.

Agent selection

Raw picks the agent in this order:

1. --agent NAME
2. RAW_AGENT
3. default_agent

There are no direct flags for a provider, model, or base URL. An agent binds the model, endpoint, and credentials for its session.

Root fields

Field	Type	Default	Description
default_agent	string	None	Agent used when --agent and RAW_AGENT are absent.
models	object	{}	Model connections, keyed by a local alias. See Models.
agents	object	{}	Agents, keyed by name. See Agents.
mcp	object	None	{ "servers": { ... } }. See MCP servers.
vars	object	{}	Runtime variable declarations. See Variables.
var_providers	object	{}	Executable variable providers. See Variables.
ui	object	Defaults below	Terminal appearance. See UI.
sessions	object	{ "retention_days": 7 }	Session retention. Allowed only in the global config file. See Sessions.

Models

models.<alias> describes one upstream model connection. model_id is sent to the service unchanged.

Field	Type	Required	Default	Description
provider	string	Yes	None	The service or deployment name.
method	string	Yes	None	One of openai-chat-completions, openai-responses, anthropic-messages, or google-generate-content. Never inferred from the model name.
model_id	string	Yes	None	The exact model ID sent upstream.
base_url	string	No	Service default	Endpoint URL. Required for a custom service.
api_key	string	No	None	A literal key. Mutually exclusive with api_key_env.
api_key_env	string	No	None	Name of an environment variable holding the key.
context_window_tokens	positive integer	No	None	Context size used for estimates and compaction.
max_output_tokens	positive integer	No	None	Output token limit. Must be smaller than context_window_tokens when both are set.
vision	boolean	No	false	Allows the agent to select builtin/view_image.

Known services have default keys: OPENAI_API_KEY, ANTHROPIC_API_KEY, GEMINI_API_KEY or GOOGLE_API_KEY, and OPENROUTER_API_KEY. A local Ollama endpoint needs no key. A custom service needs an explicit base_url, and a key source if the endpoint requires one.

Caution

Store keys in an environment variable with api_key_env when you can. A literal api_key is written into the config file.

Agents

agents.<name> selects one model alias and sets how the agent runs.

Field	Type	Default	Description
model	string	Required	A key in models.
tools	object	Required	{ "use": [...], "rules": [...] }. See Tools.
skills	object	{ "use": [] }	{ "use": [...] }. See Skills.
hooks	object	{ "use": [] }	{ "use": [...] }. See Hooks.
vars	array of strings	[]	Exact names from the root vars. No wildcards.
max_steps	positive integer	10000	Maximum model requests in one turn.
max_output_bytes	positive integer	8192	Maximum size of a tool result sent to the model.
request_timeout_ms	positive integer	120000	Deadline for one model or MCP request.
system_prompt	string	Built-in prompt	Literal prompt text. An empty string is allowed. Cannot be combined with system_prompt_file.
system_prompt_file	string	None	Path to a UTF-8 Markdown file. Relative paths resolve from the config file’s directory.
request	object	None	Provider-specific request options. See the provider notes.
cache	object	None	Provider cache controls. See Cache.
compact	object	See below	Context compaction. See Compact.

The prompt is chosen in this order: --system-prompt, RAW_SYSTEM_PROMPT, the agent’s system_prompt or system_prompt_file, then the built-in prompt.

Numeric flags and RAW_* variables override the agent’s values, and the agent’s values override the built-in defaults.

Tools

tools.use lists tool IDs in the order the model sees them. An empty array gives the agent no tools.

ID form	Source
builtin/<name>	The installed Raw package.
local/<folder>	~/.config/raw/tools/<folder>/.
agent/<folder>	tools/<folder>/ beside the selected config file.
mcp/<server>/<tool>	A server in mcp.servers.
pkg/<alias>/tools/<export>	An installed package.

tools.rules is an ordered list. Each rule has these fields:

Field	Type	Description
match	string	Glob over the canonical tool ID. * matches any characters, ? matches one.
effect	allow, ask, or deny	The action.
when	object	Optional. Valid only with effect: "ask".

when has three fields: source (arguments), any (a dotted path with [*] array steps, such as commands[*].command), and regex (an RE2 pattern, unanchored). A rule with when asks when any matching string field matches the pattern.

The last matching rule wins. A tool with no matching rule runs without a prompt. deny removes the tool’s schema from the model.

Skills

skills.use lists skills by ID: builtin/<id>, local/<id>, agent/<id>, or pkg/<alias>/skills/<export>. A nonempty list requires both builtin/list_skills and builtin/load_skill in tools.use.

Hooks

hooks.use lists hooks in execution order: agent/<name>, local/<name>, or pkg/<alias>/hooks/<export>. See Hooks for the manifest and protocol.

Cache

cache accepts these fields. Each one applies only where the provider supports it.

Field	Type	Values
mode	string	auto or no-hints
key	string	OpenAI prompt cache key. A literal key here takes precedence over the key Raw generates.
retention	string	Supported for openai and anthropic providers only.
backend	string	generic or llama.cpp. llama.cpp requires the openai-chat-completions method.

Compact

compact controls how older context is summarized.

Field	Type	Default	Description
keep_recent_turns	non-negative integer	2	Recent turns kept as they are.
max_output_tokens	positive integer	512	Output limit for each summary request.
trigger_tokens	positive integer	None	Estimated input size that starts automatic compaction. Requires context_window_tokens on the model. Without it, compaction is manual.

MCP servers

mcp.servers.<name> defines a server. A server runs only when an agent selects one of its tools.

Field	Transport	Required	Description
transport	Both	Yes	stdio or streamable-http.
command	stdio	Yes	Program to start.
args	stdio	No	Arguments.
env	stdio	No	Environment variables for the process. Literal values.
url	streamable-http	Yes	Server endpoint.
headers	streamable-http	No	Request headers. Literal values.
panels	Both	No	Panel declarations for the server’s tools. Up to four per tool.

See MCP servers.

UI

The root ui object sets terminal appearance. Command-line flags override these fields.

Field	Type	Default	Values
density	string	normal	compact, normal, verbose
reasoning	string	summary, or full when density is verbose	hidden, summary, full
color	string	auto	auto, always, never
icons	string	auto	auto, unicode, ascii
theme	string	terminal	terminal, dark, light
palette	object	Built-in	Maps semantic roles to basic ANSI color names. See the terminal output notes.

Sessions

Field	Type	Default	Description
retention_days	positive integer	7	Days after the last committed conversation activity before a session expires.

This field is allowed only in the global config file. A file passed with --config that contains a sessions block is rejected, so a project file cannot change how long sessions are kept.

Expired sessions become unavailable immediately and are then deleted, with their history and payloads. Listing and viewing a session do not extend its life.

Sessions are stored at $XDG_STATE_HOME/raw/sessions.sqlite, or ~/.local/state/raw/sessions.sqlite when XDG_STATE_HOME is unset.

Package bindings

An agent can bind to an installed package agent instead of defining its own fields.

"researcher": {
  "from": "pkg/kit/agents/researcher",
  "model": "local",
  "inputs": { "region": "Hanoi" },
  "overrides": { "max_steps": 30 }
}

Field	Description
from	The package agent, as pkg/<alias>/agents/<export>.
model	Your model alias. Packages cannot set it.
inputs	Values for the package’s declared inputs.
overrides	Replacements for system_prompt, system_prompt_file, request, cache, compact, tools, skills, vars, max_steps, max_output_bytes, or request_timeout_ms. Each list or block is replaced in full.

raw agent add writes this binding for you. See Packages.

A complete example

{
  "default_agent": "coder",
  "models": {
    "local": {
      "provider": "ollama",
      "method": "openai-chat-completions",
      "model_id": "YOUR_INSTALLED_MODEL",
      "base_url": "http://127.0.0.1:11434/v1",
      "context_window_tokens": 32768,
      "vision": false
    },
    "hosted": {
      "provider": "deepseek",
      "method": "openai-chat-completions",
      "model_id": "YOUR_MODEL_ID",
      "base_url": "https://api.deepseek.com",
      "api_key_env": "DEEPSEEK_API_KEY",
      "context_window_tokens": 1048576
    }
  },
  "agents": {
    "coder": {
      "model": "local",
      "system_prompt_file": "prompts/coder.md",
      "tools": {
        "use": ["builtin/read_file", "builtin/write_file", "builtin/bash", "builtin/list_skills", "builtin/load_skill", "local/my_bash"],
        "rules": [
          {
            "match": "builtin/bash",
            "effect": "ask",
            "when": {
              "source": "arguments",
              "any": "commands[*].command",
              "regex": "(^|[;&|()\\n])\\s*rm(\\s|$)"
            }
          }
        ]
      },
      "skills": { "use": ["local/review"] },
      "hooks": { "use": ["agent/guard"] },
      "max_steps": 25,
      "max_output_bytes": 8192,
      "request_timeout_ms": 120000,
      "compact": { "keep_recent_turns": 2, "max_output_tokens": 512 }
    }
  },
  "ui": { "density": "normal", "theme": "terminal" }
}

Note

Run raw --config PATH config list after each edit. It checks the structure and references, and it does not contact a model or start any server.