Browse the Hugging Face Hub, run models locally on Apple Silicon via Osaurus, and chat from a real workspace window or a menu-bar quick agent. HF-MAC is the thin, honest native front-end — the unified macOS surface for the 8b-is stack: Osaurus (inference), entheai (agent), MEM8 (wave memory), MLX-QUANT (ternary Metal kernels), ayeOS (ternary daemon), FLUG-OS (packet-wave sampler), HF Accelerate (MPS training), and hf-mount (repo filesystem).
🌐 Official Web Site & Documentation: https://8b-is.github.io/hf-mac/
- Vision & Philosophy
- Key Features
- System Requirements & Memory Guide
- Architecture & Data Flow
- Codebase Structure
- Quick Start
- Osaurus Companion Setup
- Security & Data Sovereignty
- Building & Distribution
- Contributing & Community
- License
ahogy a dolgok vannak — on-device, private, real tokens/sec, no fake states.
Most AI desktop applications suffer from bloated electron wrappers, bundled Python environments, or secret telemetry scripts. hf.app was built with a different philosophy:
- Honest Front-End Architecture: The native Swift application handles user interaction, Hugging Face Hub discovery, and macOS UI integration. It never embeds MLX or Python runtimes directly.
- Dedicated Engine Separation: Local model execution, weights caching, and MLX quantization are delegated entirely to Osaurus — an optimized local inference engine running on
localhost:1337. - Data Sovereignty: Your prompts, conversations, and downloaded weights stay on your machine. Zero cloud telemetry.
| Feature | Description |
|---|---|
| ⚡ Apple Silicon Native | Built with pure Swift 5.9 and SwiftUI for macOS 14.0+, leveraging M1/M2/M3/M4 unified memory for maximum token throughput. |
| 🤗 Live HF Hub Explorer | Search millions of open-weight models directly from Hugging Face REST APIs with live metadata, model tags, and pull triggers. |
| 🜂 Dual Native macOS UI | Work in a standard desktop application window (WindowGroup) or invoke the lightweight menu-bar quick assistant (MenuBarExtra) anytime. |
| 🧠 MoE Optimizer Layer | Automatically classifies prompt intent (Code, Math & Reasoning, Summarization, Creative) and routes to specialized local models with expert system prompts. |
| 🔐 Keychain Token Isolation | Securely encrypt and store Hugging Face User Access Tokens in the system macOS Keychain using Security.framework. |
| 🌊 MEM8 Wave Memory | On-device wave interference recall — MEM8 frequency-band classification with entheai-aligned scoring. Zero network. |
| 🔺 ayeOS Ternary Ready | ModelSpeed badges ternary matrices at 12.80× compression via ayeOS MEMNET daemon. |
| 🧠 entheai Agent | Spawn entheai subprocess for fan-out decomposition, code analysis, project-wide ops — Ecosystem tab. |
| 🜂 Ecosystem Tab | Unified dashboard: Osaurus · entheai · ayeOS · MEM8 · MLX-QUANT — all status at a glance. |
| Offline First | Once local models are pulled into Osaurus, chat and prompt inference operate completely offline with no network requirement. |
| HF Storage Buckets | Native bucket management — create, sync, and stream training corpora with Xet dedup and the built-in CDN (hf buckets, hf sync). |
| quantal-ternary ready | The constellation's 0.5B BitNet b1.58 ternary model (masked val 0.5597) runs through the MLX-QUANT + ayeOS stack — 168 matrices, offline in Rust. |
- Operating System: macOS 14.0 (Sonoma) or later.
- Processor: Apple Silicon (M1/M2/M3/M4) or Intel Mac with dedicated Metal GPU.
- Local Engine: Osaurus running on
localhost:1337.
| Model Size | Recommended RAM | Suggested Quantization | Example Models |
|---|---|---|---|
| 3B – 7B Parameters | 8 GB – 16 GB | 4-bit / 8-bit MLX | Llama 3 8B, Phi-3-Mini, Mistral 7B |
| 8B – 14B Parameters | 16 GB – 32 GB | 4-bit MLX | Qwen 2.5 14B, Gemma 2 9B |
| 30B – 70B Parameters | 36 GB – 128 GB | 4-bit / 6-bit MLX | Llama 3.3 70B, Qwen 2.5 32B |
The system loop follows a clear 6-step pipeline:
Browse HF Hub → Pull to Osaurus → MoE Auto-Route → MEM8 Recall → ayeOS Ternary → Run & Chat (Private)
- Browse:
HubClientqueries the Hugging Face REST API (api-inference.huggingface.co) for model cards, tags, and creator metadata. - Pull: Model weights are downloaded and cached by Osaurus into unified memory.
- MoE Optimize:
MoEOptimizerclassifies prompt intent into domain experts (Code, Reasoning, Summary, Creative) and selects the best local model. - MEM8 Recall:
EntheaiMemoryretrieves relevant past spans via wave interference scoring — frequency proximity × amplitude × phase alignment. - ayeOS Ternary: Ternary models (BitNet b1.58, MLX-QUANT) route through ayeOS's
{n+-1-<△>}inference daemon — deterministic LINOSV-seeded matrices, block-sparse matmul at 12.80× compression.ModelSpeed.ternarybadges them instantly. - Run & Chat:
OsaurusClientstreams OpenAI-compatible/v1/chat/completionsSSE to SwiftUI glass components.
The codebase is organized into clean, single-responsibility Swift modules:
Sources/HFMac/
├── HFMacApp.swift # @main App entry point, WindowGroup & MenuBarExtra setup
├── MoEOptimizer.swift # Mixture of Experts intent classifier & dynamic model router
├── Services.swift # HubClient (HF Hub REST) & OsaurusClient (OpenAI /v1 API)
├── Views.swift # SwiftUI view hierarchy (Browse, Run, Your Models, MenuBar agent)
├── Keychain.swift # Security.framework wrapper for HF tokens
├── Memory.swift # MEM8 wave-based recall engine (on-device, zero network)
├── OfflineStore.swift # Local persistence & cached model state
├── WebView.swift # WKWebView bridge for interactive model cards & Spaces
├── VoiceEngine.swift # On-device TTS/STT (Apple-native, sidecar-ready)
├── ModelSpeed.swift # Model quantization speed classification
└── Theme.swift # Modern macOS dark glass mode tokens & styling constants
MoEOptimizer.swift: Implements domain classification (ExpertDomain) and intelligent expert model routing.Services.swift: ContainsHubClientfor Hugging Face REST search andOsaurusClientfor local OpenAI-compatible endpoint communication.HFMacApp.swift: The main application definition managing reactive@Observable AppState.Views.swift: Defines SwiftUI components for browsing, chatting, model management, and the floating menu-bar quick agent.Keychain.swift: Implements secure OS-level keychain access (dev.peterl.hfmac.token).Memory.swift: MEM8 wave-based recall engine — encodes spans as waves, scores relevance via interference.
Download the latest Developer-ID notarized .dmg release from our Releases Page, open the disk image, and drag HFMac.app to your Applications folder.
# 1. Clone the repository
git clone https://github.com/8b-is/hf-mac.git
cd hf-mac
# 2. Compile and run with Swift Package Manager
swift runOr open in Xcode:
open Package.swifthf.app relies on Osaurus for local model serving:
- Download and launch Osaurus on your Mac.
- Ensure Osaurus is listening on
http://localhost:1337. - Pull your desired model inside Osaurus (e.g.
llama3:8b). - Click Refresh in the Run tab of
hf.appto instantly sync available local models.
- App Sandbox Entitlements: Enforced via
Packaging/hf-mac.entitlements(com.apple.security.app-sandboxandcom.apple.security.network.client). - Zero Telemetry: No tracking cookies, analytics SDKs, or diagnostic logging.
- Keychain Security: Hugging Face access tokens are encrypted in the macOS Keychain.
- See our full
SECURITY.mdpolicy for vulnerability disclosure guidelines.
Build targets and notarization processes are documented in PUBLISHING.md:
- Direct Notarized DMG: Automated build via
.github/workflows/release.ymlonv*tag pushes. - Mac App Store: Scaffolded in
.github/workflows/mas.ymlfor sandboxed App Store Connect upload.
Contributions are welcome! Please read our CONTRIBUTING.md guide for details on development setup, Swift style guidelines, and pull request procedures.
- Found a bug? Open an issue on GitHub Issues.
- Security concern? Refer to
SECURITY.md.
Distributed under the MIT License. See LICENSE for details.
🜂 ahogy a dolgok vannak — on-device, private, real tokens/sec, no fake states.