Distiller docs

Getting started

Distiller runs on Apple silicon Macs with macOS 14 or later. Download the latest release (Distiller.dmg, signed and notarized), open it and drag Distiller to Applications. All releases have notes on what changed. You can also build it from source with Xcode 16 or later. The same engine is available as the distiller command-line tool: swift run distiller --help lists what it can do.

First run

The Setup Assistant opens when something required is missing. It first asks where to keep Wine builds and bottles: the support folder, or a larger external drive (APFS or Mac OS Extended). Then it checks for and installs:

• Rosetta, which today's Wine builds need (macOS asks for an administrator password).
• Wine: a recent Wine build for macOS, downloaded from its publisher's releases and checked against the published checksum.
• winetricks and cabextract, for Windows components such as fonts and runtimes.
• DXMT and DXVK, open-source graphics layers.
• D3DMetal, Apple's graphics layer, which Distiller never downloads for you: Apple's licence requires you to download the Game Porting Toolkit yourself. The assistant links to Apple's page and imports the disk image you downloaded.

Installing games

Find a game on the Games page or in the app's Community tab. Recipes are ranked by how they ran on Macs like yours.

Install in Distiller on a game's page opens Distiller with that recipe. Distiller looks the recipe up in the catalogue itself, shows what it will do (which publisher's installer it downloads, from where) and waits for you to click Install. It then makes a new bottle, applies the recipe's settings and runs the game's official installer. The game appears in your Library; double-click it to play.

Links from the website only ever name a game and a recipe in the catalogue. A link can't make Distiller install anything without your confirmation, or install anything that isn't in the catalogue.

Adding your own games

Create Recipe… (⌘N) starts from one of three places:

• A game already on your Mac: choose its folder and the program to launch. Distiller reads the program's imports to suggest a graphics layer, Windows version and components. Big games on an external drive can be used where they are: Distiller gives the drive a Windows letter, so the game updates its own files.
• A Windows installer: Distiller runs it in a new bottle, then you pick the program it installed.
• An empty bottle that you set up yourself.

Every game you build opens in the recipe workshop: choose the program, adjust settings, run installers and Wine tools, edit the recipe's YAML, and play to test.

Graphics layers and tuning

Windows games draw with Direct3D; a graphics layer translates that for your Mac:

• D3DMetal (Apple, from your Game Porting Toolkit download): Direct3D 9–12 on Metal.
• DXMT: Direct3D 10 and 11 on Metal.
• DXVK: Direct3D 9–11 on Vulkan, through MoltenVK.
• WineD3D: Wine's own, through OpenGL; the most compatible and usually the slowest.

D3DMetal and DXMT need a Wine build that exports the macOS driver's functions; Distiller checks each Wine build and only offers the layers it can run. Performance & display in the workshop has curated options, such as asynchronous shader compilation and frame-rate limits for DXVK, MetalFX upscaling for DXMT, and the Metal performance HUD. Each one is a recipe setting, so it's shared with the recipe.

Sharing a recipe

Shared recipes must install the game from its publisher's official, public installer and download nothing else of the game. Before you submit, run the community check from the Submit window:

To find the installer's link, use Get from Download Page… in the recipe workshop's Official installer section. Distiller opens the publisher's download page in a private browser (nothing is kept); click the download for Windows as usual. Distiller saves the installer, notes the page and every link the download went through, and checks which one a player's Distiller can download directly, without the page's cookies and without links that expire. That link and the page go into the recipe.

Some publishers have no link that works on its own. Then choose Use the Download Page: the recipe keeps only the page, and when a player installs the game, Distiller opens that page in its private browser for them to click the download. Distiller checks the file is the same installer, by its checksum or, for installers that change with updates, its publisher's signature, before it installs anything. On the command line, distiller install shows the page and asks for the path of the file you downloaded.

1. Distiller makes a fresh bottle, downloads the official installer (recording its checksum), applies your recipe's settings and starts the installer. Follow its steps.
2. A small panel floats above everything from the moment the installer starts. Some installers finish; others start a launcher or the game themselves. Either way, choose the game's program from what's running in the test bottle, or start an installed one. Play until the game reaches its login screen or menu, and press ⌃⌥⌘S (or click Capture) whenever it shows something worth sharing, during the install too. Screenshots the game saves with its own key are picked up too. Capturing needs Screen Recording permission for Distiller.
3. Tell Distiller whether it works. Everything in the test bottle is stopped, and the bottle is removed.

Then Submit to Community… signs you in to GitHub with a one-time code (the GitHub button in the toolbar, or Settings), lets you choose up to three screenshots and the cover, and opens a pull request on distiller-recipes. A maintainer reviews it; once merged, it's on this site and in everyone's Community tab. Browsing and installing never need an account.

Reporting how it ran

After you play, Report How It Ran… opens a pre-filled form on GitHub: a rating from Platinum to Borked, optional frames per second, and notes. Reports include your Mac's chip, GPU cores, memory and macOS version, and nothing else about you. They decide how recipes are ranked for Macs like yours.

The recipe format

A recipe is YAML. This is the shape of one (abridged):

schema: 1
id: dxvk
game:
  title: Example Game
  slug: example-game
  installer:
    url: https://cdn.example-publisher.com/ExampleSetup.exe
stack:
  runner: { family: winehq, min_version: "11.0" }
  graphics: dxvk
prefix:
  windows: win10
  winetricks: [corefonts]
install:
  - download: { url: https://cdn.example-publisher.com/ExampleSetup.exe, sha256: "…", to: cache/ExampleSetup.exe }
  - run_windows: { path: cache/ExampleSetup.exe, wait: true }
env:
  DXVK_ASYNC: "1"
launch:
  exe: 'C:\Program Files\Example\Game.exe'
overlays:
  - when: { memory_gb: "<16" }
    note: Capped at 60 FPS on Macs with less than 16 GB of memory
    env: { DXVK_FRAME_RATE: "60" }

The schemas define every field, and the repository's contributing guide explains the rules. These example recipes show the format (they're examples, not real games):

Troubleshooting assistant

Getting a Windows game to run well in Wine can take some detective work: the right graphics layer, Windows version, runtime libraries and settings aren't always obvious, and a game that won't start rarely says why. To help, Distiller includes an AI troubleshooting assistant: a built-in MCP server that lets the AI app you already use look at the evidence with you, so it can diagnose problems and suggest a better configuration.

distiller mcp serves read-only troubleshooting tools over the Model Context Protocol, so an AI assistant you already use (Claude, ChatGPT, or a model running on your Mac in LM Studio or Ollama) can read a game's setup, launch logs, crash dumps and program details, and suggest recipe settings. It's most useful while you build a recipe for a new game and don't yet know which graphics layer, Windows version, winetricks components or DLL overrides it needs.

The assistant can't change, run or delete anything. It only reads a game's own folder and bottle, its answers are text and size-capped, and paths in your home folder are shown as ~.

Turn it on

The assistant is off until you turn it on. In Distiller ▸ Settings, open the AI Assistant tab and switch on Let AI assistants troubleshoot games. The Connect an AI Assistant window opens with the steps for each app below, filled in with the path on your Mac and ready to copy; Connection Steps… in the same tab opens it again. From a terminal:

distiller assistant on
distiller assistant setup lm-studio   # or claude-desktop, claude-code, chatgpt, ollama, other

Your assistant starts the server itself when it needs it. The server talks over standard input and output (stdio) and never listens on the network. In an app installed in Applications, the command is:

/Applications/Distiller.app/Contents/Helpers/distiller mcp

Turn the switch off once your games run and you just want to play. Connected assistants lose access at once, without being restarted.

What it can read

