Skip to content
ironflow
Ironflow is pre-1.0: APIs can change between releases. Pin a version. What is ready →

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.

System requirements

Section titled “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 13 Ventura 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~210 MB~189 MB~210 MB each

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 Go 1.27 engine the app bundles, which requires macOS 13 Ventura (Electron 44 alone would still run on Monterey). Windows 7/8/8.1 were dropped by Chromium and are not supported. Linux x64 and arm64 AppImages are published; .deb packaging is 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

Section titled “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

Section titled “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.

Workspace overview

Section titled “Workspace overview”

A new workspace opens on Overview. The page shows four cards:

  • Agent usage shows tokens, turns and the reported cost for this workspace over 7 days, 30 days or all time. Subscription turns show Subscription. A turn without a reported cost shows as “without cost”, not as $0.
  • Engine shows the engine state, port and function version, with buttons to open the dashboard and to start or stop the engine.
  • Recent runs lists the last runs. Failed runs show first. Select a run to open it in the dashboard.
  • Recent chats lists the last agent conversations.

A Get started checklist also appears under the Engine card. It has four steps: engine running, connect an agent, ask the agent to build something, and take the 2-minute tour. It goes away when every step is done. Select Hide to hide it for this workspace.

The usage totals also include verification calls and commit-message drafts. The card then says “Includes N verification or draft calls”.

Ironflow records usage when a response finishes. A stopped Ironflow Agent turn (API-key models) may not be counted.

Ironflow keeps the usage record when you delete chats or workspaces. To delete it, open Settings → Ironflow Agent → Usage history and select Reset usage history.

Activity

Section titled “Activity”

Activity in the workspace panel shows what happened in the running engine. It opens on Failures: failed runs and failed step compensations, dead-lettered outbox items, open circuit breakers, and failed webhook deliveries. All activity also shows function changes, worker connections, requeued and discarded outbox items, and closed or half-open circuit breakers.

Activity records history. A failure in the list does not mean that the resource is still failing.

  • Select a record to see its saved facts. Open run and Open deliveries open the matching dashboard page.
  • Investigate in Chat opens a new chat with a question and the record’s evidence in the draft. Edit the question, then send it. Activity never sends a message or starts an agent.
  • For a dead-lettered outbox item, Requeue and Discard act on the engine. Discard asks you to confirm.
  • When new records arrive, New activity appears. The list does not move until you select it. Load older shows older records.

On first use, Activity imports failed runs from the previous 24 hours and the dead letters that are still queued. Other records start when Activity first connects. History details shows these limits.

The built-in agent

Section titled “The built-in agent”

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

Connect accounts under Settings → Ironflow Agent. Anthropic, OpenAI, OpenRouter and Google support multiple named accounts. Claude Code, Codex and Copilot each use one existing native login.

Use Add OpenAI account (or another provider’s Add account button), give it a name such as “Client A”, and connect it with the existing key, OpenRouter browser sign-in or Google Cloud flow. Names must be unique within a provider, including disabled accounts and its default account. Expand an account to change its connection, rename it, disable it or remove it. Removing an extra account erases its stored key and keeps its name in chat and usage history. Reusing a removed name shows account IDs where needed to distinguish its history. The original default account can be disconnected but cannot be removed.

With a workspace focused, Settings → Ironflow Agent → Bills to chooses the account for new chats in that workspace. Each provider has its own choice. Existing chats retain the account used for their first accepted request, including a request you stopped. Changing this workspace setting does not move their billing.

The chat picker lists the accounts and their models. Choosing a different API account for an established API chat asks you to confirm its billing change. The chat continues in place, with a billing divider in the transcript. Available model and reasoning choices are preserved. A chat’s removed, disabled, signed-out or unreadable account blocks new requests until you explicitly choose or reconnect an account. Disconnecting an original default account releases its saved model preference for new chats, which may use another connected provider. Existing chats and explicit named-account bindings keep their selected account.

Disabling or removing an account requires its running work to finish or stop first. Replacing a key leaves running work alone. A worker that still holds the old key restarts when idle; if it is busy, a request needing the updated credential asks you to retry after that work finishes. Draft calls use the workspace’s current billing default. Verification uses the account that authored the captured changes and reports an error if that account is unavailable. Both run in isolated, temporary workers.

Google Cloud accounts can use different project IDs and locations for billing. They share the existing gcloud Application Default Credentials login; they do not create separate Google logins. Adding a project can reuse that login. Choosing Change and signing in again runs Google login even if an ADC file already exists, so a revoked login can be repaired.

A corrupt account sidecar produces a visible reset notice. Each workspace/API provider, including workspaces created after the reset, needs an explicit Bills to choice, including an explicit choice of its default account, before new chats or drafts can use it. Choosing an account for an existing chat recovers only that chat; it does not recover other chats or workspace defaults. Unchanged native CLI logins remain usable. The original default accounts remain compatible with an older Desktop build.

  • 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.
  • GitHub Copilot. Drives GitHub Copilot CLI 1.0.85 or newer from the copilot binary on your PATH, using its existing GitHub login. Install it with npm i -g @github/copilot. Desktop starts it with the built-in MCP servers disabled, so a prompt-injected turn cannot use the GitHub token they carry to open pull requests or comment as you.

