Debug LightNow Proxy
Work from the AI client outward. Prove the client configuration first, then the generated proxy configuration, the Runtime Profile, and finally each upstream MCP server. Stop at the first failing check.
1. Check the client posture
lightnow config-status --client codex --json
The result tells you whether the client is managed, still contains unmanaged
MCP entries, uses a legacy runner, or points at a missing or mismatched proxy
configuration. It also reports non-secret warning codes and the expected proxy
config path.
| Result | Next action |
|---|---|
managed | Continue with proxy health. |
mixed | Import or remove direct MCP entries; they bypass LightNow. |
unmanaged, missing, or empty | Run lightnow sync --client codex --local-proxy. |
legacy_runner | Run the same sync to migrate to LightNow Proxy. |
invalid or unreadable | Fix the file or its permissions. Restore the adjacent .lightnow.bak backup when appropriate. |
Restart the client after changing its configuration. A running session may keep the MCP server list it loaded earlier.
2. Check the generated proxy configuration
Use the path reported by config-status, not a similar file from another
client.
lightnow-proxy --config ~/.lightnow/lightnow-proxy/codex.yaml --health --json
The report resolves the selected Runtime Profile and calls tool discovery for each configured upstream. It includes profile and upstream status, transport, tool counts, duration, and non-secret error details.
| Health status | Exit code | Meaning |
|---|---|---|
healthy | 0 | The selected profile and all upstreams passed discovery. |
degraded | 2 | The profile is empty or at least one upstream failed. |
failed | 1 | The profile itself could not be resolved or checked. |
3. Isolate the failing layer
| Symptom | Inspect next |
|---|---|
| The profile cannot be resolved | Confirm login, active Personal or organization context, profile name, and network access to LightNow. |
| One stdio server fails | Check the executable, package installation, working directory, arguments, environment, and required secrets. |
| One HTTP server fails | Check its URL, authentication, TLS trust, and network reachability from the client host. |
| Health succeeds but the client shows no tools | Restart the client, confirm it uses the tested config path, then warm the tool cache. |
| The server reports missing inputs | Complete its runtime config or secrets in the Runtime Profile and run health again. |
Do not edit the generated proxy YAML to repair a profile. Change the owning Runtime Profile or policy and run the client sync again.
4. Refresh tool discovery
Warm the cache only after health succeeds or after you understand a degraded upstream. This performs one profile tool-list request, updates the cache, and exits.
lightnow-proxy --config ~/.lightnow/lightnow-proxy/codex.yaml --warm-tools-cache
Start a new AI client session after warming the cache.
5. Capture protocol shape last
If the client starts LightNow Proxy but initialization still fails, record a redacted stdio capture. Use a temporary path and reproduce only the failing startup.
lightnow-proxy --config ~/.lightnow/lightnow-proxy/codex.yaml --transport stdio --capture-path /tmp/lightnow-proxy-capture.txt
Capture is intended for MCP message shape and client identity, not application payload debugging. Review the file before sharing it and remove it when the incident is resolved.
Evidence for a support ticket
Attach the JSON output from config-status and proxy health, the failing client
name and version, the active context and profile name, and the time of the
attempt. Never attach access tokens, authorization headers, secret values, or
an unreviewed capture file.
If health points to missing material, continue with runtime secrets and config. Use runtime events for session metadata or MCP Inspector to test the route outside the AI client.