> ## Documentation Index
> Fetch the complete documentation index at: https://docs.compressi.us/llms.txt
> Use this file to discover all available pages before exploring further.

# Configure the CMX Gateway, Agents, and Preferences

> Manage CMX connections, gateway settings, and preferences through the terminal UI CONFIG menu or the cmx.config.toml file. Covers all config keys.

CMX is configured through its interactive terminal UI (run `cmx`) and a local config file (`cmx.config.toml`). Most users only need the CONFIG menu to connect agents and adjust preferences. Advanced users can edit the config file directly to tune gateway behavior such as compression thresholds and protected tools.

## Using the Terminal UI

Run `cmx` in your terminal to open the interactive interface. From here you can navigate menus, manage connections, and monitor live activity without touching any config files.

Keyboard shortcuts for navigating the UI:

| Key                 | Action                         |
| ------------------- | ------------------------------ |
| `Tab` or arrow keys | Move focus between elements    |
| `Enter` or click    | Select the focused item        |
| `Esc`               | Go back to the previous screen |
| `M`                 | Toggle mouse capture           |

## CONFIG Menu

Open the CONFIG menu from the main CMX interface to manage all connection and preference settings.

From CONFIG you can:

* **Connect or disconnect coding agents** — set up Codex, OpenCode, or any other supported agent to route its requests through the CMX gateway.
* **Choose a provider per agent** — select which model provider each agent should use when connecting through CMX.
* **Adjust preferences** — toggle live activity display, enable reduced motion, and control automatic update checks.

Each provider listed in CONFIG shows its current connection status and available actions. Changes take effect immediately in the UI, though the connected agent typically needs a restart before it picks up the new routing.

## Config File (cmx.config.toml)

CMX stores its gateway configuration in a local `cmx.config.toml` file. Most settings are managed automatically by the terminal UI, but you can edit this file directly for fine-grained control.

```toml theme={null}
# CMX gateway configuration
port = 17322
min_context_tokens = 32000
preserve_tail_tokens = 12000
protected_tools = ["task", "skill", "write", "edit"]
client = ""
provider = ""
```

Each key controls a specific aspect of gateway behavior:

* **`port`** — the local port CMX listens on. Default is `17322`. Your coding agent must point to this port when routing through CMX.
* **`min_context_tokens`** — the session must exceed this token count before CMX considers compression. Default is `32000`. Short conversations below this threshold are passed through unchanged.
* **`preserve_tail_tokens`** — the most recent portion of context, up to this token count, is always kept intact and never compressed. Default is `12000`.
* **`protected_tools`** — tool calls matching these names, and their results, are never compressed. Defaults cover `task`, `skill`, `write`, and `edit`. Add any other tool names you want to protect.
* **`client`** — the coding agent currently connected to CMX. Set automatically when you connect an agent through CONFIG.
* **`provider`** — the model provider used for the connected agent. Set automatically through CONFIG.

<Note>
  Changes to `cmx.config.toml` take effect after restarting CMX. Run `cmx stop` followed by `cmx start` to apply updated settings.
</Note>

## Background Service

CMX can run as a background process so it is always available during coding sessions without occupying a terminal window.

```bash theme={null}
# Start CMX in the background
cmx start

# Stop the background process
cmx stop
```

`cmx start` launches the gateway process in the background. `cmx stop` shuts it down cleanly. CMX does not install an auto-start service — you need to run `cmx start` again after a reboot if you want the gateway running.

To run CMX in the foreground in the current terminal instead, use `cmx serve`.


## Related topics

- [Connect Any OpenAI or Anthropic Agent to CMX Gateway](/providers/custom-agents.md)
- [Uninstall and Purge CMX on Linux, macOS, and Windows](/uninstall.md)
- [CMX Frequently Asked Questions: Pricing, Privacy, and Agents](/faq.md)