# Configuration reference > Every field in a Raw config file, with its type, default, and meaning, for models, agents, tools, skills, hooks, variables, MCP servers, UI, and sessions. 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](#models). | | `agents` | object | `{}` | Agents, keyed by name. See [Agents](#agents). | | `mcp` | object | None | `{ "servers": { ... } }`. See [MCP servers](#mcp-servers). | | `vars` | object | `{}` | Runtime variable declarations. See [Variables](https://raw.tlelabs.com/docs/extend/variables/). | | `var_providers` | object | `{}` | Executable variable providers. See [Variables](https://raw.tlelabs.com/docs/extend/variables/). | | `ui` | object | Defaults below | Terminal appearance. See [UI](#ui). | | `sessions` | object | `{ "retention_days": 7 }` | Session retention. Allowed only in the global config file. See [Sessions](#sessions). | ## Models `models.` 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.` 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](#tools). | | `skills` | object | `{ "use": [] }` | `{ "use": [...] }`. See [Skills](#skills). | | `hooks` | object | `{ "use": [] }` | `{ "use": [...] }`. See [Hooks](#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](https://github.com/lploc94/raw-cli/blob/main/docs/providers.md). | | `cache` | object | None | Provider cache controls. See [Cache](#cache). | | `compact` | object | See below | Context compaction. See [Compact](#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/` | The installed Raw package. | | `local/` | `~/.config/raw/tools//`. | | `agent/` | `tools//` beside the selected config file. | | `mcp//` | A server in `mcp.servers`. | | `pkg//tools/` | 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/`, `local/`, `agent/`, or `pkg//skills/`. A nonempty list requires both `builtin/list_skills` and `builtin/load_skill` in `tools.use`. ### Hooks `hooks.use` lists hooks in execution order: `agent/`, `local/`, or `pkg//hooks/`. See [Hooks](https://raw.tlelabs.com/docs/extend/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.` 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](https://raw.tlelabs.com/docs/extend/mcp/). ## 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](https://github.com/lploc94/raw-cli/blob/main/docs/terminal-output.md). | ## 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. ```json "researcher": { "from": "pkg/kit/agents/researcher", "model": "local", "inputs": { "region": "Hanoi" }, "overrides": { "max_steps": 30 } } ``` | Field | Description | | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `from` | The package agent, as `pkg//agents/`. | | `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](https://raw.tlelabs.com/docs/extend/packages/). ## A complete example ```json { "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.