Configure CMX

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": 8000,
    "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 8,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 compression passes are evaluated.	8000
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 in the TUI (or cmx config) allows configuring 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 CMX, Zero-Cost Mode and mechanical pruning passes are enabled by default and fail open:

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

• zero_cost_mode: When true (default), runs zero-cost mechanical pruning and compaction passes before evaluating LLM-based summarization.
• 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 true.
• vault.max_entries: Maximum items retained in the vault before oldest entries are pruned automatically (default 10000).

The lossless vault is on by default; it safely archives original content from mechanical prune or truncate actions in the local SQLite store so no information is lost permanently. See Content vault for management commands.

The default protected tool list includes task, subagent, skill, and todowrite. Recent context, instructions, opaque content, and complete protected tool exchanges are also safeguarded by policy. See How compression works.

Gateway lifecycle and autostart

cmx start          # background process for this user
cmx restart        # safely restart the gateway daemon
cmx status         # check gateway listener and statistics
cmx stop           # restore managed client routes, then stop
cmx autostart enable   # configure automatic launch on system boot
cmx autostart status   # check background service status

cmx start launches a detached background process. cmx autostart enable configures a platform-native background service (systemd user unit on Linux, launchd agent on macOS, or Run registry key on Windows).

If restoration fails during cmx stop, CMX keeps the gateway running and reports the client conflict to prevent leaving tools pointed at an offline port.

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.