[Bug] [Hosted Quickstart] API Usage examples use gpt-4o chat completions for non-OpenAI services #562

Background

The README instructs users to paste this into your terminal. This was tested by directly pasting the full Quickstart script into the default macOS zsh terminal.

Problem

When pasted directly into zsh, the terminal produces shell parsing errors such as:

• zsh: number expected
• zsh: command not found: #
• zsh: missing delimiter for 'u' glob qualifier

Even if the Docker startup flow continues, these errors make it unclear whether Quickstart has failed and which messages can be safely ignored.

Steps to Reproduce

1. Open a fresh terminal session using the default macOS zsh
2. Copy the full Quickstart script from the README
3. Paste it directly into the terminal and run it

Expected

• The script should run reliably when used exactly as described: paste directly into the terminal
• Users on the default macOS zsh shell should not see unrelated shell parsing errors

Actual

• Directly pasting the script into zsh produces multiple shell errors
• It becomes difficult to tell whether the problem is only the shell execution mode or an actual NyxID startup failure

Impact

• This hurts the goal of allowing a non-team-member to complete Quickstart without hand-holding
• It reduces confidence and makes the first-run experience harder to understand

Suggestion

• Explicitly document that the script should be run under bash
• Or provide a truly paste-and-run version that avoids comments or special characters that trigger zsh parsing issues

Issue 2

Title

[Bug] [Quickstart] Quickstart still prints a success message after the health check times out

Background

The Quickstart startup script waits for http://localhost:3001/health and then prints a final startup message.

Problem

In practice, even when the health check times out, the script still prints:

• Timed out. Run: docker compose logs backend
• NyxID is running at http://localhost:3000

These two messages together make it unclear whether the stack actually started successfully or not.

Steps to Reproduce

1. Run the Quickstart startup script from the README
2. Let http://localhost:3001/health fail to become ready within the wait window
3. Observe the final script output

Expected

• If the health check times out, the script should clearly report that startup is incomplete or that the backend is not ready
• It should not print both a timeout/failure message and a success message in the same run

Actual

• After the health check times out, the script still prints NyxID is running at http://localhost:3000
• The success message conflicts with the timeout message

Impact

• Testers cannot accurately tell whether Quickstart passed
• It also affects follow-up troubleshooting because it is unclear whether they should continue to registration or inspect the backend first

Suggestion

• Change the script logic so the success message is printed only after /health succeeds
• If the health check times out, print a clear failure state and the next troubleshooting step

Issue 3

Title

[Improvement] [Quickstart] Quickstart 缺少明确的启动完成判定标准

Background

本次按 README Quickstart 执行后，前端页面 http://localhost:3000 已可访问，Docker 也显示 frontend/backend/mongodb 容器均已启动，但脚本中的 backend health check 同时出现了超时。

Problem

当前 Quickstart 对“什么时候算真正跑通”描述不够清晰，容易出现以下困惑：

• 前端能打开，是否就算启动成功
• backend 容器显示 Started，是否就代表服务 ready
• /health 超时的情况下，下一步应该继续注册登录还是先排查日志

Expected

Quickstart 应提供清晰、可操作的完成判定标准，例如：

• http://localhost:3001/health 返回 200
• http://localhost:3000 可访问
• 用户可以完成注册并进入控制台

Actual

• 当前文档没有把这些条件明确列为验收标准
• 测试者只能根据零散输出来自行推断当前状态

Impact

• 不利于执行一致性的测试
• 会增加首次使用者的理解成本

Suggestion

• 在 Quickstart 末尾增加清晰的“Done when...”验收列表
• 将基础启动成功、backend ready、用户可登录这几层状态分开说明

Issue 4

Title

[Bug] [Quickstart] Quickstart 超时后给出的 backend 排查命令不完整

Background

README 的 Quickstart 启动脚本在 backend health check 超时时，会提示用户执行：

• docker compose logs backend

但实际 Quickstart 启动时使用的是组合 compose 文件：

• docker-compose.yml
• docker-compose.prod.yml
• --env-file .env.production

Problem

在当前启动方式下，用户直接执行 docker compose logs backend 时，会得到：

• no such service: backend

这是因为该命令没有带上和启动时相同的 compose 文件组合，导致 README 给出的排查路径本身无法直接使用。

Steps to Reproduce

1. 按 README Quickstart 使用组合 compose 文件启动服务
2. 让 backend health check 超时
3. 按提示执行 docker compose logs backend

Expected

• 超时后的排查命令应与实际启动命令保持一致
• 用户应能直接通过 README 给出的命令查看 backend 日志

Actual

• 直接执行 docker compose logs backend 会提示 no such service: backend
• 测试者需要额外理解 compose 文件组合方式，才能自行修正命令

Impact

• 会进一步增加 Quickstart 排障成本
• 对首次使用者不友好，也不符合“无需 hand-holding”的目标

Suggestion

• 在 README 中提供与启动命令一致的日志查看方式，例如：
  • docker compose -f docker-compose.yml -f docker-compose.prod.yml --env-file .env.production logs backend
• 或直接建议使用容器名查看日志，例如：
  • docker logs nyxid-backend

Issue 5

Title

[Bug] [Quickstart] Quickstart can fail with MongoDB authentication errors when local volumes already exist

Background

The Quickstart script regenerates MONGO_ROOT_PASSWORD and writes it into .env.dev/.env.production. If the local environment has already been run before and the MongoDB volume still exists, Mongo will not reinitialize the root user password just because the environment variable changed.

Problem

In this scenario:

• the MongoDB container can still start normally
• the frontend remains accessible
• the backend connects using the newly generated MONGO_ROOT_PASSWORD
• MongoDB is still using the old password stored in the existing volume

As a result, the backend repeatedly exits with database authentication errors. The logs look like:

• SCRAM failure: Authentication failed
• code: 18 AuthenticationFailed

Steps to Reproduce

1. Run NyxID locally once and keep the MongoDB volume
2. Run Quickstart again so that a new .env.dev/.env.production is generated
3. Start the stack and observe the backend status and logs

Expected

• Quickstart should explicitly account for the existing local volume scenario
• If Mongo credentials are regenerated, the docs should clearly explain that the existing volume may need to be reset or that the original password must be reused

Actual

• the backend fails to start because database authentication keeps failing
• from the user perspective, MongoDB looks healthy and the frontend is accessible, but the backend never becomes ready

Impact

• Quickstart can appear broken even though the issue is only a mismatch between regenerated credentials and an existing volume
• This increases troubleshooting cost and is not obvious for first-time testers

Suggestion

• Add a note in the README about existing local volumes and how to recover
• Clearly explain that if Mongo credentials are regenerated, the local volume may need to be cleared first
• Or adjust the Quickstart flow so it does not always regenerate a new Mongo root password unconditionally

Issue 6

Title

[Bug] [Quickstart] Prebuilt Docker images do not return invite_code_required in /api/v1/public/config

Background

Quickstart is expected to start a local environment where public registration is enabled. The generated local config explicitly sets:

• INVITE_CODE_REQUIRED=false

The README also states that local users should be able to register directly without needing an invite code.

Problem

After starting the stack with the prebuilt Docker images, the register page still shows the invite-code-first UI.

Checking the backend response shows:

{
  "frontend_url": "http://localhost:3000",
  "mcp_url": "http://localhost:3001/mcp",
  "node_ws_url": "ws://localhost:3001/api/v1/nodes/ws",
  "version": "0.1.0",
  "social_providers": []
}

The response does not include invite_code_required.

On the frontend, the registration flow falls back to invite-only mode when this field is missing:

• publicConfig?.invite_code_required ?? true

As a result, even though Quickstart generates INVITE_CODE_REQUIRED=false, the local register page behaves as if invite-only mode is enabled.

Steps to Reproduce

1. Run Quickstart using the prebuilt Docker images
2. Open http://localhost:3000/register
3. Observe that the page still asks for an invite code
4. Check the backend response:
   • curl -s http://localhost:3001/api/v1/public/config

Expected

• /api/v1/public/config should include invite_code_required
• With INVITE_CODE_REQUIRED=false, the register page should allow direct local registration instead of showing invite-code gating

Actual

• /api/v1/public/config does not include invite_code_required
• The frontend falls back to invite-only UI because the field is missing

Impact

• Local Quickstart users may believe invite-only mode is still enabled
• This contradicts the README expectation that local registration should work directly
• It also makes it look like the local config did not take effect

Suggestion

• Ensure the prebuilt backend image returns invite_code_required in /api/v1/public/config
• Or improve the frontend fallback behavior so local Quickstart is not misleadingly shown as invite-only when the field is absent

Issue 7

Title

[Bug] [Quickstart] Manual CLI verification assumes the created service slug will remain llm-openai

Background

The README's Manual CLI section instructs users to run:

• nyxid service add llm-openai --credential-env OPENAI_API_KEY
• nyxid proxy request llm-openai models

This implies that the created service slug will be llm-openai.

Problem

In practice, nyxid service add llm-openai ... may return a different slug, for example:

• llm-openai-2

This can happen when a service with the original slug already exists.

When users then follow the README literally and run:

• nyxid proxy request llm-openai models

the request can fail because it targets the old slug rather than the newly created service.

Steps to Reproduce

1. Ensure a service with slug llm-openai already exists
2. Run:
   • nyxid service add llm-openai --credential-env OPENAI_API_KEY
3. Observe that the CLI returns a different slug, such as llm-openai-2
4. Follow the README literally and run:
   • nyxid proxy request llm-openai models

Expected

• The README should make it clear that users must use the actual slug returned by nyxid service add
• Or the CLI flow should provide a stable identifier that matches the follow-up verification command

Actual

• The README verification step is written against a fixed slug
• The created service may use a different slug
• Users can follow the README exactly and still hit a confusing proxy error

Impact

• The CLI quickstart flow becomes unreliable when the target slug already exists
• Users may think the newly added credential or proxy flow is broken, even though the real issue is that the verification step points to the wrong slug

Suggestion

• Update the README to tell users to copy the actual Slug value returned by nyxid service add
• Or adjust the CLI UX so the next verification step can reference a stable alias instead of relying on the original requested slug

Issue 8

Title

[Bug] [Quickstart] nyxid service add llm-openai --credential-env OPENAI_API_KEY succeeds, but proxy requests still require a legacy OpenAI provider connection

Background

The Manual CLI flow in the README suggests that users can:

1. add an OpenAI-backed service with:
   • nyxid service add llm-openai --credential-env OPENAI_API_KEY
2. verify it with:
   • nyxid proxy request <slug> models

The expectation is that the credential supplied via --credential-env is enough for the proxy request to work.

Problem

In practice, the service can be created successfully, but proxy requests still fail with:

• Provider 'OpenAI' connection required. Please connect your OpenAI account first.

This happens even when the request is sent to the actual slug returned by nyxid service add, for example:

• llm-openai-2

Steps to Reproduce

1. Set OPENAI_API_KEY in the current shell
2. Run:
   • nyxid service add llm-openai --credential-env OPENAI_API_KEY
3. Note the created slug returned by the CLI, for example:
   • llm-openai-2
4. Run:
   • nyxid proxy request llm-openai-2 models

Expected

• A service created with --credential-env OPENAI_API_KEY should be usable immediately for proxy requests
• The proxy should use the credential captured during service add

Actual

• The service is created successfully
• But proxy requests still fail with:
  • Provider 'OpenAI' connection required

Impact

• The CLI quickstart flow appears broken even after the user follows the documented steps
• Users can reasonably conclude that service add did not actually create a usable OpenAI-backed service
• This also suggests the prebuilt backend image may still be relying on an older provider-connection model

Suggestion

• Ensure the prebuilt backend image treats llm-openai as a direct-auth service compatible with nyxid service add --credential-env
• Or update the Quickstart docs if the current prebuilt image still requires a separate provider connection flow

Issue 9

Title

[Improvement] [Hosted Quickstart] README does not clearly require users to add and connect a service first

Background

The current hosted README path mainly tells users to:

• sign up for a NyxID account
• add API credentials through the dashboard
• copy the Settings > MCP config into their AI tool

Problem

This wording is too vague and can easily make a new user think:

• once registration is done, configuring MCP should be enough to start calling services

In practice, the hosted path usually also requires the user to first go to AI Services and:

• add or connect a specific service
• provide the credentials required for that service
• verify one real proxy request successfully

If the README does not explicitly describe this step, users can easily end up seeing only nyx__... meta-tools in MCP, or not understand why proxy requests are still not working.

Expected

The README should clearly describe the hosted first-success path:

• sign up / log in
• add and connect at least one service in AI Services
• provide the credentials required for that service
• verify one successful proxy request first
• then configure the MCP client

Actual

• The README only says “add your API credentials through the dashboard”
• It does not clearly state the “add/connect a service first” step

Impact

• This makes it harder to prove the hosted-first acceptance goal of “a non-team member can get from zero to working in under 10 minutes without hand-holding”
• It increases the cognitive load of the hosted onboarding flow

Suggestion

• Rewrite the hosted quickstart section as an explicit step-by-step flow
• Do not only say “add your API credentials”
• Explicitly say “add and connect a service in AI Services, then provide the credentials required for that service”

Issue 10

Title

[Bug] [Quickstart] Local default startup still shows Google / GitHub / Apple login options even though they are not configured

Background

After starting NyxID locally via the Quickstart flow, the default environment is mainly intended for quick evaluation and basic verification. In the default local setup, Google, GitHub, and Apple social login providers are not configured. In practice, the only working authentication path is email registration / email login.

Problem

The login page still shows Google, GitHub, and Apple social login options, but clicking any of them fails immediately. For example, clicking Google login returns:

• social_auth_failed
• error_code: 6000
• message: Social authentication failed: Google provider not configured

This can make first-time users think that:

• social login should work but the system is broken
• Quickstart did not start correctly
• extra troubleshooting is required for the local environment

Steps to Reproduce

1. Start NyxID locally using the default Quickstart flow
2. Open the login page
3. Click any of the Google / GitHub / Apple social login options
4. Observe the result

Expected

• If the local default environment does not configure social login providers, the login page should hide Google / GitHub / Apple
• Or it should clearly indicate that these providers require additional configuration before use
• Under the default Quickstart path, users should only see login options that actually work out of the box, such as email registration / login

Actual

• The page shows Google / GitHub / Apple login buttons
• Clicking them immediately returns provider-not-configured errors
• Users have no way to know in advance that these options are unavailable in the default local environment

Impact

• Increases confusion for first-time users
• Hurts the “no hand-holding” Quickstart experience
• Makes it easy for users to misdiagnose the problem as a failed startup or a broken login system

Suggestion

• Hide unconfigured social login options in the default local development / Quickstart environment
• Or add a clear UI hint that these providers require additional setup
• At minimum, ensure that the login methods shown by default are actually usable in the out-of-the-box Quickstart flow

Issue 11

Title

[Bug] [Hosted Quickstart] API Usage examples duplicate /v1 when the service endpoint already includes /v1

Background

Hosted quickstart testing found that multiple service detail pages generate API Usage examples with a hard-coded /v1/chat/completions path. When the service endpoint already includes /v1, copying the example returns 404.

Observed pages:

• chrono-llm
• api-lark-bot

Problem

Bad example:

curl https://nyx.chrono-ai.fun/api/v1/proxy/s/chrono-llm/v1/chat/completions \
  -H "X-API-Key: nyx_..." \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-4o","messages":[{"role":"user","content":"hello"}]}'

If the endpoint is:

https://llm.aelf.dev/v1

the effective downstream URL becomes:

https://llm.aelf.dev/v1/v1/chat/completions

The downstream returns 404 page not found. Without curl -i or -w, the terminal can look like it returned nothing.

Steps to Reproduce

1. Open a service detail page whose endpoint already includes /v1, for example chrono-llm.
2. Copy the API Usage example and call:
   • /api/v1/proxy/s/<slug>/v1/chat/completions
3. The request returns 404.
4. Remove the extra /v1 and retry:
   • /api/v1/proxy/s/<slug>/chat/completions
5. The request returns 200.

Expected

• API Usage examples should be generated from the service endpoint.
• If the endpoint already includes /v1, the proxy path should be:

/api/v1/proxy/s/<slug>/chat/completions

Actual

• The example still appends /v1/chat/completions.
• The effective downstream path becomes /v1/v1/chat/completions.
• The first verification request returns 404 page not found.
• Removing /v1 makes the same service return HTTP 200.

Successful command:

curl https://nyx.chrono-ai.fun/api/v1/proxy/s/chrono-llm/chat/completions \
  -H "X-API-Key: nyx_..." \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-4o","messages":[{"role":"user","content":"hello"}]}'

Successful response includes:

HTTP=200

Impact

• Blocks the hosted quickstart "first 2xx proxy call" path.
• Users can configure the service and credential correctly but still fail because the example path is wrong.
• The 404 body is short or empty, making the failure hard to diagnose.

Suggestion

• Do not hard-code /v1/chat/completions.
• Generate proxy examples from the endpoint path.
• If the endpoint already includes /v1, use /chat/completions in the example.
• Add curl -i or -w "HTTP=%{http_code}" so failures are visible.

Issue 12

Title

[Bug] [Hosted Quickstart] API Usage examples use gpt-4o chat completions for non-OpenAI services

Background

Hosted quickstart testing found that the service detail page shows the same OpenAI-style API Usage example for different service types.

Observed examples:

• DeepSeek service (llm-deepseek)
• Telegram bot service (api-telegram-bot)

Both pages show a request body like:

{"model":"gpt-4o","messages":[{"role":"user","content":"hello"}]}

Problem

The API Usage example is not service-aware.

For DeepSeek, the example uses the OpenAI model name gpt-4o, while a working DeepSeek request should use a DeepSeek model such as:

{"model":"deepseek-chat","messages":[{"role":"user","content":"hello"}]}

For Telegram bot, the page still shows an LLM chat completions example:

curl https://nyx.chrono-ai.fun/api/v1/proxy/s/api-telegram-bot/v1/chat/completions \
  -H "X-API-Key: nyx_..." \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-4o","messages":[{"role":"user","content":"hello"}]}'

This request shape does not match what a Telegram bot service user is trying to verify, and makes it look like the bot can be tested through an OpenAI chat completions request.

Steps to Reproduce

1. Create or open a DeepSeek service.
2. Scroll to the API Usage section.
3. Observe that the example still uses "model":"gpt-4o".
4. Create or open an API Telegram Bot service.
5. Scroll to the API Usage section.
6. Observe that the example still uses an OpenAI chat completions request body.

Expected

• DeepSeek examples should use a DeepSeek-compatible model, for example deepseek-chat.
• Telegram bot examples should use a Telegram-relevant endpoint/body, or avoid showing a generic LLM chat completions example if no suitable endpoint is known.
• API Usage examples should be generated from service metadata, service type, capabilities, or OpenAPI spec when available.

Actual

• DeepSeek API Usage shows "model":"gpt-4o".
• Telegram bot API Usage shows the same OpenAI chat completions body.
• Users can copy the example and fail even when the service credential is valid, because the example is not adapted to the selected service.

Impact

• Blocks or slows the hosted quickstart "first 2xx proxy call" verification.
• Makes users think their service credential is wrong when the example is wrong.
• Makes non-OpenAI services look like OpenAI-compatible chat endpoints even when they are not.

Suggestion

• Generate API Usage examples per service/provider.
• Use catalog metadata such as provider slug, service type, capabilities, or OpenAPI endpoint discovery to choose the example.
• For known LLM providers, use provider-specific default models:
  • OpenAI: gpt-4o or the current recommended OpenAI model
  • DeepSeek: deepseek-chat
• For non-LLM services such as Telegram/Lark bots, do not show a generic chat completions request unless the service actually exposes an OpenAI-compatible chat endpoint.