Skip to main content

Quickstart

Connect Codex through one LightNow Proxy entry without losing MCP servers from an existing setup. The same model works for the other supported clients; Codex is the shortest path for this first verification.

For comparison with the native client model, see OpenAI's official Codex MCP configuration documentation.

Prerequisites​

  • A LightNow account and Codex installation.
  • lightnow and lightnow-proxy available on PATH.
  • Permission to edit ~/.codex/config.toml.
Install on macOS
brew tap lightnow-ai/tap
brew install lightnow-cli lightnow-proxy

On Windows or Linux, install both packages with pipx instead. Confirm the commands with lightnow --help and lightnow-proxy --help.

1. Sign in​

Authenticate the CLI
lightnow login
lightnow whoami --json

Login opens the browser and stores the CLI session locally. Re-run it when the session expires.

2. Protect existing MCP config​

If ~/.codex/config.toml already contains MCP servers you want to keep:

Preview, then apply the import
lightnow import-config --client codex --dry-run
lightnow import-config --client codex

The preview does not write to LightNow or change the local file. The applied import merges accepted entries into the default Runtime Profile. Skip both commands when there are no useful existing MCP entries.

3. Connect Codex​

Write one LightNow Proxy entry
lightnow sync --client codex --local-proxy

Without --profile, LightNow uses the default Runtime Profile. If direct MCP entries are present, the CLI lists them and asks before replacement. It keeps a backup at ~/.codex/config.toml.lightnow.bak.

The sync writes:

  • one [mcp_servers.lightnow] entry in ~/.codex/config.toml;
  • the runtime configuration at ~/.lightnow/lightnow-proxy/codex.yaml.

Restart Codex after sync so it reloads its MCP server list.

4. Verify the result​

Check client posture and proxy health
lightnow config-status --client codex --json
lightnow-proxy --config ~/.lightnow/lightnow-proxy/codex.yaml --health --json
1
Client status is managed

Codex contains the LightNow entry, the referenced proxy config exists, and no unexpected direct MCP entries remain.

2
Proxy health is specific

A healthy result proves tool discovery works. A degraded or failed result identifies the upstream server that needs attention.

3
Codex sees the tools

Start a new Codex session and confirm the tools from the selected Runtime Profile are available.

If verification fails​

Direct entries remainStatus is mixed

Import or remove the unexpected direct entries, then sync again. Codex's internal node_repl server is not treated as unmanaged drift.

YAMLProxy config is missing

Re-run Local Proxy sync and verify the path shown in the Codex entry.

ExecutableProxy is not on PATH

Install lightnow-proxy, open a fresh shell, and sync Codex again.

UpstreamHealth is degraded

Continue with Debug LightNow Proxy.

Next steps​