Skip to main content
How-to

Connect Codex

Codex starts one local LightNow Proxy entry. LightNow supplies the selected Runtime Profile and runtime context behind it.

Before you sync​

Install the CLI and proxy, sign in, and decide whether the current Codex MCP entries must be preserved.

Install and authenticate
brew tap lightnow-ai/tap
brew install lightnow-cli lightnow-proxy
lightnow login
lightnow whoami --json
Optional migration
lightnow import-config --client codex --dry-run
lightnow import-config --client codex

Sync Codex​

Recommended Local Proxy sync
lightnow sync --client codex --profile default --local-proxy

The CLI lists direct MCP entries before replacement and asks for confirmation. Use --yes only in an already-reviewed automation path. Restart Codex after a successful write.

Files LightNow touches​

Codex config
~/.codex/config.toml
LightNow Proxy config
~/.lightnow/lightnow-proxy/codex.yaml
Backup when Codex config exists
~/.codex/config.toml.lightnow.bak

The managed Codex entry has this shape; the generated config path is absolute on the current machine:

~/.codex/config.toml
[mcp_servers.lightnow]
command = "lightnow-proxy"
args = ["--config", "/Users/you/.lightnow/lightnow-proxy/codex.yaml", "--transport", "stdio"]
default_tools_approval_mode = "approve"

Other Codex settings remain in the TOML file. Direct [mcp_servers.*] entries are removed in Local Proxy mode, while Codex's internal node_repl plumbing is ignored by posture checks.

Verify client posture​

Inspect the Codex file without printing secrets
lightnow config-status --client codex
lightnow config-status --client codex --json
  • managed: the LightNow entry and proxy config are present, with no unexpected direct servers.
  • mixed: LightNow is present, but direct MCP entries can still bypass the managed profile.
  • missing, invalid, or unreadable: fix the client file before continuing.
  • proxy_config_missing or a missing executable warning: repeat sync after restoring the YAML file or installing lightnow-proxy.

Verify runtime health​

Test the profile without starting Codex
lightnow-proxy --config ~/.lightnow/lightnow-proxy/codex.yaml --health --json

Healthy means the selected profile loaded and tool discovery succeeded. Degraded or failed identifies an upstream that needs investigation. This check does not prove that an already-running Codex session reloaded its tools, so start a new session afterwards.

Organization-managed sync​

After a pilot works, an organization can let its current LightNow Config policy choose profile, proxy mode, telemetry preference, and unmanaged-entry handling:

Apply the active organization policy
lightnow context --tenant acme
lightnow sync --client codex --from-settings
lightnow config-status --client codex --json

Use --from-settings by itself; it cannot be combined with --local-proxy or --runner.

Troubleshooting​

ReloadCodex shows no LightNow tools

Restart Codex, then run proxy health if a new session still has no tools.

DriftStatus is mixed

Import or remove the remaining direct server, then sync again.

PATHProxy executable is missing

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

UpstreamHealth names a failed server

Follow Debug LightNow Proxy with that server as the narrow target.