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.

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.

docker pull ghcr.io/sahina/ironflow:latest
docker run -p 9123:9123 ghcr.io/sahina/ironflow:latest serve

The image is published to public GitHub Container Registry. To verify the signature before running:

cosign verify ghcr.io/sahina/ironflow:latest \
  --certificate-identity-regexp 'https://github.com/sahina/ironflow/.github/workflows/release.yml@refs/tags/v.*' \
  --certificate-oidc-issuer 'https://token.actions.githubusercontent.com'

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

# Replace VERSION with the latest release (see GitHub Releases)
VERSION=v0.20.2

curl -L -o ironflow.tar.gz \
  "https://github.com/sahina/ironflow-releases/releases/download/${VERSION}/ironflow_${VERSION#v}_linux_amd64.tar.gz"
curl -L -o ironflow.tar.gz.sig \
  "https://github.com/sahina/ironflow-releases/releases/download/${VERSION}/ironflow_${VERSION#v}_linux_amd64.tar.gz.sig"
curl -L -o ironflow.tar.gz.pem \
  "https://github.com/sahina/ironflow-releases/releases/download/${VERSION}/ironflow_${VERSION#v}_linux_amd64.tar.gz.pem"

# Verify the signature against the release-pipeline OIDC identity
cosign verify-blob \
  --certificate-identity-regexp 'https://github.com/sahina/ironflow/.github/workflows/release.yml@refs/tags/v.*' \
  --certificate-oidc-issuer 'https://token.actions.githubusercontent.com' \
  --signature ironflow.tar.gz.sig \
  --certificate ironflow.tar.gz.pem \
  ironflow.tar.gz

tar xzf ironflow.tar.gz
./ironflow serve

Substitute linux_amd64 with linux_arm64, darwin_amd64, darwin_arm64 (use .tar.gz), or windows_amd64 (use .zip) as appropriate.

Source access is governed by the LICENSE — see the Licensing guide for permitted purposes. If you have a commercial license that grants source access:

Prerequisites: Go 1.25+, Node.js 20+, pnpm, Buf CLI (for protobuf generation), Docker (PostgreSQL tests only).

git clone https://github.com/sahina/ironflow.git
cd ironflow

# Build and run
make dev

# Or build only
make build
./build/ironflow serve

See the Getting Started guide for details on building from source.

Published as an OCI Helm chart on GitHub Container Registry:

helm install ironflow oci://ghcr.io/sahina/charts/ironflow --version 0.20.2

The chart provisions a deployment, service, and optional PostgreSQL/NATS connections. See the chart values.yaml for tunables.

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

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 publicly available via GitHub:

go get github.com/sahina/ironflow/sdk/go/ironflow@latest

Or specify a version:

go get github.com/sahina/ironflow/sdk/go/ironflow@v0.20.2

See the Go 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.

Next Steps

Getting Started — Emit events, projections, and time-travel in 5 minutes
Self Host — Run Ironflow with PostgreSQL in production
Workflow Guide — Learn about recorded execution (durable workflows)
JavaScript SDK Reference — Full TypeScript/JavaScript API documentation
Go SDK Reference — Full Go API documentation
Licensing — Permitted purposes, worked examples, commercial licensing