Setup

Setup has one goal: make a model reachable through the local Nexus gateway with safe authentication. You can start from either a local runtime or a cloud provider.

Quick setup sequence

1. Open Msty Nexus.
2. Confirm Runtime is reachable.
3. Choose a setup path: local runtime or cloud provider.
4. Sync, install, import, or add a model.
5. Check model library health if a local runtime already has models.
6. Create a client token.
7. Test the gateway.
8. Configure network/CORS only if another device or browser origin needs access.

Confirm Runtime is reachable

The app stores its local Runtime token in the OS keychain. If the app reports that Runtime is offline or unauthenticated, use Repair connection before adding providers or models.

For source builds, a simple local Runtime run uses:

MSTY_NEXUS_TOKEN=dev-local-token make runtime

Development app builds use their own dev identity, loopback port, keychain namespace, and repo-local runtime data:

make dev

Production builds use local-only access by default. Do not expose Runtime to the LAN until you have a token and network plan.

Choose a local setup path

Use the local path when you want Nexus to run or reuse models on your machine.

Recommended order:

1. Open Providers.
2. Use Find Local Runtimes if you already have a compatible local API running.
3. Use the local runtime cards to install or start Nexus-managed Ollama, llama.cpp, MLX, or CLI Proxy where available.
4. Open Models and sync, search, pull, or import a model.
5. Check Health & Memory to confirm local model storage and loaded state.
6. Confirm at least one model appears as visible in the catalog.

Local runtime behavior:

• Ollama handles Ollama catalog models, embeddings, and native load/unload behavior.
• llama.cpp handles GGUF files, Hugging Face GGUF pulls, local GGUF imports, and router-mode load/unload.
• MLX handles Apple Silicon MLX models and macOS-only MLX runtime lifecycle.
• CLI Proxy exposes supported subscription account models through a local API surface.

Choose a cloud setup path

Use the cloud path when you want Nexus to route to hosted providers while keeping provider keys inside Runtime.

Recommended order:

1. Open Providers.
2. Add OpenAI, Anthropic, OpenRouter, or a compatible endpoint.
3. Paste the provider key once.
4. Save and run Test.
5. Sync provider models or enable automatic provider models.
6. Confirm models appear in Models.

Provider keys are write-only. Nexus returns only whether a credential is configured; it never returns raw provider keys to the app, SDKs, logs, or diagnostics.

Create a client token

Client tokens are local Nexus API tokens for apps and scripts. Create them in Settings > Client Tokens.

Use the token as the API key when configuring OpenAI-compatible or Anthropic-compatible clients. The plaintext token is shown once and should be stored in the client app's secret storage.

Test the gateway

Use the app's gateway test or call a model directly:

curl http://127.0.0.1:3939/v1/models \
  -H "Authorization: Bearer $MSTY_NEXUS_TOKEN"

For chat:

curl http://127.0.0.1:3939/v1/chat/completions \
  -H "Authorization: Bearer $MSTY_NEXUS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-test",
    "messages": [{ "role": "user", "content": "Say hello." }]
  }'

Replace openai/gpt-test with a model, alias, @preset/<slug>, or @route/<slug> value from the app.

Enable browser or LAN access only when needed

Runtime is local-only by default. Use Settings > Network Access when another device or browser origin must connect.

• LAN exposure changes the Runtime bind address and requires a Runtime restart.
• CORS changes browser origin access and applies at runtime.
• CORS does not expose Runtime to the LAN by itself.
• Every /v1/* request still needs a local Nexus token.

For broader exposure guidance, see Security.

Optional: enable Start at Login

Use Settings > Start at Login when you want the Nexus app to launch automatically after OS sign-in.

This is an app-shell preference, not a Runtime API setting. Nexus manages only its own auto-start registration and refuses to replace unmanaged launch entries. In development builds, Start at Login is unavailable so local dev launchers do not persist background startup behavior accidentally.

Minimum done-state

You are ready to connect other apps when:

• Runtime is healthy and authenticated.
• One provider or local runtime is configured.
• One visible model is available in Models.
• Health & Memory has no blocking local model issues.
• A client token exists.
• A gateway test succeeds.
• Network/CORS settings match the client you plan to use.