Configure CMX

Most people only need CONFIG in the terminal interface:

cmx

Use it to inspect discovered clients, connect a provider, disconnect one, and change local display or compression preferences. Restart a coding client after its routing settings change. For command-line control, use cmx providers <client> list, connect, and disconnect; see the CLI reference.

Where settings live

CMX’s own configuration is config.json in the following directory:

Operating system	Default configuration	Default local data
Linux	`~/.config/cmx/config.json`	`~/.local/share/cmx/`
macOS	`~/Library/Application Support/cmx/config.json`	`~/Library/Application Support/cmx/`
Windows	`%APPDATA%\cmx\config.json`	`%LOCALAPPDATA%\cmx\`

Linux respects XDG_CONFIG_HOME and XDG_DATA_HOME. The data directory holds local state such as usage records, cached summaries, and connection metadata. The CMX provider map stays in CMX’s config.json when client routing is restored; it is not a backup of your coding client’s settings. CMX uses JSON, not cmx.config.toml. A small example of the relevant fields is:

{
  "gateway": { "listen_addr": "127.0.0.1:17322" },
  "compression": {
    "min_context_tokens": 1000,
    "preserve_tail_tokens": 1000
  }
}

CMX fills in other defaults when loading its configuration. Keep the gateway on loopback. Do not place provider API keys in this file. Use the native coding client or its environment for credentials. After editing CMX settings, restart the gateway with cmx restart and restart affected coding clients if their routes changed.

Compression controls

The default minimum context is 1,000 estimated tokens per request, and the recent protected tail is 1,000 tokens. CMX also requires sufficient eligible context and a proposal that passes policy and economics checks; reaching the minimum alone does not guarantee a summary. Key compression fields in config.json include:

Key	Description	Default
`min_context_tokens`	Minimum context size before summarization is evaluated.	`1000`
`preserve_tail_tokens`	Recent tokens always preserved verbatim for current work.	`1000`
`safety_margin_tokens`	Minimum net token savings required before applying a summary.	`128`
`max_rounds_per_request`	Maximum internal compression rounds per request (range `1`–`8`).	`8`
`max_island_tokens`	Maximum token size of a contiguous compressible span.	`16000`
`max_summary_tokens`	Maximum tokens requested for an island summary output.	`1500`
`cache_max_entries`	In-memory LRU summary cache capacity.	`64`
`cache_ttl`	In-memory summary retention duration (e.g. `"24h"`).	`"24h"`
`summary_block_ttl`	Suppression window after an upstream 403 rejection (e.g. `"10m"`).	`"10m"`

The CONFIG screen can enable selected local optimizations, including duplicate tool-output pruning (deduplicate), removal of historical error output (purge_errors), truncation of long tool output (truncate_tools), stripping eligible historical thinking (strip_thinking), and the local content vault (vault). In config.json, mechanical pruning passes can be configured under compression:

{
  "compression": {
    "deduplicate": {
      "enabled": false,
      "min_output_tokens": 200,
      "excluded_tools": ["bash"],
      "skip_when_cache_control": true
    },
    "purge_errors": {
      "enabled": false,
      "turns": 4,
      "skip_when_cache_control": true
    },
    "vault": {
      "enabled": false,
      "max_entries": 10000
    }
  }
}

deduplicate.min_output_tokens: Smallest tool result worth replacing (default 200). Outputs below this size are untouched. apply_patch is always excluded.
purge_errors.turns: Minimum user turns after an error before tool inputs become eligible for rewrite (default 4, must be >= 1).
skip_when_cache_control: When true (default), requests carrying prompt cache breakpoints pass through untouched to protect upstream provider caching.
vault.enabled: Enables lossless archiving of removed tool content, truncated output, and stripped thinking blocks into local SQLite. Default false.
vault.max_entries: Maximum items retained in the vault before oldest entries are pruned automatically (default 10000).

The lossless vault is off by default; when enabled, it archives original content from selected prune or truncate actions in the local SQLite store. Review Security and data handling before enabling it. See Content vault for management commands. The default protected tool list includes task, skill, todowrite, todoread, write, edit, and apply_patch. Recent context, instructions, opaque content, and complete protected tool exchanges are also safeguarded by policy. See How compression works.

Gateway lifecycle

cmx start      # background process for this user
cmx status
cmx stop       # restore managed client routes, then stop

cmx start launches a detached process. It does not automatically install a login service. If restoration fails during cmx stop, CMX keeps the gateway running and reports the client conflict. While the gateway is stopped, your connected coding agents keep working on their direct connections. The next cmx start routes them through CMX again, as long as their configuration hasn’t changed since the stop.

Get started

Clients and providers

Setup and configuration

Using CMX

CLI reference

Help

Configure CMX

Configure CMX

Where settings live

Compression controls

Gateway lifecycle

​Configure CMX

​Where settings live

​Compression controls

​Gateway lifecycle

Configure CMX

Where settings live

Compression controls

Gateway lifecycle