> ## Documentation Index > Fetch the complete documentation index at: https://sambanova-systems.mintlify.site/docs/llms.txt > Use this file to discover all available pages before exploring further. # Codex integration guide [Codex](https://github.com/openai/codex) is an open-source AI coding agent that runs in the terminal. It can read, modify, and execute code across local repositories, helping developers automate development workflows, debug issues, implement features, and interact with codebases through natural language commands. ## Overview This guide shows how to wire the [OpenAI Codex CLI](https://developers.openai.com/codex/) to a SambaNova-hosted model via the [Responses API](https://sambanova.ai/blog/build-faster-coding-agents-with-sambanovas-responses-api), then try it on three real demos, including one that uses an MCP server for live library docs. ## How it works Codex CLI is built around two ideas: **`[model_providers.*]`** lets you point it at any OpenAI-compatible endpoint, and **`--profile`** lets you swap the active model and provider with one flag. Together they make the **planner / executor** pattern from the SambaNova blog feel native: one profile for the frontier planner (`gpt-5`, `o3`, etc.), another for `MiniMax-M2.7` as the cheap, fast executor. SambaNova exposes a `/v1/responses` endpoint that matches Codex's `wire_api = "responses"` exactly, so no LiteLLM proxy is required. ## Prerequisites * **Node.js ≥ 18** on PATH. * **Codex CLI** installed: `npm i -g @openai/codex` (or `brew install --cask codex`). * **SambaNova API key** exported as `SAMBANOVA_API_KEY`. * *(For Demos 2 and 3)* an OpenAI API key registered with Codex for the frontier planner profile (see below). Sanity check: ```bash theme={null} codex --version && [ -n "$SAMBANOVA_API_KEY" ] && echo "SambaNova OK" ``` ### Register your OpenAI key for the frontier planner (Demos 2 and 3) The `plan` profile uses Codex's built-in `openai` provider, which authenticates from `~/.codex/auth.json`. Let Codex write that file for you by exporting your key and piping it into `codex login`: ```bash theme={null} export OPENAI_API_KEY="sk-…your-key-here…" printenv OPENAI_API_KEY | codex login --with-api-key ``` Confirm it's stored (and which auth mode is active): ```bash theme={null} codex login status # or: codex doctor ``` > Already logged into Codex with a stale key from a past login? Run `codex logout` first, then re-run the `codex login --with-api-key` command above after setting up your OpenAI API key. > Skipping the frontier planner entirely (using `plan-sn`)? You don't need an OpenAI key at all, since `plan-sn` goes through the SambaNova provider. ## Wire up SambaNova Codex reads `~/.codex/config.toml`. Add a SambaNova provider and two profiles, one for planning and one for execution: **`~/.codex/config.toml`** (append; don't replace your existing block): ```toml theme={null} [model_providers.sambanova] name = "SambaNova" base_url = "https://api.sambanova.ai/v1" env_key = "SAMBANOVA_API_KEY" wire_api = "responses" # --- frontier planner (default OpenAI provider) --- [profiles.plan] model_provider = "openai" model = "gpt-5" approval_policy = "on-request" sandbox_mode = "workspace-write" # --- SambaNova planner --- [profiles.plan-sn] model_provider = "sambanova" model = "gpt-oss-120b" approval_policy = "on-request" sandbox_mode = "workspace-write" # --- SambaNova executor --- [profiles.execute-sn] model_provider = "sambanova" model = "MiniMax-M2.7" approval_policy = "on-request" sandbox_mode = "workspace-write" ``` > `wire_api = "responses"` is what makes this work directly. SambaNova's `/v1/responses` endpoint matches the OpenAI Responses API shape Codex sends. If you've seen older guides recommend LiteLLM as a proxy, you don't need it. Then create one demo workspace and reuse it across all three demos: ```bash theme={null} mkdir -p ~/sambanova-codex-demo && cd ~/sambanova-codex-demo ``` *** ## Demo 1: SambaNova end to end A pet-friendly "hello world" landing page, built and verified entirely by `MiniMax-M2.7` via the `execute-sn` profile. ```bash theme={null} codex --profile execute-sn "Create a minimalist, pet-friendly 'hello world' landing page in this directory. One index.html, one style.css, no JS frameworks. Soft pastel palette, a friendly paw-print emoji, a short tagline ('Hello, friend'), and a single call-to-action button. Keep it under 80 lines of HTML+CSS combined. Open the file when done so I can preview it." ``` Verify: ```bash theme={null} open index.html ``` That's the **SN-only** baseline. One model, one profile, one call. *** ## Demo 2: Frontier plans, SambaNova executes The architect/builder split: the `plan` profile (frontier model) writes a precise `PLAN.md`; `execute-sn` (MiniMax-M2.7) carries it out. `PLAN.md` is the artifact that crosses the boundary: reproducible, swappable, and reviewable. **Step 1. Plan with the frontier model:** ```bash theme={null} codex --profile plan "Read index.html and style.css in this directory. Write PLAN.md describing how to extend this landing page into a 'pet adoption finder' demo: - A gallery of 6 placeholder pet cards (name, species, one-line bio) in CSS grid - A search input that filters cards by name (vanilla JS, no frameworks) - A dark-mode toggle that persists in localStorage Include exact file layout, the JS event handlers needed, and a verification checklist a human can run in the browser. Don't modify any code yet." ``` Open `PLAN.md` and review. Edit it freely; that's the point of materializing the plan. **Step 2. Hand `PLAN.md` to SambaNova:** ```bash theme={null} codex --profile execute-sn "Read PLAN.md and execute every step. After each step, list which acceptance criteria from the plan are now satisfied. Open index.html at the end so I can verify in the browser." ``` **Step 3. Verify:** ```bash theme={null} open index.html ``` You should see the gallery, working search, and a working dark-mode toggle. The executor never sees the planner's conversation; `PLAN.md` is its entire spec. Tweak `PLAN.md` and rerun the same `--profile execute-sn` command, or swap the planner profile for `plan-sn` (no frontier) without rewriting the plan. > Want SambaNova on both sides? `codex --profile plan-sn …` for the planner uses `gpt-oss-120b` instead of OpenAI. Useful when you don't want any frontier dependency. *** ## Demo 3: MCP-fed planning with live library docs Demo 2, plus an MCP server. The planner uses [**Context7**](https://github.com/upstash/context7) to fetch *current* docs for a library, bakes them into `PLAN.md`, and MiniMax executes. This solves the "model trained on stale docs" problem without writing custom retrieval. ### Install Context7 as an MCP server Free API key from [context7.com/dashboard](https://context7.com/dashboard), then export it: ```bash theme={null} export CONTEXT7_API_KEY=ctx7sk-… ``` Register Context7 in `~/.codex/config.toml`: ```toml theme={null} [mcp_servers.context7] command = "npx" args = ["-y", "@upstash/context7-mcp"] env = { "CONTEXT7_API_KEY" = "${CONTEXT7_API_KEY}" } ``` > Free tier works without the key; drop the `env` line and you'll just hit lower rate limits. The MCP server is now available to **every** profile. Confirm: ```bash theme={null} codex --profile plan "List the tools you can call from the context7 MCP server." ``` You should see `resolve-library-id` and `query-docs`. ### The task Stamp each pet card from Demo 2 with a human-readable "Added *X* days ago" label, computed at page load with [date-fns](https://date-fns.org/) (`formatDistanceToNow`). date-fns is a good Context7 target: its v2→v3 rewrite changed how it's imported (tree-shakeable named exports, a new UMD `cdn.min.js` build) and v4 added time-zone support, so models routinely emit stale default-import patterns that don't run. ### Step 1: `plan` profile fetches current docs and writes the plan ```bash theme={null} codex --profile plan "Use the context7 MCP server to look up current docs for the 'date-fns' library, specifically formatDistanceToNow with the addSuffix option, and how to load date-fns in a plain browser page via its UMD CDN build (the dateFns global) vs ESM named imports. Then update PLAN.md with a section 'Phase 2: relative date labels' describing how to give each pet card a fixed data-added ISO date and render an 'Added X days ago' label from it on load. Use the up-to-date API from Context7, not what you remember. Quote the exact