Skip to content
ironflow

Installation

This guide covers how to install Ironflow on your machine.

All public install paths verify against Sigstore cosign keyless signatures — you can confirm any binary or image was built and signed by the official release pipeline before running it.

Licensing

Ironflow ships under the Functional Source License v1.1, Apache-2.0 future grant. Free for development, evaluation, personal projects, internal non-revenue tooling, education, and non-commercial research. A commercial license is required for any externally-facing production or commercial product feature. See Licensing for worked examples.

Server

You can run the Ironflow server using Homebrew, Scoop, Docker, a direct binary download, a Helm chart (Kubernetes), or by building from source.

Cluster mode

Multi-node clustering (--node-id, --nats-url) requires PostgreSQL plus external NATS. SQLite + embedded NATS is single-node only. See Self Hosting for cluster topology.

Terminal window
brew tap sahina/tap
brew install ironflow


# Start in dev mode — auth is bypassed, so the dashboard opens straight up
# and the API accepts calls with no key. SQLite, port 9123. Start here.
ironflow serve --dev

Other ways to run it:

Terminal window
# Custom port, and open the dashboard in your browser
ironflow serve --dev --port 8080 --open


# Wipe local dev state (SQLite DB, NATS store, blobs, keys) and start fresh
ironflow serve --dev --reset


# PostgreSQL instead of SQLite
IRONFLOW_DATABASE_URL="postgres://user:pass@localhost:5432/ironflow" ironflow serve --dev


# Real mode — auth on. First boot prints a dashboard email + password and
# writes an admin API key to .ironflow/.ironflow_bootstrap_key.json.
ironflow serve

--reset only works together with --dev, and only on SQLite.

The Homebrew formula resolves binaries from the public release mirror (sahina/ironflow-releases); no GitHub token is required.

See the ironflow serve CLI reference for all available flags and options.

Desktop App

Ironflow Desktop is a free GUI front-door to Ironflow. It bundles the engine, so you can run functions, browse events, and work with the AI agent without touching the CLI.

Download Ironflow Desktop

