SoCLaaS

Home / Setup Guides / Codex CLI

Coding Agent

Connect Codex CLI to SoCLaaS

Use Codex from your terminal with a SoCLaaS API key. Codex talks to the gateway through a custom OpenAI-compatible model provider.

We recommend OpenCode for most users. Codex CLI is built around OpenAI's own models and may not work best with third-party LLM providers. If you are choosing a client, start with the OpenCode setup guide.

Recommended: download a ready-made config. Open Portal → Client Setup, download soclaas.config.toml and soclaas-model-catalog.json, and save both in ~/.codex/. Then run codex --profile soclaas. The generated catalog lists every chat model available to your key.

The portal also provides a soclaas.env file for loading SOCLAAS_API_KEY; the shell environment instructions on the same page show where to save it.

The API key portal is available from the NUS network, while the API gateway itself is reachable from the Internet. Check the exact Codex config keys against your installed version, since the CLI changes frequently.

What you need

SettingValue
Base URLhttps://soclaas-api.comp.nus.edu.sg/v1
API keyFrom the SoCLaaS portal, stored in SOCLAAS_API_KEY
ModelA chat-capable ID from GET /v1/models

Manual setup

Use these steps if you prefer not to download the generated config.

  1. Get an API key

    Sign in to the SoCLaaS portal from the NUS network and create a personal key. The portal can also download a soclaas.env file that sets SOCLAAS_API_KEY for you.

  2. Export the key

    Add this to your shell profile so new terminals pick it up.

    export SOCLAAS_API_KEY="YOUR_API_KEY"

  3. Find a model ID

    curl https://soclaas-api.comp.nus.edu.sg/v1/models \
  -H "Authorization: Bearer $SOCLAAS_API_KEY"

    Choose a model that supports chat and copy its id.

  4. Install Codex

    npm install -g @openai/codex
codex --version

  5. Configure the provider

    Edit ~/.codex/config.toml. Replace YOUR_MODEL_ID with the ID from step 3.

    model = "YOUR_MODEL_ID"
model_provider = "soclaas"
model_reasoning_effort = "none"

[model_providers.soclaas]
name = "SoCLaaS"
base_url = "https://soclaas-api.comp.nus.edu.sg/v1"
env_key = "SOCLAAS_API_KEY"
wire_api = "responses"

    SoCLaaS exposes both endpoints. If your Codex version or chosen model has trouble with the Responses API, switch wire_api to chat.

  6. Run Codex

    codex "Summarise this repository in three bullets."

    If you saved the generated files instead, launch the profile with codex --profile soclaas.

Troubleshooting