Switching to a source backed by a different runtime does not rewrite the chat you are in. Your next send forks a fresh conversation linked to it, and both carry a “Continued from” / “Continued in” banner so the thread stays followable. Account or runtime changes are refused while that chat has a running turn, before a linked child is created. Model and reasoning changes on the same account apply to its next turn. Other chats keep running. Native resume stays with the source that created it; a different source uses a linked continuation.

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

Edit, reload, and verify

Section titled “Edit, reload, and verify”

Desktop can start your application’s Dev command alongside the engine. Set it when adding a project, or edit the workspace to change it on the next start. Application dev commands require the project’s language runtime, package manager, and dependencies installed locally. Use your project’s watch command, such as npm run dev, with its own file watcher configured. Desktop starts the command; your toolchain watches files and restarts the application. An engine-only workspace has no application process to reload.

Try this loop with a running project:

  1. Fire an event that triggers your function, then open the resulting run in the dashboard. Note its input, steps, and result.
  2. Edit the function in your editor, or ask the agent to fix it. Save the file and let your dev command restart and register the updated function.
  3. Check Overview → Engine for Dev process and Functions vN. The function version appears after Desktop detects a registration change. You can also open the engine status in the workspace footer to inspect the dev command and its status.
  4. Fire a new event with the same test input. Inspect the new run’s steps and result, and check the projection or entity events your change should produce. A reload alone does not prove the fix.

With workspace write access, the agent has an ironflow_await_reload tool for the edit-to-test step. Ask it to wait for reload before emitting its verification event, and to report the resulting run ID. The wait compares registered function versions with the last version it tested. It is advisory: after about 15 seconds without a newer version it returns reloaded: false, and it does not prevent another emit. Treat that result as an unverified reload and check the dev process before accepting the test as evidence of the new code.

If the new run fails, open it from Recent runs or Activity, inspect the saved error and steps, and use Investigate in Chat to prepare a question with the failure evidence. Send it when ready. After the next edit, repeat the reload and new-event check. Open the agent’s dashboard evidence links to inspect the resources it used, rather than relying only on its final answer.

For a project outside Desktop, see Getting Started.

Give the agent workspace access

Section titled “Give the agent workspace access”

Select Approve workspace in the chat composer, read the dialog, and select Allow edits and commands. Approval applies to this workspace across chats and app restarts. It permits file edits, shell commands, and engine changes such as emitting events, invoking functions, and writing KV values or secrets. These actions can have effects that a file diff cannot undo.

In a Git repository, Desktop captures file changes after each agent turn for review. If the workspace is not a Git repository, the approval dialog offers Initialize git & allow edits and commands. This initializes the repository without committing anything.

To return the agent to read-only access, select Workspace approved in the composer and confirm Revoke, or use Settings → Ironflow Agent → Workspace access → Revoke. Wait for active agent turns to finish or stop them first. Settings also lets you revoke access while the workspace is stopped.

The source you choose affects command permissions. Ironflow Agent (API key), Claude Code, and Copilot commands can run with your user permissions and access paths outside the workspace. Codex normally uses an OS sandbox with writes limited to the workspace and network access off. Its separate Settings → Ironflow Agent → OS sandbox control can turn that boundary off for new turns if Codex cannot run with it. Turning it off allows those turns to access files and the network with your account’s permissions; running turns keep the permissions they started with.

Skills and engine tools

Section titled “Skills and engine tools”

Desktop bundles Ironflow skills for assessing fit, setting up a project, writing code, operating the engine, and looking up reference documentation. Open Skills in the workspace panel to inspect the available skills. Your project’s skills take precedence over skills with the same name from your home directory or the bundle.

Under Settings → Ironflow Agent → Skills → Your own skills, choose whether to load skills from ~/.agents/skills and ~/.claude/skills across workspaces. Changes apply on the next agent turn.

You do not need to copy the bundled skills into a project to use them in Desktop. When opening the workspace in another editor, its Open workspace in… menu offers Set up Ironflow skills here…. Confirm Write skills to export copies into .agents/skills/, with links in .claude/skills/ or copies where links are unavailable. Re-exporting replaces existing copies of those bundled skills, so keep any edits you want to preserve before confirming.

The agent also connects to the workspace’s engine through MCP tools. Read-only tools inspect resources such as functions, runs, events, and projections. Workspace approval enables tools that change engine state and the reload-wait tool used above. Desktop supplies the connection; you do not need to configure a separate MCP server for the built-in agent. See the MCP tools reference for operations and the MCP server guide to connect another coding agent.

Explore the dashboard

Section titled “Explore the dashboard”

Select Open dashboard on Overview’s Engine card to use these views:

  • Flow Map in the dashboard sidebar shows registered wiring and connections learned from runtime activity. Use it to follow events between functions and other resources. Some connections appear only after the relevant code has run.
  • Streams → select an entity → Time-Travel shows a window of entity events ending at the selected version, with the runs they triggered. Drag the version slider to inspect earlier history. Select Latest to follow new events again. Moving the slider changes the view; it does not restore or rewrite the entity.

See Entity streams for appending and reading entity events, and Event sourcing for the relationship between event history and derived state.

Where to go next

Section titled “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: