Skip to content
ControlCraft
Back to downloads

Desktop · Setup

Install ControlCraft Desktop

Three steps. About five minutes. After this, generation runs entirely on your machine — no requests leave your laptop.

One-liner install (skips the Gatekeeper warning)

Paste in Terminal. Downloads via curl so macOS never stamps the quarantine bit — no "Apple cannot verify…" dialog. Same outcome as the manual three-step path below.

macOS · curl | bash

curl -fsSL https://controlcraft.io/api/install/mac | bash
Windows / Linux equivalents

Windows · PowerShell

iwr -useb https://controlcraft.io/api/install/windows | iex

Linux · AppImage

curl -fsSL https://controlcraft.io/api/install/linux | bash

Or do it step-by-step:

  1. 1

    Install the ControlCraft app

    Grab the installer for your OS from the downloads page. Open the installer and complete the OS prompts. macOS users: drag ControlCraft.app into Applications.

  2. 2

    Install Ollama

    ControlCraft talks to a local LLM through Ollama. The desktop shell auto-detects it on first launch but doesn't bundle it — install once, used forever.

    macOS · Homebrew

    brew install ollama

    macOS · DMG · Linux · Windows

    # Download from https://ollama.com/download
# Run the installer; the `ollama` CLI ends up on PATH.
  3. 3

    Pull a vision model

    ControlCraft uses a vision-capable model so reference images actually inform the output. llava is the proven default (~4 GB download).

    Pull the default model

    ollama pull llava

    Faster alternatives — pick one that fits your machine:

    • ollama pull llama3.2-vision — sharper JSON output, ~7 GB
    • ollama pull qwen2-vl — strong image reasoning, ~5 GB
    • ollama pull llava:13b — higher fidelity, ~8 GB, needs >16 GB RAM

You're ready.

Launch ControlCraft. The first window opens to a prompt and a live model chip in the top-right showing llava · loaded · X GB once the model is warm. Click Generate to make your first motion graphic.

Diagnostics + advanced

Hardware recommendations
  • macOS · Apple silicon (M1+) · 16 GB RAM minimum, 32 GB recommended for the 13B-class models.
  • Windows / Linux · NVIDIA GPU with ≥8 GB VRAM for GPU-accelerated inference; CPU-only works but is ~6-10× slower.
Verify Ollama is reachable
curl http://127.0.0.1:11434/api/tags
# Should return: {"models":[{"name":"llava:latest", …}]}
Pin a different frontend URL

By default the desktop shell loads https://controlcraft.io. To point at a staging build:

MOTION_FORGE_FRONTEND_URL=https://staging.controlcraft.io open -a ControlCraft
Where data lives
  • macOS · ~/Library/Application Support/ControlCraft/
  • Linux · ~/.local/share/ControlCraft/
  • Windows · %APPDATA%\ControlCraft\

Per-session uploads land in your OS temp dir under mf-upload-… and are not retained automatically — export anything you want to keep.

Open the installer when the OS warns it's unsigned

We're shipping ControlCraft Desktop before the Apple Developer ID and EV Code-Signing certificate paperwork clears. Until those land, your OS will flag the installer as "from an unidentified developer." The binary is exactly what our CI built — no third-party rewrap — so you can safely bypass the warning. Pick the snippet for your platform.

macOS · "Apple cannot verify…" / "malicious software"

The fastest fix: strip the quarantine attribute Apple set when you downloaded the file. This is the same thing Right-click → Open does under the hood, but it works on the un-mounted DMG too.

One-liner — replace path if you renamed it

xattr -dr com.apple.quarantine /Applications/ControlCraft.app

Or via the GUI: System Settings → Privacy & Security → scroll to "ControlCraft.app was blocked" → Open Anyway. macOS 15+ requires you re-confirm with Touch ID after first launch — that unlocks the app for every subsequent open.

macOS · the DMG itself won't mount

xattr -dr com.apple.quarantine ~/Downloads/ControlCraft-*.dmg
open ~/Downloads/ControlCraft-*.dmg

Windows · SmartScreen "Windows protected your PC"

Click More info on the SmartScreen dialog, then Run anyway. If PowerShell flags the file with "file came from another computer", unblock it once:

PowerShell — adjust filename

Unblock-File -Path "$env:USERPROFILE\Downloads\ControlCraft-Setup-*.exe"

IT-managed laptops may needSet-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSignedfirst. Talk to your sysadmin before relaxing policy.

Linux · .AppImage won't launch

chmod +x ~/Downloads/ControlCraft-*.AppImage
~/Downloads/ControlCraft-*.AppImage

Linux · .deb refuses to install

sudo dpkg -i ~/Downloads/controlcraft_*.deb
# If dependencies complain:
sudo apt --fix-broken install

These steps will retire once our Apple Developer ID notarization and Windows EV Code-Signing cert are live — the installer will then launch with a single click on every platform. Tracked at desktop signing certs in the release runbook.

Troubleshooting
  • Local model chip stays grey: Ollama isn't running. ollama serve in a terminal — or restart the desktop, which auto-starts it.
  • First generate takes ~3 minutes: expected. Ollama loads the model into RAM on the first inference; subsequent generates are ~30-60s.
  • Engine port already in use: the shell picks a fresh port on every launch — restart fixes it.