Security

Msty Nexus is local-first software. Its security model is built around a local Runtime API, local Nexus tokens, write-only provider credentials, explicit network exposure, and redacted diagnostics.

Read this page before enabling LAN access, browser CORS, or remote controller profiles.

Token model

Every /v1/* endpoint requires a local Nexus token except local native app pairing requests.

Accepted token forms:

• Authorization: Bearer <token>
• X-Msty-Nexus-Token: <token>
• x-api-key: <token>

Local Nexus tokens authenticate clients to Nexus only. They are never forwarded to online providers or local runtimes.

Token storage:

• Bootstrap auth can use MSTY_NEXUS_TOKEN.
• Managed client tokens are stored in SQLite as hashes.
• Plaintext token values are returned only once when created.
• Token list/get responses expose metadata and display prefixes only.
• The first-party app stores its local token in the OS keychain.

Provider credential boundary

Provider keys are stored by Msty Nexus Runtime in secure OS storage or a configured credential backend. API responses return only credentialConfigured.

Provider keys must not appear in:

• Provider API responses
• App state
• SDK output
• Logs
• Job metadata
• Audit metadata
• Diagnostics reports
• Generated runtime configs

Provider metadata is API-visible, so Nexus rejects credential-shaped metadata keys such as apiKey, authorization, token, and secret.

Network exposure

Runtime binds locally by default. Use network exposure only when another trusted device must connect.

Important distinctions:

• Bind address controls whether other devices can reach Runtime.
• CORS controls which browser origins can call Runtime.
• CORS does not expose Runtime to the LAN.
• LAN exposure does not remove token authentication.
• Bind changes require a Runtime restart.
• CORS changes apply while Runtime is running.

Only share local Nexus tokens with clients you trust.

Browser and CORS boundary

CORS preflight for allowed origins is public. Actual /v1/* calls still require a local Nexus token.

Nexus strips upstream Access-Control-* response headers and writes CORS from its own configured policy. Provider URLs and local runtime tools cannot override the browser exposure policy.

Browser-origin requests cannot create pairing requests. Native app pairing is loopback-only.

Pairing

Local app pairing lets a native client request a local token through an explicit approval flow.

Pairing constraints:

• Request creation is limited to loopback native clients.
• Callback URLs must use literal loopback IPs and explicit ports.
• localhost, URL credentials, fragments, and non-loopback callbacks are rejected.
• Approval sends the token only to the requester callback.
• If callback delivery fails, Nexus rolls back the created token.
• The approve API returns only redacted token metadata.

Approve a pairing request only when the displayed code matches the app you opened.

Diagnostics and audit events

Nexus records audit events for security- and lifecycle-relevant mutations. Audit reads use a metadata allow-list so old or malformed rows cannot expose arbitrary stored data.

Safe diagnostics can include:

• Version and platform facts
• Runtime health state
• Provider credential presence booleans
• Service action support
• Status IDs and message keys
• Counts and timestamps
• Safe job state

Diagnostics must not include provider keys, local token values, token prefixes, local paths, request bodies, prompts, responses, raw upstream errors, process IDs, command lines, or generated artifact paths.

Local files and model storage

Local file import is write-only input. For example, llama.cpp GGUF import accepts a local file path from the native app, copies the file into Nexus-managed storage, and keeps only safe relative metadata afterward.

Delete actions are constrained to Nexus-owned storage and records. Nexus rejects unmanaged, absolute, symlink-escaped, path-traversal, and non-model targets.

Practical baseline

• Keep Runtime local-only unless another trusted device needs access.
• Create separate client tokens per app or script.
• Revoke tokens when clients are removed.
• Avoid * CORS except for explicit development.
• Use provider Test before routing production requests.
• Keep diagnostics support-safe.
• Review Gateway request logging before enabling it; it logs metadata only, but should still be a deliberate choice.