> ## Documentation Index > Fetch the complete documentation index at: https://docs.cortex.foundation/llms.txt > Use this file to discover all available pages before exploring further. # Configuration > How Cortex CLI reads config.toml, the keys you can set, named profiles, and which layer wins when two files disagree. Cortex CLI keeps its settings in a TOML file. There is one for you, an optional one per repository, and a set of overrides you can pass on the command line. Between them they decide which model a session starts on, how much the agent may do without asking, how the terminal app looks, and how long a command may run before it is killed. This page covers where the files live, the order in which they are merged, the keys you can set in each section, and how named profiles let you keep several setups side by side. Permission and sandbox rules have their own page, and so do the environment variables that sit above the files in precedence. ## Where the config file lives | Scope | Location | | ---------------------- | -------------------------------------------- | | Yours, macOS and Linux | `~/.cortex/config.toml` | | Yours, Windows | `%USERPROFILE%\.cortex\config.toml` | | Project | `.cortex/config.toml` in the repository root | The Cortex home directory is resolved in this order: `CORTEX_CONFIG_DIR`, then `CORTEX_HOME`, then `~/.cortex`. `CORTEX_CONFIG` overrides the config file path outright, wherever the home directory ends up. Inside a project, Cortex looks for `.cortex/config.toml`, then `.cortex/config.json`, then `.cortex/config.jsonc`, then `cortex.toml`, `cortex.json` and `cortex.jsonc`. The first one it finds is the project config. Commit the project file when the settings belong to the repository rather than to you. ## Precedence Five layers, weakest first. A later layer overrides a key set by an earlier one. 1. Built-in defaults 2. Your own config, `~/.cortex/config.toml` 3. The profile selected with `-p` / `--profile`, or by `profile = ""` 4. The project config, `.cortex/config.toml` 5. The command line: `-c` / `--config KEY=VALUE`, repeatable, then the dedicated flags Environment variables sit between config files and command-line flags in precedence: a flag beats a variable, a variable beats a config file. See [Environment variables](/cli/environment-variables) for the full list. A project `.cortex/config.toml` beats your own `~/.cortex/config.toml`. Cloning a repository can therefore change your model, your sandbox mode and your approval policy without you touching anything. Run `cortex config` in a new clone to see the values that are actually in effect. ## Inspect and edit ```bash theme={null} cortex config # the effective configuration cortex config get cortex config set cortex config unset cortex config --json # the same, machine-readable cortex config --edit # edit it interactively cortex debug config # what is in effect, and which files it came from cortex debug doctor # check configuration, storage and required tools ``` From inside the terminal app, `/config` opens the same file and `/reload-config` re-reads configuration from disk. ## Keys ### Model | Key | Type | Notes | | -------------------------------- | ----------------------------------- | ----------------------------------------------------------------- | | `model` | string | Default model | | `model_provider` | string | Provider id | | `model_context_window` | integer | Override the assumed context window | | `model_auto_compact_token_limit` | integer | When to auto-compact the conversation | | `model_reasoning_effort` | `low`, `medium`, `high` | Reasoning effort | | `model_reasoning_summary` | `none`, `brief`, `detailed`, `auto` | How much reasoning is summarised | | `model_aliases` | table | Map your own short names to model ids | | `small_model` | string | Model used for cheap background work such as titles and summaries | | `providers` | table | Custom provider definitions | ### Permissions and sandboxing | Key | Values | Meaning | | --------------------- | ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- | | `approval_policy` | `untrusted`, `on-failure`, `on-request`, `never` | When to ask before running a tool. `on-request` is the default. | | `sandbox_mode` | `read-only`, `workspace-write`, `danger-full-access` | What the sandbox permits. `workspace-write` is the default. | | `trusted_directories` | array of paths | Read from both layers and merged, but nothing in this build consults the merged list. Do not rely on it to skip a prompt. | `[sandbox_workspace_write]` refines `workspace-write` with `writable_roots`, `network_access`, `exclude_tmpdir_env_var` and `exclude_slash_tmp`. The `[permission]` table sets per-capability and per-command policy. Both are documented on [Permission policy](/cli/policy). ### Behaviour | Key | Type | Meaning | | ----------------------------- | ------ | ---------------------------------------------- | | `instructions` | string | Extra instructions prepended to every session | | `current_agent` | string | Agent used by default | | `hide_agent_reasoning` | bool | Hide reasoning output | | `show_raw_agent_reasoning` | bool | Show reasoning verbatim | | `check_for_update_on_startup` | bool | Look for a new release on launch | | `disable_paste_burst` | bool | Turn off paste-burst detection in the composer | ### History ```toml theme={null} [history] persistence = "save-all" # or "none" max_bytes = 10000000 ``` ### Terminal app ```toml theme={null} [tui] animations = true notifications = true # Enter the alternate screen buffer. Set false to stay inline in the host # terminal. Equivalent flag: --no-alternate-screen alternate_screen = true [tui.theme] name = "dark" # dark, light, ocean_dark, monokai ``` The theme ids stay lowercase in config even though the picker shows friendlier names. See [Themes](/cli/themes). ### Execution ```toml theme={null} [execution] max_agent_threads = 4 max_tool_threads = 8 command_timeout_seconds = 120 http_timeout_seconds = 60 max_retries = 3 retry_delay_ms = 1000 streaming = true max_file_size_bytes = 10485760 max_batch_files = 100 verbose = false ``` Each of these has a flag: `--max-agent-threads`, `--max-tool-threads`, `--command-timeout`, `--http-timeout`, `--no-streaming`. ### Plugins Plugins are configured in the same file: ```toml theme={null} [[plugins]] name = "my-plugin" path = "~/.cortex/plugins/my-plugin" enabled = true priority = 0 granted_permissions = ["read_files", "network"] [plugins.config] api_key = "your-api-key" max_items = 20 ``` ## Profiles A profile is a named block that overrides top-level keys. Anything you can set at the top level you can set in a profile. ```toml theme={null} [profiles.review] model = "your-model-id" approval_policy = "never" sandbox_mode = "read-only" ``` Select it for one invocation with `-p review`, or set `profile = "review"` at the top level to make it your default. A profile sits below the project config, so a repository can still override it. Nothing in the CLI documentation states whether Cortex prompts you before honouring a repository's `.cortex/config.toml`. Treat an unfamiliar repository's config as something to read before you run a session in it. ## Related * [Environment variables](/cli/environment-variables) * [Data locations](/cli/data-locations) * [Permission policy](/cli/policy) * [Modes and permissions](/cli/modes-and-permissions) * [Themes](/cli/themes) * [CLI troubleshooting](/cli/troubleshooting)