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, 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 the server (SQLite, port 9123)
ironflow serve


# Custom port and open dashboard in browser
ironflow serve --port 8080 --open


# Persistent NATS storage
ironflow serve --nats-store-dir ./data/nats


# PostgreSQL backend
IRONFLOW_DATABASE_URL="postgres://user:pass@localhost:5432/ironflow" ironflow serve

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.

Availability

macOS on Apple Silicon (M1/M2/M3/M4) is available today. Windows and Linux builds appear on the releases page as they ship.

  1. Download the .dmg from the latest release.

  2. Open the .dmg and drag Ironflow Desktop into Applications.

  3. First launch: the app is not notarized yet, so macOS Gatekeeper may block it. Right-click the app and choose Open, then Open again. If it still won’t open, clear the quarantine flag:

    Terminal window
    xattr -dr com.apple.quarantine "/Applications/Ironflow Desktop.app"

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

TypeScript SDK

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

Package Description
@ironflow/core Shared types, schemas, utilities (used by every other package)
@ironflow/node Workers, serve handlers, step execution (Node.js)
@ironflow/browser Real-time subscriptions, workflow triggers (browser)
@ironflow/langgraph LangGraph 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:

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

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 regenerated by make mirror-go-check / make mirror-go-sync.

Python SDK

The Python SDK is an auto-generated HTTP client covering the full REST API surface. It is published to PyPI and has zero external dependencies (uses only urllib and json from the standard library).

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 yet implemented. For durable step execution, use the Go SDK or TypeScript SDK. See the SDK Comparison matrix for the full feature breakdown.

Terminal window
pip install ironflow

Requires Python 3.9+.

from ironflow import IronflowClient


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


# Emit an event
client.events_create(body={
    "name": "order.placed",
    "data": {"order_id": "123", "total": 99.99},
})


# List runs
runs = client.runs_list()

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