Local Runtimes

Local runtimes are model engines that Nexus can manage or route to on the current machine. Nexus keeps their lifecycle behind a stable gateway API so clients do not need runtime-specific setup logic.

Open Providers for local runtime cards and Settings for runtime storage and performance controls.

Runtime services

Nexus runtime services include:

• Nexus Ollama: Ollama catalog models and embeddings served behind the local gateway.
• Nexus llama.cpp: GGUF models through the local llama.cpp server and native router.
• Nexus MLX: MLX models optimized for Apple Silicon.
• Nexus CLI Proxy: subscription-backed Claude, Gemini, Codex, and related local API models where available.

Some services are platform-limited. MLX lifecycle and sync are macOS-only.

Service actions

Runtime actions run as background jobs:

• install
• start
• stop
• restart
• update
• rollback
• uninstall
• enable
• disable

Jobs expose progress, status, warnings, and safe error codes. Long-running work should be followed through the activity strip or /v1/jobs/{id}.

Install and update policies

Nexus supports these runtime install/update source policies:

• feed: Msty-controlled signed runtime feed and the default for normal use.
• upstream: explicit publisher-direct development option.
• manifest: operator-controlled signed manifests with local trusted Ed25519 keys.
• path: verify a cataloged executable already exists on PATH.
• disabled: reject install/update while leaving other safe actions available.

API callers cannot supply feed URLs, artifact URLs, manifest URLs, or trust keys. Trust policy is Runtime startup configuration, not UI input.

Managed runtime ownership

Nexus controls only runtimes it owns or explicitly records.

Lifecycle boundaries:

• Nexus does not kill externally started processes.
• Stop and restart operate only on Nexus-owned process records.
• Uninstall removes Nexus-managed runtime binaries and install metadata.
• Uninstall preserves model caches and model catalog records.
• Path-based installs mark operator-provisioned executables; Nexus does not run package managers or shell installers.

This prevents a local control action from deleting user-owned runtime files.

Runtime settings

Runtime settings include:

• Models directory
• Managed runtime root status
• Model cache status
• Install policy posture
• Runtime tuning for Ollama and llama.cpp
• Acceleration engine selection where supported

Model storage uses runtime-specific subdirectories under the configured models directory. The app may show storage summaries, but Runtime keeps raw storage roots and local paths out of public diagnostics.

Service diagnostics

Service diagnostics are read-only. They combine:

• Runtime catalog metadata
• Supported actions
• Install state
• Managed version identifiers
• Sanitized status probes
• Executable availability
• Configuration-presence booleans

Diagnostics do not expose resolved executable paths, local model directories, runtime roots, command lines, process IDs, generated config paths, provider credentials, or raw network errors.

Service accounts

Some runtimes support account-backed local models. CLI Proxy can expose subscription account models through service account routes.

Account sign-in flows are runtime-owned. The app starts and polls the login flow, then model sync runs after the account is connected. Secrets remain in Runtime or OS credential storage and are not returned to the frontend.

Common issues

• Runtime is not installed: install it from the local runtime card.
• Executable missing: reinstall with Nexus or add the cataloged executable to PATH.
• Port conflict: stop the process using the runtime port, then start again.
• Runtime started externally: stop it manually, then start through Nexus if you want Nexus lifecycle controls.
• Update requires stop: stop the runtime before updating a managed version.

For model download and import details, see Models.