Where your data goes: Claude and ChatGPT send what the tools return (log lines, file contents, your Mac's setup) to their service, under that service's privacy terms. With a model in LM Studio or Ollama, everything stays on your Mac. Your assistant asks before each tool call, so you can see what's read.

Connect your assistant

Distiller doesn't change your AI app's settings. You add Distiller's command to the app's list of MCP servers, and the app starts Distiller's server whenever it needs it. The server runs only while that app uses it, and talks only to that app. Any app that supports local (stdio) MCP servers can connect: the steps below cover common ones, and for others, look for "MCP servers", "tools" or "integrations" in the app's settings.

Every app needs the same two things: the command (the path above) and the single argument mcp. Change the path if Distiller isn't in Applications.

{
  "mcpServers": {
    "distiller": {
      "command": "/Applications/Distiller.app/Contents/Helpers/distiller",
      "args": ["mcp"]
    }
  }
}

claude mcp add --scope user distiller -- /Applications/Distiller.app/Contents/Helpers/distiller mcp

[mcp_servers.distiller]
command = "/Applications/Distiller.app/Contents/Helpers/distiller"
args = ["mcp"]

{
  "mcpServers": {
    "distiller": {
      "command": "/Applications/Distiller.app/Contents/Helpers/distiller",
      "args": ["mcp"]
    }
  }
}

pip install ollmcp
OLLAMA_CONTEXT_LENGTH=32768 ollama serve      # in another terminal, if Ollama isn't running
ollama pull qwen3:14b
ollmcp --servers-json distiller-mcp.json --model qwen3:14b

/Applications/Distiller.app/Contents/Helpers/distiller mcp

From Wine settings to recipe fields

The assistant suggests changes in Wine's terms. This is where each one goes in a recipe, and in the recipe workshop:

Recipes can only use the winetricks components and environment variables on the recipes repository's allowlist; the workshop shows what's allowed.

Example: a recipe from scratch

An illustration of a typical session. Lantern Keep is a made-up Unreal Engine game; the log lines are the kind Wine and Unreal really write.

1. Start with Distiller's guess

   Choose Create Recipe…, give it the publisher's installer, and pick the game's program once it's installed. Distiller reads the program's DLL imports and suggests a starting point; here, DXMT, Windows 10 and no winetricks. Click Play. The game closes straight away, with no window.

2. Ask the assistant

   With the assistant on and connected, start a new chat:

   Use the Distiller tools to work out why Lantern Keep won't start. Look at its setup and its latest launch log, check the game's own logs and crash dumps, and inspect its program. Then tell me which recipe settings to change and why.

   The assistant calls list_games to find the game, get_game for its setup, and read_launch_log filtered to err: lines:

   err:module:import_dll Library VCRUNTIME140_1.dll (needed by L"C:\\Program Files\\Lantern Keep\\LanternKeep\\Binaries\\Win64\\LanternKeep-Win64-Shipping.exe") not found
   err:module:loader_init Importing dlls for L"C:\\Program Files\\Lantern Keep\\LanternKeep\\Binaries\\Win64\\LanternKeep-Win64-Shipping.exe" failed, status c0000135

   Assistant: The game can't load VCRUNTIME140_1.dll, part of the Microsoft Visual C++ 2015–2022 runtime. Its installer normally adds the runtime, but it didn't in this bottle. Add the vcrun2022 winetricks component.

3. Apply it and play again

   In the recipe workshop, add vcrun2022 under winetricks and play. This time a window opens and then closes. Ask the assistant to compare the new launch with the last one. It calls list_game_logs, which finds the game's own log and a crash folder in the bottle:

   ~/…/drive_c/users/you/AppData/Local/LanternKeep/Saved/Logs/LanternKeep.log
   ~/…/drive_c/users/you/AppData/Local/LanternKeep/Saved/Crashes/UECC-Windows-…/CrashContext.runtime-xml

   It reads the log with read_game_file and checks the program with inspect_program:

   LogD3D12RHI: Error: D3D12CreateDevice failed
   LogRHI: Error: No compatible D3D12 adapter found
   inspect_program: 64-bit · Unreal Engine · imports d3d12.dll, d3d11.dll, dxgi.dll

   Assistant: The game starts in DirectX 12 mode, and DXMT only translates DirectX 10 and 11. Unreal Engine games accept -dx11, so add that launch argument and keep DXMT. If the game has no DirectX 11 mode, switch the graphics layer to D3DMetal, which handles DirectX 12 (you import it from Apple's Game Porting Toolkit in Components).

4. Tune it for your Mac

   With -dx11, the game reaches its menu. On an 8 GB MacBook Air it stutters in busy scenes, so you ask for help. The assistant calls get_environment, sees 8 GB of memory and an 8-core GPU, and suggests two options from the workshop's Performance & display list: MetalFX upscaling, and steady 30 fps frame pacing. It also suggests applying them only to Macs with less than 16 GB, so players with more memory keep full resolution.

5. The finished recipe

   schema: 1
   id: dxmt
   name: DXMT, DirectX 11 mode
   game:
     title: Lantern Keep
     slug: lantern-keep
     installer:
       url: https://downloads.example-publisher.com/LanternKeepSetup.exe
   stack:
     runner: { family: any, min_version: "11.0" }
     graphics: dxmt
   prefix:
     windows: win10
     winetricks: [vcrun2022]
   install:
     - download: { url: https://downloads.example-publisher.com/LanternKeepSetup.exe, sha256: "…", to: cache/LanternKeepSetup.exe }
     - run_windows: { path: cache/LanternKeepSetup.exe, wait: true }
   launch:
     exe: 'C:\Program Files\Lantern Keep\LanternKeep\Binaries\Win64\LanternKeep-Win64-Shipping.exe'
     args: ["-dx11"]
   overlays:
     - when: { memory_gb: "<16" }
       note: MetalFX upscaling and 30 fps pacing on Macs with less than 16 GB
       env:
         DXMT_METALFX_SPATIAL_SWAPCHAIN: "1"
         DXMT_CONFIG: "d3d11.preferredMaxFrameRate=30;"

   Then run the community check and share it. Mention what you tried in the pull request; it helps reviewers and the next player.

Tips

• Change one thing at a time, play again, and ask the assistant to compare the new launch log with the previous one (read_launch_log keeps several).
• Turn on the Metal performance HUD (Performance & display) to confirm the game draws through Metal and to give the assistant frame rates to work with.
• Ask for the reason, not just the setting. A good suggestion points at a log line or an imported DLL; a guess doesn't.
• Wine's own debug output is off by default. The launch log mostly shows errors, and that's usually what's needed.

Safety and privacy

• Wine isn't a sandbox. Windows programs run with your permissions. Install games you trust.
• Recipes are data. They can download files with a checksum, change a bottle's settings and run Windows programs inside Wine, but never run commands on your Mac. Every path stays inside the game's bottle.
• No tracking. Distiller sends nothing about you anywhere. Reports and submissions happen only when you send them.
• Your GitHub sign-in asks only for access to public repositories, and the token stays in your keychain.

Contributing

Distiller and its recipes are developed on GitHub: nullfx/distiller for the app and this site, nullfx/distiller-recipes for recipes and reports. Every change arrives as a pull request reviewed by a maintainer. AGENTS.md explains the architecture and the rules, for people and AI coding agents alike.