ISOLATED_CODEX_HOME

Codex setup

Use Codex CLI with BRUCEAI. An OpenAI key gives you GPT-6.1 Sol, GPT-6 Astra / Sol / Luna, GPT-5.6 Sol / Terra / Luna and GPT-5.5.

To avoid touching your existing Codex or ChatGPT login, put the BRUCEAI config in a separate folder and isolate it with CODEX_HOME. Your personal ~/.codex stays unchanged and your normal codex command keeps working.

Grok and DeepSeek work in Codex the same way; just swap in the matching key and model id. See the Grok and DeepSeek guides on the left. If you would rather not edit files by hand, the CC Switch guide on the left offers a one-click import.

Model IDs

Copy these model IDs into config files, API request bodies, or any OpenAI-compatible client that asks for a model name. Each group needs the matching key type.

GPTNeeds an OpenAI key

GrokNeeds a Grok key

DeepSeekNeeds a DeepSeek key

BEFORE YOU START

Prepare your API key

1. Open the API key page

After signing in, open the API key page to create or copy a key. It looks like sk-or-v1-xxxxxxxxxxxx. Treat it like a password.

Create API key

3. Confirm the Base URL

https://api.bruceai.net/v1

Codex uses the OpenAI-compatible interface, so this Base URL must include /v1.

2. Create a key for the provider you want

Click Create API key, give it a name you will recognize, then pick the key type by the models you plan to call:

OpenAI key: Serves gpt-6.1-sol, gpt-6-astra, gpt-6-sol, gpt-6-luna, gpt-5.6-sol, gpt-5.6-terra, gpt-5.6-luna and gpt-5.5. Works with Codex, GitHub Copilot and any OpenAI-compatible client.
Grok key: Serves grok-4.7, grok-4.6 and grok-4.5. Works with Grok Build, Codex and any OpenAI-compatible client.
DeepSeek key: Serves deepseek-v4.1-flash: 1M context, thinking mode, tool calling and image input. Works with Codex and any OpenAI-compatible client.

A key only serves its own provider's models. Sending a GPT model id with a Grok key, or a Grok id with an OpenAI key, is refused with a 400. Create one key per provider if you use several.

Do not share your API key with anyone, and do not commit it to GitHub, GitLab, or any public repository.

Choose your system first

The commands below switch to the system you choose.

STEP 01

Install and verify Codex CLI

Run npm install only if Codex CLI is not installed yet, then confirm with codex --version.

On an Ubuntu server, switch to Node.js 22 with NVM first so node and npm come from the same environment. After npm install, add the global bin directory to PATH and refresh the command cache; otherwise the install can succeed while the shell still reports codex not found.

NVM install guide

macOS / Linux

bash

node -v
npm -v
npm install -g @openai/codex@latest

hash -r
command -v codex
codex --version

If Ubuntu prints “Command 'codex' not found” and suggests Snap, do not run snap install codex. Select Ubuntu server, finish the PATH setup, and make sure command -v codex resolves to the npm-installed binary.

STEP 02

Create an isolated config folder

macOS / Linux

bash

mkdir -p ~/.codex-bruceai

STEP 03

Open config.toml

Open config.toml with the command below. If the file does not exist, the editor will create it.

macOS / Linux

bash

nano ~/.codex-bruceai/config.toml

STEP 04

Paste config.toml contents

Paste the full content below into config.toml. The default model is gpt-5.6-terra, a balance of capability and cost; you can switch any time with /model inside Codex. In Windows Notepad, press Ctrl+S to save, then close the window.

New to nano? Follow these steps to edit, save, and exit

1Edit: after running the nano command in the previous step, paste the entire code block below into the editor. Use Command+V in macOS Terminal; on Linux, use Ctrl+Shift+V or right-click and select Paste. Do not use Ctrl+V because nano treats it as Page Down.
2Make changes: move the cursor with the arrow keys, then remove text with Backspace or Delete. Replace any placeholder that says your key with your own API key, keeping the existing quotes and brackets.
3Save: hold Control and press the letter O (Ctrl+O, not the number 0). When “File Name to Write” appears at the bottom, leave the filename unchanged and press Enter.
4Exit: after nano returns to the editor, press Ctrl+X to return to the terminal. If “Save modified buffer?” appears, the changes are not saved yet; press Y, then Enter to save and exit.

toml

model_provider = "OpenAI"
model = "gpt-5.6-terra"
model_reasoning_effort = "high"
disable_response_storage = true

[model_providers.OpenAI]
name = "OpenAI"
base_url = "https://api.bruceai.net/v1"
wire_api = "responses"
requires_openai_auth = true

STEP 05

Open auth.json

Open auth.json with the command below, then prepare to paste your OpenAI key.

macOS / Linux

bash

nano ~/.codex-bruceai/auth.json

STEP 06

Paste auth.json contents

Replace sk-or-v1-your-key with the OpenAI key you created on the API key page. auth.json is a secret; never commit it to Git. In Windows Notepad, press Ctrl+S to save, then close the window.

New to nano? Follow these steps to edit, save, and exit

1Edit: after running the nano command in the previous step, paste the entire code block below into the editor. Use Command+V in macOS Terminal; on Linux, use Ctrl+Shift+V or right-click and select Paste. Do not use Ctrl+V because nano treats it as Page Down.
2Make changes: move the cursor with the arrow keys, then remove text with Backspace or Delete. Replace any placeholder that says your key with your own API key, keeping the existing quotes and brackets.
3Save: hold Control and press the letter O (Ctrl+O, not the number 0). When “File Name to Write” appears at the bottom, leave the filename unchanged and press Enter.
4Exit: after nano returns to the editor, press Ctrl+X to return to the terminal. If “Save modified buffer?” appears, the changes are not saved yet; press Y, then Enter to save and exit.

json

{ "OPENAI_API_KEY": "sk-or-v1-your-key" }

STEP 07

Start Codex

macOS / Linux

bash

CODEX_HOME="$HOME/.codex-bruceai" codex

STEP 08

Switch models inside Codex

After Codex starts, type /model to switch between the models BRUCEAI supports.

You can only switch to models of the provider your key belongs to: an OpenAI key uses the GPT family, a Grok key uses grok-4.7 / grok-4.6 / grok-4.5, and a DeepSeek key uses deepseek-v4.1-flash. Anything else returns a 400.

text

/model

# OpenAI key
gpt-6.1-sol
gpt-6-astra
gpt-6-sol
gpt-6-luna
gpt-5.6-sol
gpt-5.6-terra
gpt-5.6-luna
gpt-5.5

# Grok key
grok-4.7
grok-4.6
grok-4.5

# DeepSeek key
deepseek-v4.1-flash

If you select an unsupported model, the BRUCEAI backend returns the list of models this key can use.

STEP 09

Optional: create an alias

If you do not want to type CODEX_HOME every time, create a bcodex command. macOS goes in ~/.zshrc, an Ubuntu server in ~/.bashrc; in Windows Notepad, paste the function at the end of the file, press Ctrl+S, then close the window.

macOS / Linux

bash

echo 'alias bcodex="CODEX_HOME=\"$HOME/.codex-bruceai\" codex"' >> ~/.zshrc
source ~/.zshrc

After that, run bcodex for BRUCEAI. Your original codex command still uses your personal ChatGPT / Codex settings.

STEP 10

Troubleshooting

401 / invalid token: make sure the key is complete, has no extra spaces, and starts with sk-or-v1-.

400 / unsupported_model: the model id does not belong to this key's provider. An OpenAI key only serves the GPT family; create a Grok or DeepSeek key for those models.

403 / requires openai: contact the administrator to confirm account permissions.

Codex still uses your own ChatGPT account: make sure you started it with CODEX_HOME pointing at ~/.codex-bruceai and that base_url in config.toml is correct.

400 / conversation too large: compact the conversation with /compact in Codex, or start a new one.