TinyForge

Train, finetune, and experiment with tiny ML models, entirely on your Mac.

A native macOS studio for the whole local ML loop: browse a model, build a dataset, finetune it on your Apple Silicon GPU, try it out, and export it. No cloud, no notebooks, no toolchain to set up.

---

Why TinyForge

Finetuning a small model on your own data shouldn't require a GPU rental, a stack of Python scripts, and three different CLIs. TinyForge wraps the best of the Apple Silicon ML ecosystem (MLX, mlx-lm, PyTorch/MPS, and the HuggingFace stack) behind a clean, native app that walks you through one coherent workflow:

Get a model → Build a dataset → Finetune → Try it out → Export & share

Everything runs locally. Your data never leaves your machine.

Features

• 🔍 Model browser: search HuggingFace, view files & READMEs, and download with a live progress bar (Xet-accelerated). See what you've already downloaded at a glance.
• 🧱 Dataset builder: import HuggingFace datasets or local JSON/CSV/Parquet, preview rows, map columns into chat / instruction / completion formats, inspect token-length distributions, and split into train/validation.
• ⚡ Finetuning on the GPU: LoRA / QLoRA / DoRA / full finetuning via mlx-lm and a from-scratch tiny-LM engine (a small Llama-style model trained on your own text), all with live dashboards (loss, throughput, peak memory) and GPU/thermal telemetry.
• ✨ Inference playground: stream generations with sampling controls, compare base vs. finetuned side by side, and optionally run natively in Swift via MLX-Swift (no Python round-trip).
• 📦 Export & share: fuse adapters and export to safetensors and MLX (quantized), and push straight to the Hub with an auto-generated model card.
• 🗂️ Experiment tracking: every run, dataset, and export is recorded locally (SQLite) and browsable.
• 📥 Self-contained: ships as a signed, notarizable .app with a bundled Python runtime. Nothing to install.
• 🔄 Auto-updates: new releases download in the background and install on quit (Sparkle). Opt out in Settings, or check manually from the app menu.

Screenshots

Models: browse & manage downloads	Datasets: build training data
Finetune: configure & watch it train	Playground: base vs. finetuned

Requirements

• Apple Silicon Mac (M1 or later). MLX and the MPS backend require it.
• macOS 15+.
• For development: Xcode 26+, xcodegen, and uv. The first build downloads the Metal Toolchain (xcodebuild -downloadComponent MetalToolchain) for MLX-Swift's shaders.

Quick start

Run a release build

git clone github.com/skundu42/tinyforge && cd tinyforge
scripts/build_release.sh          # bundles Python, builds, signs → TinyForge.app
open build/Build/Products/Release/TinyForge.app

Run from source (development)

# 1) Backend deps
cd backend && uv sync && cd ..

# 2) Generate the Xcode project and run
cd App && xcodegen generate && open TinyForge.xcodeproj   # then ⌘R

In a debug build, the app finds the dev Python environment automatically, no bundling needed.

Tech stack

Layer	Tools
App	SwiftUI · Swift 6.3 · Swift Charts · swift-subprocess · mlx-swift-lm · XcodeGen
Backend	FastAPI · uvicorn · pydantic · uv
ML	MLX · mlx-lm · PyTorch (MPS) · transformers · accelerate · datasets
Hub	huggingface_hub (Xet)
Packaging	python-build-standalone · codesign · notarytool

Project structure

.
├── App/                  # SwiftUI macOS app (project.yml → Xcode project)
│   ├── Sources/
│   │   ├── Backend/      # process manager, API client, WebSocket clients
│   │   ├── DesignSystem/ # theme + reusable components
│   │   ├── Features/     # Home, Hub, Datasets, Training, Playground, Export, Settings
│   │   └── Telemetry/
│   └── Tests/
├── backend/              # Python orchestrator (uv project)
│   └── tinyforge/
│       ├── api/          # FastAPI app + routers
│       ├── hub/          # HuggingFace browse / download / cache / auth
│       ├── datasets/     # load / format / tokenize / registry
│       ├── train/        # mlx-lm & from-scratch LM runners, orchestration, registry
│       ├── infer/        # streaming generation
│       └── export/       # fuse / convert / push
├── scripts/              # bundle_python, sign, notarize, package_dmg, build_release
└── docs/                 # roadmap, packaging guide, screenshots

Testing

The project is built test-first. Logic is unit-tested with fakes; each milestone is verified end-to-end against the real toolchain (live HuggingFace, a real MLX finetune, a real MPS run, a real fuse, a bundled-runtime launch).

# Backend (114 tests)
cd backend && uv run pytest

# App (46 tests; -skipMacroValidation for the MLX-Swift macros)
cd App && xcodebuild test -scheme TinyForge -destination 'platform=macOS' -skipMacroValidation

Network/heavy end-to-end tests are opt-in: touch .run-network-tests to enable them.

Contributing

Contributions are welcome! A good loop:

1. cd backend && uv sync and cd App && xcodegen generate.
2. Make your change test-first: add a failing test, then the code.
3. Run uv run pytest and xcodebuild test. Keep them green.
4. Keep the design system (App/Sources/DesignSystem) consistent for any UI.
5. Open a PR with a clear description and, for UI work, a screenshot.

Found a bug or have an idea? Please open an issue.

License

Released under the MIT License. The TinyForge name and logo are part of this project; the bundled dependencies retain their own licenses.

Acknowledgements

Built on the shoulders of MLX & mlx-lm, PyTorch, HuggingFace, FastAPI, and uv.

_{Forged on Apple Silicon. 🔨✨}