Minirun

Run models larger than memory.
Weights stream from your SSD through a memory budget you set. Free, local, on Mac and iPhone.

English | 简体中文

Minirun is a native macOS and iOS app that runs open models whose weights are far larger than the device's memory. Instead of loading a model, it reads each layer — and only the experts the router picks — from an external NVMe SSD into a small, fixed set of buffers, hands them to MLX without copying, and releases them. The amount of memory in use is a number you choose before the run, and the runtime refuses a budget it cannot honor rather than exceeding it later.

• Bigger than memory. Kimi K3 (2.8 T parameters, 1.56 TB on disk) runs on an iPhone 16 Pro. DeepSeek V4 Flash (167 GB) holds a conversation on a Mac and on that phone.
• A memory budget you set. Floor, Balanced, Generous, or a number of your own. Minirun keeps resident what the budget pays for and streams the rest; the answer is byte-identical at every budget.
• Runs from your SSD. Add a folder on an external drive; Minirun finds the Minirun containers in it and streams their weights straight off it. Nothing is copied to the internal disk.
• Verified before it runs. Every file is digested against the published Hugging Face tree once; the runtime opens files only through descriptors from that verified set. Prompts, answers and telemetry never leave the device.
• Instruments. Decode rate, bytes read per token, footprint against the budget and the flow from storage, live while the model answers.

Models

Containers are byte-preserving repacks of the published checkpoints (no requantization), published at huggingface.co/nanguoyu and listed at minirun.dev/models. Speeds below are what the app shows on the reference devices — a MacBook Pro (M1 Pro, 32 GB) over a USB4 (40 Gb/s) enclosure, and an iPhone 16 Pro over its USB 3 port with a powered dock — and change with the drive, cable and budget.

        

What you need

• Mac: Apple silicon, macOS 15 or later.
• iPhone: iPhone 15 Pro or later (a USB 3 port), iOS 18 or later.
• An external NVMe SSD with room for the model — 2 TB for Kimi K3, 256 GB for DeepSeek V4 Flash. The enclosure and cable decide your speed more than the SSD does: use a USB4/Thunderbolt-rated cable, plug straight into the Mac, and on the iPhone hang the enclosure off a powered dock (the phone's port cannot power an NVMe enclosure by itself).

_{The whole setup: the phone, a USB4 NVMe enclosure and a powered dock. Kimi K3 lives on that drive.}

Get Minirun

Mac. Download Minirun.dmg, drag Minirun to Applications, open it. The app is signed and notarized, and checks for updates itself (Sparkle).

iPhone. Install TestFlight from the App Store, then open the public link on the phone: testflight.apple.com/join/QuYTybjV. iPhone 15 Pro or later, iOS 18 or later. Builds expire after 90 days; TestFlight updates them.

Or build the iPhone app yourself with Xcode

1. Open Apps/Minirun/Minirun.xcodeproj, select the Minirun-iOS scheme and your iPhone.

2. In Signing & Capabilities pick your Apple Developer team and change the bundle identifier to one of your own (a free personal team works; the app then re-signs every seven days).

3. On the phone, enable Settings → Privacy & Security → Developer Mode, then press Run. Or from a terminal:

   xcodebuild build -project Apps/Minirun/Minirun.xcodeproj \
     -scheme Minirun-iOS -destination 'generic/platform=iOS' \
     DEVELOPMENT_TEAM=YOUR_TEAM_ID \
     PRODUCT_BUNDLE_IDENTIFIER=com.example.minirun \
     -allowProvisioningUpdates
   

Quick start

1. Add storage. Settings → Storage → Add a folder… and pick a folder on the external drive (on iPhone, through the Files app). Minirun assesses the drive and lists the containers it finds.
2. Get a model. Settings → Models → Find Models shows the published containers; download one into that folder, or point at a copy you already have.
3. Verify. Verify all files digests the container against its published tree. On iPhone this continues in the background and finishes with a notification.
4. Chat. New chat, pick the model, pick a budget, send.

The full guide is at minirun.dev/docs.

Build and test from source

Requirements: an Apple-silicon Mac, macOS 15 or later, Xcode 26 or newer.

# Mac app, no signing team needed
xcodebuild build -project Apps/Minirun/Minirun.xcodeproj \
  -scheme Minirun-macOS -destination 'platform=macOS' CODE_SIGNING_ALLOWED=NO

# iOS app for the Simulator (needs an iOS platform installed in Xcode)
xcodebuild build -project Apps/Minirun/Minirun.xcodeproj \
  -scheme Minirun-iOS -destination 'generic/platform=iOS Simulator' CODE_SIGNING_ALLOWED=NO

# Tests: the app suite, then the package suites (use xcodebuild, not swift test)
xcodebuild test -project Apps/Minirun/Minirun.xcodeproj \
  -scheme Minirun-macOS -destination 'platform=macOS' CODE_SIGNING_ALLOWED=NO
xcodebuild test -scheme minirun-Package -destination 'platform=macOS' \
  -only-testing:MinirunKitTests -only-testing:MinirunRunnersTests

The Xcode project is generated from Apps/Minirun/project.yml; after editing it, run xcodegen generate in Apps/Minirun (XcodeGen).

Repository layout

Model weights are external artifacts governed by their own licenses; this repository grants no rights to any weights.

Contributing

Contributions are welcome under Apache-2.0. Every commit is signed off under the Developer Certificate of Origin 1.1; see CONTRIBUTING.md. Report security issues privately as described in SECURITY.md.

License and marks

Copyright (c) 2026 Dong Wang. Source code is licensed under the Apache License 2.0; see NOTICE and THIRD_PARTY_NOTICES.md. The license does not grant rights to the Minirun name and logo; see TRADEMARKS.md.

Website: minirun.dev · Docs: minirun.dev/docs · Contact: minirun.dev/contact