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

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.

Server

Section titled “Server”

You can run the Ironflow server using Homebrew, Scoop, Docker, Docker Compose, or a direct binary download.

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 (fish):

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. Embedded NATS needs an explicit store directory here
# Set IRONFLOW_BLOB_URL and AWS credentials for an existing S3 bucket first.
# Keep this key file for restarts.
mkdir -p ./data
if not test -s ./data/jwt-secret
    sh -c 'umask 077; openssl rand -hex 32 > ./data/jwt-secret'
end
set -gx IRONFLOW_JWT_SECRET (cat ./data/jwt-secret)
IRONFLOW_DATABASE_URL="postgres://user:pass@localhost:5432/ironflow" ironflow serve --dev --nats-store-dir ./data/nats --bootstrap-key-file ./data/bootstrap-key.json


# Real mode — auth on. First boot writes an admin API key and the dashboard
# password to .ironflow/.ironflow_bootstrap_key.json, and prints the dashboard email.
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

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

Direct installs auto-update from the release feed. For Scoop installs, update with scoop update ironflow-desktop.

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

TypeScript SDK

Section titled “TypeScript SDK”

The TypeScript SDK is published as four packages under the @ironflow organization on npm. All packages are public and install without authentication. A fifth public package, @ironflow/agent, is a CLI, not an SDK library: it is the Ironflow agent for ACP editors, run with npx.

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/node     # for Node.js / server-side workers
npm install @ironflow/browser  # for browser / client-side
npm install @ironflow/langgraph

@ironflow/node, @ironflow/browser and @ironflow/langgraph each depend on @ironflow/core, so installing one pulls it in. Install @ironflow/core directly when your code imports from it. pnpm does not let you import a package that is not a direct dependency.

See the JavaScript SDK API reference for full package documentation.

Go SDK

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

Python SDK

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

The package ships the pull worker (ironflow.worker), the push handler (ironflow.serve), projections, and the REST and ConnectRPC clients. See the SDK Comparison matrix for the full feature breakdown.

A durable function and a client call, 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())
from ironflow.worker import Worker, function




@function(id="process-order", triggers=[{"event": "order.placed"}])
async def process_order(ctx):
    return await ctx.step.run("charge", lambda: {"charged": ctx.event.data["total"]})




Worker(functions=[process_order]).run()  # pull mode; blocks until Ctrl+C

See the Python SDK API reference for full documentation.

Verifying Release Integrity

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

Next Steps

Section titled “Next Steps”