Skip to content
ironflow

Ironflow Desktop

Ironflow Desktop is a free desktop app that bundles the Ironflow engine. Download it, open it, and you have a running Ironflow — no install, no Docker, no Node.js, and no CLI.

It is the fastest way to see Ironflow work. Everything you do in it maps onto the same engine, dashboard, and APIs described throughout these docs, so nothing you learn here is throwaway.

No API key required

The app, the engine, the dashboard, and the starter templates all work without credentials. Desktop also includes an optional built-in AI agent. To use it, connect a provider credential or sign in through a supported subscription CLI.

System requirements

macOSWindowsLinux
SupportSupported (Apple Silicon)ExperimentalExperimental
CPUApple Silicon (Intel Macs are not supported)x64 (64-bit Intel/AMD)x64 (64-bit Intel/AMD) or arm64 (aarch64)
OSmacOS 12 Monterey or laterWindows 10 (64-bit) or laterUbuntu 18.04+, Debian 10+, Fedora 32+, or equivalent
Package.dmg (or .zip)-setup.exe (or Scoop).AppImage (one per CPU)
Download~193 MB~171 MB~201 MB each

Platform support

macOS on Apple Silicon is the only supported platform. Windows and Linux builds are published on every release and auto-update normally, but they are experimental — they are not regularly tested. Intel Macs are not supported and no Intel build is published.

This is a capacity limit, not a technical one: Ironflow is built by one developer, working on Apple Silicon. Every platform’s build pipeline is green. If you hit a problem on one of them — or want to help look after one — open an issue on the releases repo.

Plan for roughly 1 GB of free disk (the app plus one workspace’s engine data) and 8 GB of RAM. Each workspace runs its own engine process, so memory scales with how many you keep running.

The macOS floor comes from the two runtimes the app bundles, which happen to agree: Electron 43 supports macOS Monterey and up, and so does the Go 1.26 engine. Windows 7/8/8.1 were dropped by Chromium and are not supported. Linux arm64 and .deb packaging are not built.

Not sure which Mac you have? uname -m prints arm64 on Apple Silicon (x86_64 means an Intel Mac, which the app does not support); sw_vers -productVersion prints your macOS version.

Install

Download Ironflow Desktop

Then follow the steps for your platform.

Download the .dmg, open it, and drag Ironflow Desktop into Applications.

macOS builds are signed with a Developer ID certificate and notarized by Apple, so they open normally — no Gatekeeper workaround needed.

Only an Apple Silicon build is published. On an Intel Mac macOS refuses it with “this application is not supported on this Mac”.

The app updates itself from the release feed, so you only download it once. Scoop installs are the exception — update those with scoop update ironflow-desktop.

Workspaces

A workspace is one Ironflow environment: its own engine process, database, and event store. You can create one two ways:

  • From a template — the app scaffolds a small working project, boots the engine, and seeds it with events so there is something to look at immediately. Best for a first look.
  • From your own project — point the app at a folder you already have.

Each workspace’s engine data lives under <your-project>/.ironflow/workspaces/<id>/, gitignored so it never shows up in your repo. Deleting a workspace removes that directory and nothing else — your source is untouched.

Once a workspace is running, the app hosts the standard Ironflow dashboard, so events, runs, projections, and time-travel debugging all work exactly as documented.

The built-in agent

Desktop ships with an AI agent that can inspect your local Ironflow — read runs, trace failures, and propose fixes.

Each workspace picks its own model source under Settings → Ironflow Agent → Model sources; the setting applies to the focused workspace only, so two workspaces can disagree.

  • Ironflow Agent (API key) — the default. Connect a provider account and the agent runs in-app, metered per token by your provider. Supported providers are Anthropic, OpenAI, OpenRouter, and Google (a Gemini API key, or gcloud Application Default Credentials for Vertex AI). Keys are stored encrypted by your operating system’s credential store.
  • Claude Code subscription. Drives the claude binary on your PATH, using its existing Claude login. Install it with npm i -g @anthropic-ai/claude-code; Settings shows the detected version and path and tells you when it is missing or too old. The agent asks before tool calls that need permission. Best-effort: Anthropic may change this without notice.
  • Codex. Drives Codex 0.150.0 or newer from the codex binary on your PATH, using its existing ChatGPT login. Ironflow never reads the login or substitutes an OpenAI API key. Desktop discovers the models and reasoning levels available to that ChatGPT account, supports image attachments and native conversation resume, and confines turns to the workspace with network access off. Granting workspace write access changes only that workspace from read-only to writable.

Switching between runtime-backed sources restarts the workspace’s agent runtime, so a switch is refused while a turn is in flight.

The agent is optional and off until you connect an account or a working CLI. Everything else in the app works without it.

Where to go next

Desktop is a front door, not a separate product — the engine inside it is the same one you get from Homebrew, Docker, or a binary download. When you are ready to work from the terminal or deploy somewhere: