Configuration

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.

Built-in defaults
Your own config, ~/.cortex/config.toml
The profile selected with -p / --profile, or by profile = "<name>"
The project config, .cortex/config.toml
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 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

cortex config                # the effective configuration
cortex config get <KEY>
cortex config set <KEY> <VALUE>
cortex config unset <KEY>
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.

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

[history]
persistence = "save-all"   # or "none"
max_bytes = 10000000

Terminal app

[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.

Execution

[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:

[[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.

[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.

Get started

Use the CLI

Automate

Configure

Extend

Reference

Where the config file lives

Precedence

Inspect and edit

Keys

Model

Permissions and sandboxing

Behaviour

History

Terminal app

Execution

Plugins

Profiles

​Where the config file lives

​Precedence

​Inspect and edit

​Keys

​Model

​Permissions and sandboxing

​Behaviour

​History

​Terminal app

​Execution

​Plugins

​Profiles

​Related

Where the config file lives

Precedence

Inspect and edit

Keys

Model

Permissions and sandboxing

Behaviour

History

Terminal app

Execution

Plugins

Profiles

Related