Blaizzy/nativ

Local AI, native to your Mac.

Chat, serve, monitor, and connect MLX models from one macOS app.

Nativ is a native macOS workspace for running AI models locally on Apple silicon. It bundles an mlx-vlm server, finds compatible models in your Hugging Face cache (honoring HF_HUB_CACHE and HF_HOME), and wraps the whole experience in a polished SwiftUI app.

Use Nativ as a private chat app, a model manager, a performance dashboard, or an OpenAI- and Anthropic-compatible local inference server for the tools you already use.

Full feature and contributor documentation lives in Docs/ — start there for Chat, Models, Voice, Scheduled tasks, Integrations, and the Developer reference, plus guides for extensions, kits, and the MCP catalog.

Inference runs on your Mac after a model has been downloaded. Model downloads and first-time build dependencies still require network access.

flowchart LR
    A["Nativ · SwiftUI app"] --> B["NativServerKit"]
    B --> C["Bundled mlx-vlm server"]
    C --> D["MLX runtime"]
    D --> E["Local models · Apple unified memory"]
    F["Apps and coding agents"] -->|"localhost API"| C

NativServerKit owns the embedded Python distribution and server lifecycle. The app adds model discovery, chat, analytics, configuration, integrations, logs, menu bar controls, and software updates around that runtime.

To run the app:

• A Mac with Apple silicon.
• macOS 26 or newer.
• Enough unified memory for the model you choose.
• Optional: a Hugging Face token (set in the app or via HF_TOKEN) to download gated models.

To build from source, you will also need:

• Xcode with the macOS 26 SDK.
• The Xcode Metal Toolchain for the embedded terminal (xcodebuild -downloadComponent MetalToolchain).
• xcodegen.
• Python 3.
• Network access to GitHub Releases and PyPI while the embedded Python bundle is first assembled or refreshed.

Download the latest DMG from GitHub Releases, drag Nativ to Applications, and launch it. Alternatively, install it via Homebrew:

brew install --cask nativ

Nativ uses Sparkle for subsequent in-app updates.

On first launch:

1. Choose an installed language model, download a recommended one, or continue with load-on-demand.
2. Optionally generate an API key to protect the server's management endpoints.
3. Grant microphone, accessibility, and screen recording permissions up front, or change them later in Settings.
4. Open Models to download or select a compatible model.
5. Start chatting, inspect analytics, or connect one of the supported coding tools.

Nativ asks for Accessibility permission so it can detect the default Control + Option + Command double-tap outside the app, and for Microphone permission the first time you record. Recordings are saved temporarily as .wav files with matching .txt transcripts and can be opened from Show Voice Recordings in the menu-bar menu. Raw audio is deleted automatically after five minutes (or immediately when Nativ quits), while transcript files remain available. Press Fn + R to transcribe the newest available audio again and insert it at the current cursor. The transcript remains on the clipboard. If no speech-to-text model is installed, Nativ links directly to filtered speech-model discovery. Open Audio to inspect dictation analytics and history, select an installed speech-to-text model, choose the capture animation, or change either global shortcut.

brew install xcodegen
make xcode-generate
make xcode-run

The first build can take a while because NativServerKit creates a relocatable Python runtime and installs the pinned mlx-vlm server dependencies into the framework resources. Later builds reuse the bundle until an input changes.

Local builds are signed with the Apple Development identity configured in Configuration/Signing.xcconfig (or the ignored Configuration/Signing.local.xcconfig override). Keep the identity's login keychain unlocked while building. The stable signer-bound identity lets macOS keep Accessibility permission across rebuilds instead of treating each binary as a different app.

The debug launch script restarts only the exact app bundle requested. If another worktree's Nativ is running, it leaves both builds untouched and reports its path. To intentionally switch builds, quit the running app first or use ./scripts/open_macos_debug.sh --replace-existing /absolute/path/to/Nativ.app. Concurrent launches are serialized across worktrees to protect the shared app identity, chat data, server, and shortcuts.

To test an unreleased mlx-audio checkout, point the build at its local path:

MLX_AUDIO_SOURCE_PATH=/path/to/mlx-audio make xcode-build

The local package participates in dependency resolution, so its pyproject.toml metadata replaces the published package metadata. A sibling ../mlx-audio checkout on the main branch is detected automatically, matching the existing local mlx-vlm behavior.

By default, the app exposes its server at http://127.0.0.1:8080. You can change the host and port in the Developer page, which also lists every available endpoint and lets you copy URLs directly.

For example, with a model selected:

curl http://127.0.0.1:8080/v1/chat/completions \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "your-model-id",
    "messages": [{"role": "user", "content": "Why is the sky blue?"}],
    "stream": false
  }'

If you enabled a server API key, also send it as a Bearer token:

-H 'Authorization: Bearer your-api-key'

The server includes:

• OpenAI-compatible /v1/chat/completions, /v1/responses, /v1/models, image, and audio routes.
• Anthropic-compatible /v1/messages and token-counting routes.
• /health, /metrics, cache statistics, cache reset, and model unload endpoints.

Sources/
├── Nativ/                       # SwiftUI application
│   ├── Features/
│   │   ├── Artifacts/
│   │   ├── Chat/
│   │   ├── Dashboard/
│   │   ├── Developer/
│   │   ├── Extensions/         # Extension registry, broker, and management UI
│   │   ├── ImageGeneration/
│   │   ├── Integrations/
│   │   ├── IssueReport/
│   │   ├── MCP/
│   │   ├── Models/
│   │   ├── Routines/
│   │   ├── Settings/
│   │   ├── Shared/
│   │   ├── VoiceCapture/
│   │   └── SystemMonitor/
│   ├── Assets.xcassets/
│   ├── ModelProviderIcons/
│   └── Utilities/
├── NativExtensionSDK/           # Versioned extension manifests and XPC contracts
└── NativServerKit/              # Embedded server and Swift clients
Extensions/
└── VoiceDictation/              # Audio extension (legacy internal target name)
PythonDistribution/
├── Launcher/                    # Relocatable server launcher
├── Requirements/                # Pinned Python dependencies
└── Scripts/                     # Bundle assembly and verification
Configuration/                   # App metadata and signing settings
Design/                          # Brand source files and README artwork
scripts/                         # Archive, signing, notarization, and release tools
project.yml                      # XcodeGen project definition

See Docs/extending/extensions.md for the extension package format, lifecycle, permission model, and the steps for adding another first-party extension.

Generate and build the Xcode project:

make xcode-generate
make xcode-build

Verify that the bundled executable can launch and print mlx_vlm.server help:

make xcode-smoke

Exercise the long-running process lifecycle and /metrics readiness:

make xcode-lifecycle-smoke

Built for fast, local inference on Apple silicon.