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

# Codex CLI on Tensormesh

> Drive open-weight models with stock OpenAI Codex CLI against Tensormesh — sign up, configure, and run in 5 minutes.

Get stock [Codex CLI](https://www.npmjs.com/package/@openai/codex) driving open-weight models against Tensormesh in 5 minutes. Every Tensormesh serverless model supports the full Codex flow today (chat + tool use); `MiniMaxAI/MiniMax-M2.5` is the recommended default.

## Quick Links

<CardGroup cols={3}>
  <Card title="Sign up / Log in" icon="user-plus" href="https://app.tensormesh.ai/login">
    Create your Tensormesh account with Google or GitHub.
  </Card>

  <Card title="Get an API key" icon="key" href="https://app.tensormesh.ai/profile?tab=api">
    Generate an `ak-...` key under **Profile → API keys**.
  </Card>

  <Card title="Install Codex CLI" icon="download" href="https://www.npmjs.com/package/@openai/codex">
    `npm install -g @openai/codex` — verified against Codex 0.128+.
  </Card>

  <Card title="Supported models" icon="list" href="#supported-models">
    Full matrix of Codex-ready models on Tensormesh serverless.
  </Card>

  <Card title="Get support" icon="envelope" href="mailto:saas-support@tensormesh.ai">
    Email [saas-support@tensormesh.ai](mailto:saas-support@tensormesh.ai) for help.
  </Card>
</CardGroup>

## TL;DR

Three steps — install the CLI, configure the provider, set the API key — then run `codex`. Step 2 has an ordering constraint (top-level keys must precede any `[section]` header); see [Setup](#setup) below if you have an existing `~/.codex/config.toml`.

```bash theme={null}
# Step 1 — install Codex CLI (skip if already installed)
npm install -g @openai/codex

# Step 2 — configure the Tensormesh provider in ~/.codex/config.toml.
#         Safe only if the file is missing or empty. If you already have
#         a config.toml, see Step 2 in the Setup section below.
cat > ~/.codex/config.toml <<'EOF'
# Top-level keys (must come before any [section] header)
model_provider = "tensormesh"
model = "MiniMaxAI/MiniMax-M2.5"
model_reasoning_effort = "medium"

[model_providers.tensormesh]
name = "tensormesh"
base_url = "https://serverless.tensormesh.ai/v1"
wire_api = "responses"
env_key = "TENSORMESH_INFERENCE_API_KEY"
EOF

# Step 3 — set your API key (add to ~/.zshrc or ~/.bashrc to persist)
export TENSORMESH_INFERENCE_API_KEY=ak-...

# Run it
codex
```

That's the full setup — no third-party tooling installed, no PATH addition. [Setup](#setup) below walks through the same three steps in detail (and the merge-into-existing-config case).

## Prerequisites

* **Codex CLI** installed via `npm install -g @openai/codex`. Verified against `0.128.0` through `0.131.0` (chat + tool use end-to-end); forward-compatible with later versions barring upstream Codex breaking changes.
* **A Tensormesh account** with an API key (`ak-...`). [Sign up](https://app.tensormesh.ai/login), then visit [Profile → API keys](https://app.tensormesh.ai/profile?tab=api).
* **macOS or Linux**, bash or zsh. Windows binaries ship in Codex 0.131+ but aren't currently tested by Tensormesh.

<Note>
  You do **not** need to run `codex login`. The provider's `env_key` field tells Codex to read your API key from the environment variable directly; the OAuth login flow is for OpenAI-hosted models only.
</Note>

<Note>
  You do **not** need to run any local infrastructure. Tensormesh handles Codex compatibility server-side, so stock `codex` pointed at `serverless.tensormesh.ai` (per the TL;DR above) is the complete setup.
</Note>

## Supported models

| Model                                     | Codex CLI status  | Notes                                   |
| ----------------------------------------- | ----------------- | --------------------------------------- |
| `MiniMaxAI/MiniMax-M2.5`                  | ✓ chat + tool use | Recommended default; 192K context       |
| `openai/gpt-oss-120b`                     | ✓ chat + tool use | Reasoning + tools, 128K context         |
| `openai/gpt-oss-20b`                      | ✓ chat + tool use | Reasoning + tools, 128K context         |
| `Qwen/Qwen3-235B-A22B`                    | ✓ chat + tool use | Reasoning + tools, 40K context          |
| `Qwen/Qwen3-30B-A3B`                      | ✓ chat + tool use | Reasoning + tools, 40K context          |
| `Qwen/Qwen3-Coder-30B-A3B-Instruct`       | ✓ chat + tool use | Coding-tuned, 256K context              |
| `Qwen/Qwen3-Coder-480B-A35B-Instruct-FP8` | ✓ chat + tool use | Coding-tuned, 256K context              |
| `mistralai/Devstral-2-123B-Instruct-2512` | ✓ chat + tool use | Mistral-architecture coder, 32K context |
| `moonshotai/Kimi-K2.6`                    | ✓ chat + tool use | Reasoning + tools, 32K context          |

<Tip>
  `GET /v1/models` reflects what's currently available — Tensormesh hides any model that's temporarily cold. If you see fewer models than the table lists, retry after 30–60 seconds; the first request to a cold model warms it up.
</Tip>

For non-Codex clients (Python SDK, curl, custom apps), every model in the table works fine via `/v1/chat/completions` as well. Codex CLI specifically cannot fall back to that wire (see [openai/codex#7782](https://github.com/openai/codex/discussions/7782) for OpenAI's rationale), which is why the matrix above is Codex-CLI specific.

## Switching models

The Codex TUI's `/model` picker only shows OpenAI's built-in lineup (`gpt-5.5`, `gpt-5.4`, …) — Tensormesh model slugs aren't in it. Likewise, the *"GPT-5.5 is now available"* tip on launch refers to models you can't use here. **Press Esc to dismiss the picker** and switch models via one of the methods below.

This is a Codex CLI limitation that affects every third-party provider; it's not specific to Tensormesh.

### Per-invocation (no config edit)

```bash theme={null}
codex -m MiniMaxAI/MiniMax-M2.5                       # MiniMax (recommended default)
codex -m openai/gpt-oss-120b                          # reasoning, large
codex -m openai/gpt-oss-20b                           # reasoning, small
codex -m Qwen/Qwen3-235B-A22B                         # reasoning, 40K
codex -m Qwen/Qwen3-30B-A3B                           # reasoning, 40K
codex -m Qwen/Qwen3-Coder-30B-A3B-Instruct            # coder, 256K
codex -m Qwen/Qwen3-Coder-480B-A35B-Instruct-FP8      # coder, 256K
codex -m mistralai/Devstral-2-123B-Instruct-2512      # Mistral coder
codex -m moonshotai/Kimi-K2.6                         # Kimi reasoning
```

`-m` is a per-invocation override; your `config.toml` default is unchanged. Equivalent long form: `codex -c 'model="..."'`.

### Change the default

Edit `~/.codex/config.toml` and update the `model = ` line, or use sed:

```bash theme={null}
sed -i '' 's|^model = ".*"|model = "Qwen/Qwen3-Coder-480B-A35B-Instruct-FP8"|' ~/.codex/config.toml
```

(Drop the empty-string argument from `-i` on Linux: `sed -i 's|...|' ~/.codex/config.toml`.)

### Optional: shell aliases for frequent switching

If you switch models often, add aliases to your `~/.zshrc` (zsh) or `~/.bashrc` (bash):

```bash theme={null}
alias tm-mini='codex -m MiniMaxAI/MiniMax-M2.5'
alias tm-gpt='codex -m openai/gpt-oss-120b'
alias tm-qwen='codex -m Qwen/Qwen3-235B-A22B'
alias tm-coder='codex -m Qwen/Qwen3-Coder-480B-A35B-Instruct-FP8'
alias tm-coder-small='codex -m Qwen/Qwen3-Coder-30B-A3B-Instruct'
alias tm-devstral='codex -m mistralai/Devstral-2-123B-Instruct-2512'
alias tm-kimi='codex -m moonshotai/Kimi-K2.6'
```

Reload your shell, then run `tm-coder` from any directory to start a Codex session against that model. Exit codex (`/exit` or Ctrl-D twice) and run a different alias to switch.

## Setup

The three steps from the TL;DR, with explanation.

<Steps>
  <Step title="Install Codex CLI">
    ```bash theme={null}
    npm install -g @openai/codex
    ```

    This installs the `codex` command to your global `node_modules/bin`. Verify with `codex --version`.
  </Step>

  <Step title="Configure the Tensormesh provider">
    Codex reads provider configuration from `~/.codex/config.toml`. Add this content:

    ```toml theme={null}
    # Top-level keys (must come before any [section] header)
    model_provider = "tensormesh"
    model = "MiniMaxAI/MiniMax-M2.5"
    model_reasoning_effort = "medium"

    [model_providers.tensormesh]
    name = "tensormesh"
    base_url = "https://serverless.tensormesh.ai/v1"
    wire_api = "responses"
    env_key = "TENSORMESH_INFERENCE_API_KEY"
    ```

    The first three keys make Tensormesh + MiniMax + medium reasoning the default for every `codex` invocation. The `[model_providers.tensormesh]` block defines the provider those defaults reference. You can override per-invocation with `-c`.

    <Warning>
      **TOML ordering matters.** The `model_provider`, `model`, and `model_reasoning_effort` keys are top-level — they must appear in the file **before any `[section]` header** (TOML doesn't reset table context on blank lines, so anything below a `[header]` belongs to that section).
    </Warning>

    <Tabs>
      <Tab title="Fresh config (file missing or empty)">
        Just paste the block as-is — the TL;DR's `cat > ~/.codex/config.toml` does this.
      </Tab>

      <Tab title="Merge into existing config">
        If you already use Codex with another provider (OpenAI direct, Azure, etc.), open `~/.codex/config.toml` in your editor and merge:

        1. Put the three top-level `model_*` keys at the top of the file, replacing your previous defaults if any (the keys must be unique in TOML — you can't have two `model_provider` lines).
        2. Put the `[model_providers.tensormesh]` section anywhere below the top-level keys; it's additive and won't conflict with other `[model_providers.<other>]` sections.

        To switch back to your other provider for a single run, use `-c 'model_provider="openai"'` (or whichever you've configured) — no config edit needed.
      </Tab>
    </Tabs>
  </Step>

  <Step title="Set your API key">
    ```bash theme={null}
    export TENSORMESH_INFERENCE_API_KEY=ak-...
    ```

    Add this to `~/.zshrc` (zsh) or `~/.bashrc` (bash) to persist across sessions. The API key prefix selects environment: `ak-dev-...` for dev, `ak-staging-...` for staging, `ak-live-...` for production.

    Don't have a key yet? [Generate one in your profile](https://app.tensormesh.ai/profile?tab=api).
  </Step>
</Steps>

## Usage

```bash theme={null}
# Interactive TUI (works in any directory)
codex

# One-shot prompt — note the </dev/null. Without it, codex exec also reads
# from stdin even when the prompt is in argv, and appears to hang waiting
# for EOF (Ctrl-D). Redirecting stdin tells codex "argv is the full input".
codex exec --skip-git-repo-check "say pong" </dev/null

# Interactive, auto-approve commands, writes allowed in workspace
codex -s workspace-write -a never

# Interactive, full network + unrestricted shell (use only on a trusted machine)
codex --dangerously-bypass-approvals-and-sandbox

# Resume the most recent session (see footgun note below)
codex exec resume --last --skip-git-repo-check "follow-up question" </dev/null
```

### Slash commands in TUI

Inside an interactive `codex` session, **type `/`** to bring up the command picker (autocomplete). `/help` is **not** a valid command — typing it gives `Unrecognized command '/help'`.

A few that customers reach for most often:

| Command    | What it does                                  |
| ---------- | --------------------------------------------- |
| `/status`  | Session config + token usage display          |
| `/compact` | Manually summarize history to free up context |
| `/init`    | Generate an `AGENTS.md` for the current repo  |
| `/diff`    | Show git diff in the conversation             |
| `/copy`    | Copy the last response as markdown            |
| `/exit`    | Quit cleanly (also `Ctrl-D` twice)            |

For the full list of slash commands available in your installed version, type `/` and arrow through the picker.

### Sandbox / approval modes

Codex defaults to a strict sandbox: read-only, no network, prompts before each shell command. Three modes are available:

| Mode                                         | Network | Shell approval                               | When to use                                            |
| -------------------------------------------- | ------- | -------------------------------------------- | ------------------------------------------------------ |
| *(no flag)*                                  | no      | Prompts before each command                  | Reading code, exploring; safest                        |
| `-s workspace-write -a never`                | no      | Auto-approves; writes allowed inside workdir | Normal coding; the most common daily mode              |
| `--dangerously-bypass-approvals-and-sandbox` | yes     | Auto-approves all commands; no sandbox       | Only on a trusted machine, for prompts you've reviewed |

For `codex exec` (non-interactive), the `-a never` flag is implicit, so just `codex exec -s workspace-write` is sufficient.

The `-s workspace-write` and `--dangerously-bypass-approvals-and-sandbox` configurations are mutually exclusive in effect — `workspace-write` sandboxes filesystem writes and disables network. If you need network access for a tool, use the bypass flag.

<Note>
  Codex CLI 0.128.0 removed the older `--full-auto` shortcut. Use `-s workspace-write` (+ `-a never` for interactive) instead. If you copy a snippet that uses `--full-auto`, Codex will error with `unexpected argument '--full-auto' found`.
</Note>

### Resume gotcha — `--last` orders by file mtime

`codex exec resume --last` picks the session whose JSONL file was most recently modified, **not** the one most recently created. So if you just touched an older session (even by reading or resuming it once), that session — not your latest one — wins `--last`. To target a specific session, pass its UUID explicitly:

```bash theme={null}
codex exec resume <session-uuid> --skip-git-repo-check "follow-up" </dev/null
```

Session UUIDs are listed in `~/.codex/sessions/YYYY/MM/DD/rollout-*.jsonl` filenames.

### Recommended settings

* **`model_reasoning_effort = "medium"`** is the empirical sweet spot for MiniMax-M2.5. The full set Codex accepts is `none` / `minimal` / `low` / `medium` / `high` / `xhigh`. Against MiniMax-M2.5, `high` does not consistently improve output quality, costs more latency, and occasionally produces self-contradicting reasoning chains in long generations. Use `none` or `minimal` only when you specifically want to skip the model's reasoning step. **This recommendation is calibrated only for MiniMax-M2.5.** For the other supported models, `medium` is a reasonable starting point but not validated; experiment if you're optimizing for a specific workload.
* **Stay in `-s workspace-write` for most coding work.** Switch to the bypass flag only for tasks that need network access (e.g., fetching docs, hitting an API).

## Known cosmetic issues

### "Model metadata not found" warning in TUI

When you run interactive `codex` (TUI), you'll see this between every user message and the model's response:

```
⚠ Model metadata for `<your-model-slug>` not found. Defaulting to
  fallback metadata; this can degrade performance and cause issues.
```

**This is cosmetic. Functionality is unaffected.** Codex CLI ships a built-in registry of OpenAI's own models (`gpt-5.5`, `gpt-5.4`, …); when it sees a slug that isn't in the registry it falls back to default metadata and emits this warning. Tensormesh model slugs (MiniMax, Qwen3, etc.) are not in OpenAI's registry, so the warning fires for every supported model here.

The warning **does not appear** in `codex exec` (non-interactive) runs — only in TUI. It's a Codex CLI behavior, not a Tensormesh behavior; the same applies to every other third-party provider.

### Auto-compact threshold

Codex automatically compacts conversation history when it approaches the model's context window. The exact trigger varies per model, and the threshold is configurable via Codex's `auto_compact_token_limit` setting:

| Model                                                                | Context window |
| -------------------------------------------------------------------- | -------------- |
| `MiniMaxAI/MiniMax-M2.5`                                             | 192K (196,608) |
| `openai/gpt-oss-120b` / `gpt-oss-20b`                                | 128K (131,072) |
| `Qwen/Qwen3-235B-A22B` / `Qwen3-30B-A3B`                             | 40K (40,960)   |
| `Qwen/Qwen3-Coder-30B-A3B-Instruct` / `Coder-480B-A35B-Instruct-FP8` | 256K (262,144) |
| `mistralai/Devstral-2-123B-Instruct-2512`                            | 32K (32,768)   |
| `moonshotai/Kimi-K2.6`                                               | 32K (32,768)   |

If you're using a 40K-window model, expect compaction to fire much earlier in long sessions than on a 192K MiniMax run.

**What you'll see when it fires:**

* In **TUI mode**: a visible "compacting..." event between turns.
* In **`exec` mode**: silent — the compact-trigger turn just takes longer (around 30–60 seconds extra) and the next turn proceeds with the compressed context. No explicit message is printed.

**What's preserved vs lost** when compaction fires:

* ✓ Preserved: the **topical context** of the conversation (documents you've fed to Codex, the high-level task you're working on).
* ✗ Lost: **specific conversational facts you told Codex** ("remember the codeword BLUEFISH42"). After compaction, Codex sees a summary of earlier turns, not the verbatim history. If specific recall matters for your workflow, plan for compaction or split into fresh sessions.

To trigger compaction manually before reaching the threshold, type `/compact` in the TUI. Otherwise, start a fresh session.

## Troubleshooting

<Note>
  When a request fails, Codex retries five times before surfacing the cause:

  ```
  ERROR: Reconnecting... 1/5
  ERROR: Reconnecting... 2/5
  ... (3/5, 4/5, 5/5)
  ERROR: <the actual cause — this is the line to read>
  ```

  The five `Reconnecting...` lines are noise. The meaningful error is the line immediately after `5/5`.
</Note>

| Symptom (substring of the meaningful error line)                                                                                                      | Likely cause                                                                                                                                                                                                       | Fix                                                                                                                                                                                                                                                                            |
| ----------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `command not found: codex`                                                                                                                            | Codex CLI not installed                                                                                                                                                                                            | `npm install -g @openai/codex`                                                                                                                                                                                                                                                 |
| `Missing environment variable: TENSORMESH_INFERENCE_API_KEY`                                                                                          | Variable not exported in the current shell                                                                                                                                                                         | `export TENSORMESH_INFERENCE_API_KEY=ak-...`; persist in `~/.zshrc` / `~/.bashrc`                                                                                                                                                                                              |
| `We're currently experiencing high demand, which may cause temporary errors` *(after 5 retries)*                                                      | Most often an **invalid or wrong-environment API key** (auth failures are reported as 5xx, which Codex retries before surfacing). Less often, a transient capacity event.                                          | Verify your key against your account and confirm the `ak-<env>-...` prefix matches your target environment. Quick check: `curl -sS -H "Authorization: Bearer $TENSORMESH_INFERENCE_API_KEY" https://serverless.tensormesh.ai/v1/models`. If it errors, the key is the problem. |
| `404 Not Found` / `Model '<slug>' not found` *(or)* `400 Bad Request` / `The '<slug>' model is not supported when using Codex with a ChatGPT account` | Wrong model slug, or `base_url` typo in `config.toml`. The 404 means Tensormesh doesn't recognize the slug; the 400 is from Codex CLI itself rejecting the slug before sending it. Both mean "fix the model name." | Compare your `~/.codex/config.toml` against the snippet in [Setup](#setup); `curl $base_url/models` to list what's actually available; or check the [Supported models](#supported-models) matrix.                                                                              |
| `404 Not Found` / `Model '<slug>' not found` *but* the slug appears in `curl $base_url/models`                                                        | The model is temporarily cold (no instance running).                                                                                                                                                               | Wait 30–60 seconds and retry — a request will warm the model. After warm-up, subsequent requests are typically under 5 seconds.                                                                                                                                                |
| `Operation not allowed: read-only` (mid-session)                                                                                                      | Codex's default sandbox is read-only                                                                                                                                                                               | Restart with `codex -s workspace-write -a never` for normal coding, or `codex --dangerously-bypass-approvals-and-sandbox` for full access.                                                                                                                                     |
| `error: unexpected argument '--full-auto' found`                                                                                                      | Codex 0.128.0 removed `--full-auto`                                                                                                                                                                                | Use `-s workspace-write -a never` (interactive) or `-s workspace-write` (`codex exec`).                                                                                                                                                                                        |
| `Maximum context length is 196608 tokens` *(or model-specific limit)*                                                                                 | Conversation grew past the model's context window                                                                                                                                                                  | Type `/compact` in TUI, or start a new session.                                                                                                                                                                                                                                |
| `codex exec` appears to hang printing `Reading additional input from stdin...`                                                                        | Codex's exec mode reads stdin even when the prompt is in argv                                                                                                                                                      | Add `</dev/null` to the command, or press Ctrl-D in the terminal to close stdin.                                                                                                                                                                                               |

Still stuck? Email [saas-support@tensormesh.ai](mailto:saas-support@tensormesh.ai) with the meaningful error line (the one after `5/5`) and the output of `codex --version`.

## Rollback / uninstall

To remove Tensormesh from your Codex setup:

1. Delete the `[model_providers.tensormesh]` block (and the three top-level `model_provider` / `model` / `model_reasoning_effort` lines if you added them) from `~/.codex/config.toml`.
2. Unset `TENSORMESH_INFERENCE_API_KEY` and remove from `~/.zshrc` / `~/.bashrc`.

All actions reverse the setup steps above.