Builds for each platform:

  • macOS (Apple Silicon) — the supported platform. .dmg, signed and notarized, opens normally. No Intel build is published; Intel Macs are not supported.

  • Windows (x64) — experimental. Install via Scoop (scoop bucket add ironflow https://github.com/sahina/scoop-ironflow then scoop install ironflow/ironflow-desktop); the direct-download -setup.exe is not yet Authenticode-signed and triggers a SmartScreen warning.

  • Linux (x64 and arm64) — experimental. .AppImage, one per CPU. Match it to uname -m: x86_64 → -x86_64.AppImage, aarch64 → -arm64.AppImage.

    Keyring prompt on first launch. On GNOME you may see an Authentication required dialog asking to unlock the login keyring, sometimes with “the password you use to log in no longer matches that of your login keyring”. This dialog comes from GNOME Keyring, not Ironflow: the app encrypts stored secrets (provider API keys, the delete token) with the system keyring via libsecret. The message means the login keyring was created with a different password than your current one — typical after auto-login, a password change, or a cloned VM image. Cancelling lets the app start, but secrets fall back to obfuscation instead of encryption and the app shows an insecure-keychain warning. To fix it, reset the login keyring and sign in again:

    Terminal window
    rm ~/.local/share/keyrings/login.keyring

    Log out and back in; GNOME recreates the keyring with your session password. This deletes secrets other apps stored in that keyring. Alternatively, open Passwords and Keys (seahorse) and change the Login keyring password to match your account.

Windows and Linux builds ship on every release and auto-update, but are not regularly tested. See platform support for what that means.

The app auto-updates from the release feed, so you only download it once.

See the Ironflow Desktop guide for workspaces, templates, and the built-in agent.

TypeScript SDK

The TypeScript SDK is published as four packages under the @ironflow organization on npm. All packages are public and install without authentication.

PackageDescription
@ironflow/coreShared types, schemas, utilities (used by every other package)
@ironflow/nodeWorkers, serve handlers, step execution (Node.js)
@ironflow/browserReal-time subscriptions, workflow triggers (browser)
@ironflow/langgraphLangGraph saver — durable checkpoint surface for LangGraph agents
Terminal window
npm install @ironflow/core
npm install @ironflow/node     # for Node.js / server-side workers
npm install @ironflow/browser  # for browser / client-side
npm install @ironflow/langgraph

See the JavaScript SDK API reference for full package documentation.

Go SDK

The Go SDK is published to a public mirror on every release and indexes on pkg.go.dev. It is a drop-in Go module — no private-repo access required.

Terminal window
go get github.com/sahina/ironflow-go/ironflow@latest

Or pin to a version — mirror tags match the engine release, so take the tag from the releases page:

Terminal window
go get github.com/sahina/ironflow-go/ironflow@v0.0.0  # ← replace

See the Go SDK API reference for full documentation.

Contributing to the Go SDK

The engine source uses an internal module path (github.com/sahina/ironflow/sdk/go/ironflow) for in-repo imports. The public mirror rewrites the import path at sync time (see ADR 0022). When contributing, edit the engine source; the public mirror is verified by make mirror-go-check (a dry-run sync plus smoke build) and regenerated by scripts/mirror-go-sync.sh <version>.

Python SDK

The Python SDK is a generated client for the REST API (IronflowClient), plus a generated ConnectRPC client (IronflowRPC / AsyncIronflowRPC) for the capabilities REST does not expose — webhook management, agent tools, time travel, pub/sub consumer groups, function versioning. ConnectRPC is part of the default contract rather than an optional extra, so the package depends on connectrpc and pyqwest; the REST client itself uses only urllib and json from the standard library.

Install ironflow-py, not ironflow

Terminal window
pip install ironflow-py

The distribution name is ironflow-py; the import name stays ironflow. The bare name ironflow on PyPI belongs to an unrelated third-party project (a materials-science tool from the pyiron group), so pip install ironflow installs the wrong package. A virtualenv holding both has two claimants on the top-level ironflow module and the install order silently decides which wins.

Available from v0.33.0. Published from sahina/ironflow-py over PyPI Trusted Publishing, so every release carries an attestation binding it to a public commit.

Experimental — client only

The Python SDK provides client API methods only (emit events, list runs, manage resources). Worker execution runtime (step.run, step.sleep, push/pull mode) is not implemented. For durable step execution, use the Go SDK or TypeScript SDK. See the SDK Comparison matrix for the full feature breakdown.

The API it exposes, for reference (Python 3.10+):

from protobuf.wkt import Struct


from ironflow import IronflowClient, IronflowRPC
from ironflow.rpc import v1


client = IronflowClient(
    server_url="http://localhost:9123",
    api_key="ifkey_...",
)


with IronflowRPC(server_url=client.server_url, api_key=client.api_key) as rpc:
    # Emit an event
    rpc.events.emit(
        v1.TriggerRequest(
            event="order.placed",
            data=Struct.from_python({"order_id": "123", "total": 99.99}),
        )
    )


    # List runs
    runs = rpc.runs.list(v1.ListRunsRequest())

See the Python SDK API reference for full documentation.

Verifying Release Integrity

Every public artifact is signed via Sigstore cosign keyless. The expected signing identity is the release.yml workflow on a versioned tag in sahina/ironflow. If cosign verify ever fails on a downloaded artifact, do not run it — email the security address in the LICENSE with the exact cosign verify output.

cosign v3 single-bundle format (v0.22+)

Starting with v0.22, the release pipeline writes signatures in the modern single-bundle format (ironflow_<ver>_<os>_<arch>.tar.gz.bundle). Verification uses --new-bundle-format --bundle <file>, as shown in the Direct Binary tab above. Pre-v0.22 releases used the older split --signature + --certificate format — if you are upgrading from a v0.20 install and have verification scripts, switch them to the v3 form.

Next Steps