← Back to Home

DwarfStar — Run DeepSeek V4 Flash and PRO Locally on Your Own Machine

2026-07-06

DwarfStar — Run DeepSeek V4 Flash and PRO Locally on Your Own Machine 🚀

What is it? DwarfStar (formerly ds4) is a self-contained native inference engine built specifically for DeepSeek V4 Flash and PRO models. Created by Salvatore Sanfilippo (antirez) — the legendary creator of Redis — it's a purpose-built C runtime that is completely independent: not a GGUF wrapper, not a fork of llama.cpp, but a bespoke engine optimized for DeepSeek V4's architecture. It ships with a CLI, an HTTP server, and an integrated coding agent, all running on your own hardware.

Why it's trending: DwarfStar hit 17,600+ GitHub stars in under two months because it solves a real problem: running quasi-frontier open-weight models locally. DeepSeek V4 Flash feels near GPT-5 level for coding and reasoning, and with DwarfStar's aggressive 2-bit quantization (routed MoE experts only), it runs comfortably on 96–128 GB MacBooks, NVIDIA DGX Sparks, and AMD Strix Halo machines. The same creator behind Redis brought his systems programming expertise to local LLM inference — and the community noticed. Distributed inference across multiple machines, SSD streaming for models larger than RAM, and a KV cache that treats your NVMe as a first-class citizen make this a genuinely novel take on on-device AI.

📋 Prerequisites

Before you start, make sure you have:

  • A machine with 96+ GB RAM (128 GB recommended for a comfortable experience)
  • macOS (Apple Silicon M3/M5 Max or M3 Ultra) or Linux (NVIDIA GPU with 48+ GB VRAM, or AMD Strix Halo)
  • Git and a C compiler toolchain (make, clang/gcc)
  • curl for downloading model weights
  • ~70 GB free SSD space for the Q2 quant, ~150 GB for Q4

🔧 Setup & Installation

1. Clone the Repository

git clone https://github.com/antirez/ds4.git
cd ds4

2. Download the Model Weights

DwarfStar only works with the official GGUFs published on Hugging Face. The download_model.sh script handles everything:

# For 96–128 GB machines (recommended)
./download_model.sh q2-imatrix

# For machines with 256+ GB RAM
./download_model.sh q4-imatrix

# For 512 GB machines — the full PRO model
./download_model.sh pro-q2-imatrix

The script downloads from huggingface.co/antirez/deepseek-v4-gguf, stores files under ./gguf/, and links ./ds4flash.gguf to your chosen model. It resumes partial downloads automatically with curl -C -.

3. Build the Engine

Choose the build target for your hardware:

# macOS with Apple Silicon (Metal)
make

# Linux with NVIDIA CUDA (DGX Spark / GB10)
make cuda-spark

# Linux with NVIDIA CUDA (other GPUs)
make cuda-generic

# Linux with AMD ROCm (Strix Halo)
make rocm

# CPU-only diagnostics (slow, for testing only)
make cpu

That's it — no Python, no Docker, no virtual environments. A single make produces the ./ds4 CLI binary and the ./ds4-server HTTP API server.

4. Verify Your Setup

Run a quick smoke test:

./ds4 -m ./ds4flash.gguf --nothink --prompt "Hello, who are you?"

You should see the model respond in a few seconds. On an M3 Max 128 GB with Q2 quant, expect ~26 tokens/second generation speed.

🏗️ How It Works

DwarfStar is designed around DeepSeek V4's unique architecture — a Mixture of Experts (MoE) model with a compressed KV cache that makes very long contexts practical. Unlike generic runners, every optimization is specific to DeepSeek V4's tensor layout.

DwarfStar Architecture

⚙️ Architecture Overview

DwarfStar's architecture has four main layers:

  1. User Interfaces — Three entry points: the CLI (./ds4) for interactive sessions, the HTTP Server (./ds4-server) for API access and tool calling, and the experimental ds4-agent for autonomous coding tasks. All three share the same inference backend.

  2. Inference Engine — The core ds4.c runtime. It handles prompt processing, tokenization (DeepSeek V4's custom tokenizer), graph compilation for the target backend, and KV cache management. This is not a generic LLM runtime — it's a narrow, DeepSeek-specific engine that achieves its speed by making strong assumptions about model structure.

  3. GPU Backends — Three hardware paths:

    • Metal (Apple Silicon) — the primary target, fastest path for MacBooks and Mac Studios
    • CUDA (NVIDIA) — optimized for the DGX Spark / GB10 and other local CUDA GPUs
    • ROCm (AMD) — supports Strix Halo systems like the Framework Desktop

  4. KV Cache System — The most innovative part of DwarfStar's design. DeepSeek V4's compressed KV cache allows SSD streaming: when the model is larger than available RAM, non-routed weights stay resident while routed MoE experts are loaded on demand from SSD. On modern Mac SSDs (7+ GB/s), cache misses are surprisingly tolerable. For fully in-RAM operation, the cache is a fast in-memory ring buffer with optional on-disk persistence.

Distributed Inference

DwarfStar supports splitting layers across multiple machines. A Q4 Flash model can run across two 128 GB MacBooks connected via Thunderbolt: each machine loads its own layer slice, activations flow over TCP, and the coordinator presents a unified CLI/API. Prefill is pipelined across machines for additional speed.

Speed Benchmarks

Machine Quant Prefill Generation
M3 Max, 128 GB Q2 58.52 t/s 26.68 t/s
M5 Max, 128 GB Q2 87.25 t/s 34.27 t/s
M3 Ultra, 512 GB Q2 84.43 t/s 36.86 t/s
M3 Ultra, 512 GB Q4 78.95 t/s 35.50 t/s
M3 Ultra, 512 GB PRO Q2 138.82 t/s 9.56 t/s
DGX Spark GB10 Q2 343.81 t/s 13.75 t/s

Generation speeds are for greedy decoding with 32K context. Prefill speeds benefit from chunked prefill and long-context optimization.

🚀 Usage

Interactive CLI

# Start an interactive session
./ds4 -m ./ds4flash.gguf

# With thinking mode enabled (slower but better reasoning)
./ds4 -m ./ds4flash.gguf --think

# Limit output tokens
./ds4 -m ./ds4flash.gguf --think --tokens 1500

HTTP API Server

# Start the server on the default port
./ds4-server -m ./ds4flash.gguf

# Listen on a specific port
./ds4-server -m ./ds4flash.gguf --port 8080

The server provides an OpenAI-compatible API endpoint, making it a drop-in replacement for any tool or agent that expects an OpenAI API. Point your coding agent at http://localhost:8080/v1 and it works immediately.

SSD Streaming (for Models Larger Than RAM)

# Automatic cache budget (recommended)
./ds4 -m ./ds4flash.gguf --ssd-streaming

# Manual cache size
./ds4 -m ./ds4flash.gguf --ssd-streaming --ssd-streaming-cache-experts 32GB

The automatic budget takes 80% of the Metal recommended working set, subtracts non-routed weights, and uses the rest for the routed expert cache. On 64 GB machines, start with an explicit 32 GB cache.

🧪 Verification Checklist

  • git clone, model download, and make complete without errors
  • ./ds4 -m ./ds4flash.gguf --nothink --prompt "Hello" responds correctly
  • Generation speed matches expected range for your hardware
  • ./ds4-server starts and responds at http://localhost:8080/v1
  • SSD streaming mode loads without crashes on memory-constrained hardware
  • KV cache persists across sessions (check --cache flag)

🔗 Resources

← Retour à l'Accueil

DwarfStar — Exécutez DeepSeek V4 Flash et PRO Localement sur Votre Machine

2026-07-06

DwarfStar — Exécutez DeepSeek V4 Flash et PRO Localement sur Votre Machine 🚀

Qu'est-ce que c'est ? DwarfStar (anciennement ds4) est un moteur d'inférence natif autonome conçu spécifiquement pour les modèles DeepSeek V4 Flash et PRO. Créé par Salvatore Sanfilippo (antirez) — le légendaire créateur de Redis — il s'agit d'un runtime C sur mesure complètement indépendant : ni un wrapper GGUF, ni un fork de llama.cpp, mais un moteur dédié optimisé pour l'architecture de DeepSeek V4. Il inclut une CLI, un serveur HTTP et un agent de codage intégré, le tout fonctionnant sur votre propre matériel.

Pourquoi ça cartonne : DwarfStar a atteint 17 600+ étoiles GitHub en moins de deux mois car il résout un vrai problème : faire fonctionner des modèles open-weight quasi-frontières localement. DeepSeek V4 Flash se rapproche du niveau GPT-5 pour le codage et le raisonnement, et grâce à la quantification agressive 2 bits de DwarfStar (experts MoE routés uniquement), il fonctionne confortablement sur les MacBooks 96–128 Go, les NVIDIA DGX Spark et les machines AMD Strix Halo. Le créateur de Redis a apporté son expertise en programmation système à l'inférence LLM locale — et la communauté l'a remarqué. L'inférence distribuée sur plusieurs machines, le streaming SSD pour les modèles plus grands que la RAM, et un cache KV qui traite votre NVMe comme un citoyen de première classe font de DwarfStar une approche véritablement novatrice de l'IA sur appareil.

📋 Prérequis

Avant de commencer, assurez-vous d'avoir :

  • Une machine avec 96+ Go de RAM (128 Go recommandés pour une expérience confortable)
  • macOS (Apple Silicon M3/M5 Max ou M3 Ultra) ou Linux (GPU NVIDIA avec 48+ Go VRAM, ou AMD Strix Halo)
  • Git et une chaîne de compilation C (make, clang/gcc)
  • curl pour télécharger les poids du modèle
  • ~70 Go d'espace SSD libre pour la quantification Q2, ~150 Go pour la Q4

🔧 Installation et Configuration

1. Cloner le Dépôt

git clone https://github.com/antirez/ds4.git
cd ds4

2. Télécharger les Poids du Modèle

DwarfStar fonctionne uniquement avec les GGUFs officiels publiés sur Hugging Face. Le script download_model.sh gère tout :

# Pour les machines 96–128 Go (recommandé)
./download_model.sh q2-imatrix

# Pour les machines avec 256+ Go de RAM
./download_model.sh q4-imatrix

# Pour les machines 512 Go — le modèle PRO complet
./download_model.sh pro-q2-imatrix

Le script télécharge depuis huggingface.co/antirez/deepseek-v4-gguf, stocke les fichiers dans ./gguf/, et lie ./ds4flash.gguf vers votre modèle choisi. Il reprend les téléchargements partiels automatiquement avec curl -C -.

3. Compiler le Moteur

Choisissez la cible de compilation pour votre matériel :

# macOS avec Apple Silicon (Metal)
make

# Linux avec NVIDIA CUDA (DGX Spark / GB10)
make cuda-spark

# Linux avec NVIDIA CUDA (autres GPU)
make cuda-generic

# Linux avec AMD ROCm (Strix Halo)
make rocm

# CPU seulement (diagnostic, lent)
make cpu

C'est tout — pas de Python, pas de Docker, pas d'environnements virtuels. Un simple make produit le binaire CLI ./ds4 et le serveur HTTP ./ds4-server.

4. Vérifier Votre Installation

Lancez un test rapide :

./ds4 -m ./ds4flash.gguf --nothink --prompt "Bonjour, qui êtes-vous?"

Vous devriez voir le modèle répondre en quelques secondes. Sur un M3 Max 128 Go avec quantification Q2, attendez-vous à ~26 tokens/seconde.

🏗️ Comment ça Fonctionne

DwarfStar est conçu autour de l'architecture unique de DeepSeek V4 — un modèle Mixture of Experts (MoE) avec un cache KV compressé qui rend les contextes très longs pratiques. Contrairement aux exécuteurs génériques, chaque optimisation est spécifique à la disposition des tenseurs de DeepSeek V4.

Architecture DwarfStar

⚙️ Architecture

L'architecture de DwarfStar comprend quatre couches principales :

  1. Interfaces Utilisateur — Trois points d'entrée : la CLI (./ds4) pour les sessions interactives, le Serveur HTTP (./ds4-server) pour l'accès API et l'appel d'outils, et l'agent ds4 expérimental pour les tâches de codage autonomes. Les trois partagent le même moteur d'inférence.

  2. Moteur d'Inférence — Le runtime ds4.c central. Il gère le traitement des instructions, la tokenisation (tokenizer personnalisé DeepSeek V4), la compilation de graphe pour le backend cible, et la gestion du cache KV. Ce n'est pas un runtime LLM générique — c'est un moteur spécialisé qui atteint sa vitesse en faisant des hypothèses fortes sur la structure du modèle.

  3. Backends GPU — Trois chemins matériels :

    • Metal (Apple Silicon) — la cible principale, le chemin le plus rapide pour MacBooks et Mac Studios
    • CUDA (NVIDIA) — optimisé pour le DGX Spark / GB10 et autres GPU CUDA locaux
    • ROCm (AMD) — supporte les systèmes Strix Halo comme le Framework Desktop

  4. Système de Cache KV — La partie la plus innovante de DwarfStar. Le cache KV compressé de DeepSeek V4 permet le streaming SSD : quand le modèle est plus grand que la RAM disponible, les poids non routés restent résidents tandis que les experts MoE routés sont chargés à la demande depuis le SSD. Sur les SSD Mac modernes (7+ Go/s), les misses de cache sont étonnamment tolérables. Pour un fonctionnement entièrement en RAM, le cache est un tampon circulaire rapide avec persistance disque optionnelle.

Inférence Distribuée

DwarfStar supporte la répartition des couches entre plusieurs machines. Un modèle Flash Q4 peut fonctionner sur deux MacBooks 128 Go connectés via Thunderbolt : chaque machine charge sa propre tranche de couches, les activations circulent via TCP, et le coordinateur présente une interface CLI/API unifiée. Le préremplissage est pipeline entre les machines pour plus de vitesse.

Benchmarks de Vitesse

Machine Quantification Préremplissage Génération
M3 Max, 128 Go Q2 58,52 t/s 26,68 t/s
M5 Max, 128 Go Q2 87,25 t/s 34,27 t/s
M3 Ultra, 512 Go Q2 84,43 t/s 36,86 t/s
M3 Ultra, 512 Go Q4 78,95 t/s 35,50 t/s
M3 Ultra, 512 Go PRO Q2 138,82 t/s 9,56 t/s
DGX Spark GB10 Q2 343,81 t/s 13,75 t/s

Les vitesses de génération sont pour un décodage glouton avec contexte 32K. Les vitesses de préremplissage bénéficient du préremplissage par lots et de l'optimisation des longs contextes.

🚀 Utilisation

CLI Interactive

# Démarrer une session interactive
./ds4 -m ./ds4flash.gguf

# Avec mode réflexion activé (plus lent mais meilleur raisonnement)
./ds4 -m ./ds4flash.gguf --think

# Limiter les tokens de sortie
./ds4 -m ./ds4flash.gguf --think --tokens 1500

Serveur API HTTP

# Démarrer le serveur sur le port par défaut
./ds4-server -m ./ds4flash.gguf

# Écouter sur un port spécifique
./ds4-server -m ./ds4flash.gguf --port 8080

Le serveur fournit une API compatible OpenAI, ce qui en fait un remplacement direct pour tout outil ou agent qui attend une API OpenAI. Pointez votre agent de codage vers http://localhost:8080/v1 et il fonctionne immédiatement.

Streaming SSD (pour les Modèles Plus Grands que la RAM)

# Budget de cache automatique (recommandé)
./ds4 -m ./ds4flash.gguf --ssd-streaming

# Taille de cache manuelle
./ds4 -m ./ds4flash.gguf --ssd-streaming --ssd-streaming-cache-experts 32GB

Le budget automatique prend 80% de l'espace de travail recommandé Metal, soustrait les poids non routés, et utilise le reste pour le cache des experts routés. Sur les machines 64 Go, commencez avec un cache explicite de 32 Go.

🧪 Liste de Vérification

  • git clone, téléchargement du modèle et make se terminent sans erreur
  • ./ds4 -m ./ds4flash.gguf --nothink --prompt "Bonjour" répond correctement
  • La vitesse de génération correspond à la plage attendue pour votre matériel
  • ./ds4-server démarre et répond sur http://localhost:8080/v1
  • Le mode streaming SSD se charge sans crash sur du matériel à mémoire limitée
  • Le cache KV persiste entre les sessions (vérifiez le flag --cache)

🔗 Ressources