Getting Started

Start the server, scaffold a project, emit events, derive state, and time-travel through your system’s Continuous History — all in about five minutes.

Prefer a GUI?

Ironflow Desktop is a free app for macOS, Windows, and Linux that bundles the engine — download, open, and explore without the CLI. This tutorial uses the CLI.

Prefer an AI Agent?

Skip the walkthrough and paste this into your coding agent. It installs the engine and the skills, showing you each command first:

Read https://ironflow.run/start.md and set up Ironflow in this project.

To evaluate before you install the engine, install only the skills, then ask “does Ironflow fit this codebase?”:

npx skills add sahina/ironflow-releases

See AI Skills for the full route, and the AI Quickstart to build this same tutorial with an agent.

1. Start the Server

Homebrew

brew install sahina/tap/ironflow

# --dev bypasses auth — no dashboard login, no API key
ironflow serve --dev

Scoop (Windows)

scoop bucket add ironflow https://github.com/sahina/scoop-ironflow
scoop install ironflow/ironflow

# --dev bypasses auth — no dashboard login, no API key
ironflow serve --dev

Windows is experimental. See Installation for what that means.

Docker

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

For persistent data, mount a volume and point the SQLite DB at it (NATS storage is derived from --db):

docker run -p 9123:9123 \
  -v ironflow-data:/data \
  ghcr.io/sahina/ironflow-releases:latest serve --dev --db /data/ironflow.db

See Docker Compose for Docker Compose with PostgreSQL.

Docker Compose

Save this as docker-compose.yml:

name: ironflow
services:
  ironflow:
    image: ghcr.io/sahina/ironflow-releases:${VERSION:-latest}
    command: serve --dev --db /data/ironflow.db
    ports:
      - "${IRONFLOW_PORT:-9123}:9123"
    volumes:
      - ironflow-data:/data # Persists NATS JetStream and SQLite data
    healthcheck:
      test: ["CMD", "wget", "-q", "--spider", "http://localhost:9123/health"]
      interval: 10s
      timeout: 5s
      retries: 3

volumes:
  ironflow-data:

Then start it:

docker compose up

For a production setup with PostgreSQL and monitoring profiles, see Docker Compose — it covers docker-compose.single-node.yml, which lives in the public release repo.

Binary

Download the latest release from GitHub Releases for your platform, then:

./ironflow serve --dev

The server starts at http://localhost:9123 with:

• Dashboard at /
• API at /api/v1/*
• Health check at /health

The --dev flag disables authentication so you can start building immediately. No API keys or passwords needed.

Gitignore .ironflow/

Run as a local binary, serve keeps its state in .ironflow/ under the current directory: the SQLite DB, the embedded NATS store, blobs/, plus .ironflow_bootstrap_key.json (an admin API key) and .ironflow_jwt_secret. Add .ironflow/ to .gitignore before your first commit so those credentials never reach the repo — ironflow init projects already do. Passing --db moves all of it to that file’s directory; the Docker tabs above keep it inside the container or the mounted volume.

Production Mode

When you’re ready for real workloads, drop the --dev flag. Ironflow will auto-bootstrap an admin account and API key on first boot — see Security for details.

---

2. Create Your Project

TypeScript

ironflow init my-app
cd my-app

This scaffolds a working project with a function, projection, and worker — ready to run. ironflow init runs pnpm install automatically (falling back to npm install); pass --skip-install to opt out.

If you pass --skip-install

The install step is also what removes the template’s pnpm-workspace.yaml and pnpm-lock.yaml, which point at monorepo paths that don’t exist in your project. If you skip it, delete both files before running pnpm install yourself.

Go

ironflow init my-app --template go-quickstart
cd my-app

This scaffolds main.go and go.mod, then runs go get github.com/sahina/ironflow-go/ironflow@latest and go mod tidy. The module path defaults to the project name — pass --module github.com/you/my-app to set a real one.

Python

ironflow init has no Python template yet, so create the project by hand:

mkdir my-app
cd my-app
python -m venv .venv
source .venv/bin/activate   # fish: source .venv/bin/activate.fish
pip install ironflow-py

Install ironflow-py, not ironflow

The distribution name is ironflow-py; the import name stays ironflow. The bare name ironflow on PyPI belongs to an unrelated third-party project, so pip install ironflow installs the wrong package.

Step 3 gives you the one file this project needs, worker.py. See the Python SDK reference for the full surface.

Manual setup

You can also install the SDK directly: npm install @ironflow/node (TypeScript), go get github.com/sahina/ironflow-go/ironflow (Go), or pip install ironflow-py (Python) — see the Installation guide for details.

---

3. Understand the Code

TypeScript

Open worker.ts — this single file contains a function, a projection, and a worker:

import {
  createFunction,
  createProjection,
  createWorker,
  type IronflowProjection,
} from "@ironflow/node";

// ── Types ───────────────────────────────────────────────────────
interface OrderData {
  orderId: string;
  total: number;
  email: string;
}

// ── React: A function that processes orders ─────────────────────
// Every step is memoized. If the process crashes, it resumes
// from the last completed step. With recording enabled, every
// step is also permanently recorded for time-travel debugging.
const processOrder = createFunction(
  {
    id: "process-order",
    triggers: [{ event: "order.placed" }],
    recording: true,
  },
  async ({ event, step }) => {
    const data = event.data as OrderData;

    const order = await step.run("validate-order", async () => {
      return {
        valid: true,
        orderId: data.orderId,
        total: data.total,
      };
    });

    const payment = await step.run("process-payment", async () => {
      return {
        charged: true,
        amount: order.total,
        transactionId: `txn_${Date.now()}`,
      };
    });

    await step.run("send-confirmation", async () => {
      return { sent: true, email: data.email };
    });

    return { order, payment };
  },
);

// ── Derive: A projection that computes order statistics ─────────
// Projections are pure reducers. Every time an "order.placed"
// event is recorded, this reducer runs and the derived state
// is automatically persisted and queryable.
const orderStats = createProjection({
  name: "order-stats",
  events: ["order.placed"],
  initialState: () => ({ totalOrders: 0, totalRevenue: 0 }),
  handler: (
    state: { totalOrders: number; totalRevenue: number },
    event: { name: string; data: unknown },
  ) => ({
    totalOrders: state.totalOrders + 1,
    totalRevenue: state.totalRevenue + ((event.data as OrderData).total ?? 0),
  }),
});

// ── Start the worker ────────────────────────────────────────────
const worker = createWorker({
  functions: [processOrder],
  projections: [orderStats as IronflowProjection],
});

worker.start().then(() => {
  console.log("Worker started — listening for events");
});

Start the worker in a second terminal:

pnpm start

You should see the worker connect and register:

[ironflow-worker] Starting worker worker-… with 1 functions
[ironflow-worker] Registered function: process-order
[ironflow-worker] Connected to server at http://localhost:9123
[ironflow-worker] Projection runner started (streaming): order-stats

The scaffold’s own Worker started — listening for events line is inside worker.start().then(...), and start() is the poll loop — it resolves only when something calls worker.stop(). Do not wait for that line; the four above mean the worker is live.

Go

The Go SDK supports both push mode (Serve()) and pull mode (NewWorker()). The go-quickstart template uses pull mode and mirrors the TypeScript scaffold — ProcessOrder function with three steps plus an OrderStats projection. Open main.go:

package main

import (
    "context"
    "fmt"
    "log"
    "os"
    "os/signal"
    "syscall"

    "github.com/sahina/ironflow-go/ironflow"
)

type OrderData struct {
    OrderID string  `json:"orderId"`
    Total   float64 `json:"total"`
    Email   string  `json:"email"`
}

// React: A function that processes orders. Every step is memoized
// and permanently recorded for time-travel debugging.
var ProcessOrder = ironflow.CreateFunction(
    ironflow.FunctionConfig{
        ID:        "process-order",
        Name:      "Process Order",
        Mode:      ironflow.PullMode,
        Recording: true,
        Triggers:  []ironflow.Trigger{{Event: "order.placed"}},
    },
    func(ctx ironflow.Context) (any, error) {
        var data OrderData
        if err := ctx.Event.Data(&data); err != nil {
            return nil, fmt.Errorf("parse order: %w", err)
        }

        order, err := ironflow.Run(ctx, "validate-order", func() (map[string]any, error) {
            return map[string]any{"valid": true, "orderId": data.OrderID, "total": data.Total}, nil
        })
        if err != nil {
            return nil, err
        }

        payment, err := ironflow.Run(ctx, "process-payment", func() (map[string]any, error) {
            return map[string]any{"charged": true, "amount": data.Total}, nil
        })
        if err != nil {
            return nil, err
        }

        _, err = ironflow.Run(ctx, "send-confirmation", func() (map[string]any, error) {
            return map[string]any{"sent": true, "email": data.Email}, nil
        })
        if err != nil {
            return nil, err
        }

        return map[string]any{"order": order, "payment": payment}, nil
    },
)

// Derive: pure reducer over order.placed events.
var OrderStats = ironflow.CreateProjection(ironflow.ProjectionConfig{
    Name:   "order-stats",
    Events: []string{"order.placed"},
    Mode:   ironflow.ProjectionModeManaged,
    InitialState: func() map[string]any {
        return map[string]any{"totalOrders": 0.0, "totalRevenue": 0.0}
    },
    Handler: func(state map[string]any, event ironflow.ProjectionEvent, ctx ironflow.ProjectionContext) (map[string]any, error) {
        total, _ := event.Data["total"].(float64)
        // float64, not int. The runner JSON round-trips state between events,
        // so every number comes back as a float64 — an `.(int)` assertion
        // silently yields 0 and the count never advances past 1.
        totalOrders, _ := state["totalOrders"].(float64)
        totalRevenue, _ := state["totalRevenue"].(float64)
        return map[string]any{
            "totalOrders":  totalOrders + 1,
            "totalRevenue": totalRevenue + total,
        }, nil
    },
})

func main() {
    worker := ironflow.NewWorker(ironflow.WorkerConfig{
        Functions:   []ironflow.Function{ProcessOrder},
        Projections: []ironflow.Projection{OrderStats},
    })

    ctx, cancel := context.WithCancel(context.Background())
    defer cancel()

    sigChan := make(chan os.Signal, 1)
    signal.Notify(sigChan, syscall.SIGINT, syscall.SIGTERM)
    go func() {
        <-sigChan
        cancel()
        worker.Drain()
    }()

    log.Println("Worker started — listening for events")
    if err := worker.Run(ctx); err != nil {
        log.Fatalf("Worker error: %v", err)
    }
}

Note

Go SDK fully supports projections — see ironflow/projection.go and the Projections guide. The go-quickstart example ships this scaffold.

Python

Create worker.py — this single file contains a function, a projection, and a worker:

import time

from ironflow.projection import create_projection
from ironflow.worker import Worker, function


# ── React: A function that processes orders ─────────────────────
# Every step is memoized. If the process crashes, it resumes
# from the last completed step. With recording enabled, every
# step is also permanently recorded for time-travel debugging.
@function(id="process-order", triggers=[{"event": "order.placed"}], recording=True)
async def process_order(ctx):
    data = ctx.event.data

    order = await ctx.step.run("validate-order", lambda: {
        "valid": True,
        "orderId": data["orderId"],
        "total": data["total"],
    })

    payment = await ctx.step.run("process-payment", lambda: {
        "charged": True,
        "amount": order["total"],
        "transactionId": f"txn_{int(time.time() * 1000)}",
    })

    await ctx.step.run("send-confirmation", lambda: {"sent": True, "email": data["email"]})

    return {"order": order, "payment": payment}


# ── Derive: A projection that computes order statistics ─────────
# Projections are pure reducers. Every time an "order.placed"
# event is recorded, this reducer runs and the derived state
# is automatically persisted and queryable.
order_stats = create_projection(
    name="order-stats",
    events=["order.placed"],
    initial_state=lambda: {"totalOrders": 0, "totalRevenue": 0},
    handler=lambda state, event, ctx: {
        "totalOrders": state["totalOrders"] + 1,
        "totalRevenue": state["totalRevenue"] + event.data.get("total", 0),
    },
)

# ── Start the worker ────────────────────────────────────────────
# run() owns the event loop: the first Ctrl+C drains, a second stops.
if __name__ == "__main__":
    print("Worker started — listening for events")
    Worker(functions=[process_order], projections=[order_stats]).run()

Start the worker in a second terminal:

python worker.py

---

4. Emit Events

With the server and worker running, emit an event:

ironflow emit order.placed --data '{"orderId": "order-1", "total": 99.99, "email": "customer@example.com"}'

Watch the worker terminal — you’ll see the function pick up the event and execute each step.

Emit a few more to build up history:

ironflow emit order.placed --data '{"orderId": "order-2", "total": 49.50, "email": "another@example.com"}'
ironflow emit order.placed --data '{"orderId": "order-3", "total": 149.00, "email": "third@example.com"}'

From your application

The CLI is the fastest way to emit while you’re following along, but in a real app you’ll emit from your own code. The client is separate from the worker — emit from an API route, a background job, or anywhere else you have a server.

TypeScript

import { createClient } from "@ironflow/node";

const client = createClient({ serverUrl: "http://localhost:9123" });

const result = await client.emit("order.placed", {
  orderId: "order-4",
  total: 75.25,
  email: "fourth@example.com",
});

console.log(result.eventId, result.runIds);

Use emitSync() instead when you need the triggered runs’ results before responding — it blocks until every matched run completes and returns one result each. To target a single function by ID and get one result back, use invoke(functionId, { data }). See the Node SDK reference for idempotency keys, event versions, and metadata.

Go

client := ironflow.NewClient(ironflow.ClientConfig{
    ServerURL: "http://localhost:9123",
})

result, err := client.Emit(ctx, "order.placed", map[string]any{
    "orderId": "order-4",
    "total":   75.25,
    "email":   "fourth@example.com",
})
if err != nil {
    log.Fatal(err)
}

fmt.Println(result.EventID, result.RunIDs)

Use EmitSync() instead when you need the triggered runs’ results before returning — it returns one result per matched run. To target a single function by ID, use InvokeSync(). See the Go SDK reference for idempotency keys, event versions, and metadata.

Python

from protobuf.wkt import Struct
from ironflow.rpc import v1
from ironflow import IronflowRPC
from ironflow import IronflowClient

client = IronflowClient(server_url="http://localhost:9123")

with IronflowRPC(server_url=client.server_url, api_key=client.api_key) as rpc:
    result = rpc.events.emit(v1.TriggerRequest(event='order.placed', data=Struct.from_python({'orderId': 'order-4', 'total': 75.25, 'email': 'fourth@example.com'})))

print(result.event_id, result.run_ids)

The Python RPC client exposes events.emit. Its typed response has event_id and run_ids attributes.

---

5. See What Was Derived

The order-stats projection has been processing every order.placed event and maintaining a running total. Query it:

curl -s -X POST http://localhost:9123/ironflow.v1.ProjectionService/GetProjection -H 'Content-Type: application/json' -d '{"name":"order-stats"}' | jq '.stateValue // .state'

{
  "totalOrders": 3,
  "totalRevenue": 298.49
}

That’s the three CLI emits. If you also ran the SDK emit from the previous section, you’ll see 4 orders and 373.74 instead.

You didn’t write any aggregation queries. The projection derived this state automatically from the recorded events. Emit another event and query again — the state updates in real time.

From your application

Same query, from the SDK client:

TypeScript

interface OrderStats {
  totalOrders: number;
  totalRevenue: number;
}

const stats = await client.projections.get<OrderStats>("order-stats");

console.log(stats.state); // { totalOrders: 3, totalRevenue: 298.49 }
console.log(stats.lastEventSeq, stats.status);

Go

stats, err := client.Projections().Get(ctx, "order-stats")
if err != nil {
    log.Fatal(err)
}

fmt.Printf("%+v\n", stats.State) // map[totalOrders:3 totalRevenue:298.49]
fmt.Println(stats.LastEventSeq, stats.Status)

Python

from ironflow import IronflowRPC
from ironflow.rpc import v1

with IronflowRPC(server_url="http://localhost:9123") as rpc:
    result = rpc.projections.get(v1.GetProjectionRequest(name="order-stats"))
    state = result.state_value if result.state_value is not None else result.state
    print(state.to_python() if state is not None else None)
    print(result.registry.last_event_seq if result.registry else 0)

Projection state is in state_value or state. Registry metadata is in registry.

The TypeScript and Go clients return the materialized state plus the projection’s position in the event stream (lastEventSeq) and health (status), so you can tell fresh state from stale without a second call. Both accept a partition key to read one slice of a partitioned projection.

You can also see the projection in the Dashboard at http://localhost:9123 — navigate to Projections to see its status and current state.

---

5.5 See Durability in Action

What happens when something goes wrong mid-execution? Ironflow memoizes every completed step. If a function crashes, it resumes from the last successful step — not from scratch.

Try it: emit an event, then stop your worker mid-execution (Ctrl+C). Restart it:

This scaffold is too fast to interrupt

The quickstart’s three steps have no real work in them, so a run finishes in milliseconds and you will almost certainly hit Ctrl+C after it has already completed — nothing to resume, and nothing to wait for. Read this step for the mechanism. To actually catch a run mid-flight, follow Survive a Crash, whose first step sleeps 3 seconds specifically to give you a kill window.

TypeScript

pnpm start

Go

go run .

Python

python worker.py

The worker picks up the interrupted run and completes it from where it left off. Check the Runs page in the dashboard — you’ll see the run completed successfully despite the restart.

Resume timing

Expect 90 seconds to 3 minutes, not instant. A worker killed mid-step still holds a concurrency lease, so the run is reclaimed by the capacity scanner once that lease expires (90s) plus a 30s recovery grace — not by the stale-claim sweep, whose threshold --dev does lower but which skips any run holding a lease. The lease timings are compile-time constants with no flag or environment variable. See Crash recovery for the full mechanics.

This is memoized execution: each step.run() result is recorded as the function proceeds and checkpointed to the server on a ~1s debounce (checkpointInterval on createWorker, 0 to disable). Crash at step 3 of 5? Steps 1 and 2 aren’t re-executed — the resumed run replays them from cache and picks up at step 3.

---

6. Rewind Time

Every step of every function run was permanently recorded. You can rewind to any moment.

Dashboard

1. Open http://localhost:9123 and navigate to Runs
2. Click any completed run
3. Use the timeline scrubber at the top to drag back in time
4. Watch the step outputs change as you scrub — you’re seeing the exact state of the run at that moment
5. With a point selected, click Compare with Final State to see a diff of what changed between that moment and the run’s end

CLI

# List your runs
ironflow run list

# Replay a run frame-by-frame (replace with your run ID)
ironflow inspect <run_id> --replay

In replay mode:

• → or l — next frame
• ← or h — previous frame
• g — first frame, G — last frame
• j/↓ — navigate steps within current frame
• k/↑ — navigate steps up
• Tab — switch between Steps and Details panels
• q — quit

---

What Just Happened?

In five minutes, you built a system with Continuous History:

1. Emit — You recorded events (order.placed). These are permanent, immutable facts.
2. React — A function processed each event with durable, memoized steps. If the process had crashed mid-execution, it would have resumed from the last completed step — not restarted.
3. Derive — A projection automatically computed order statistics from the event stream. No queries, no batch jobs — the state is always up to date.
4. Rewind — This tutorial enabled recording: true, so you scrubbed through its recorded execution timeline and inspected step state.

This is Continuous History: events and recorded execution steps form an append-only history. Inspect what happened, replay when needed, and rebuild derived state without guesswork. Event history is inherent to entity streams. Execution-step history requires recording to be enabled.

Push and Pull Modes

This tutorial used Pull mode — a long-running worker that polls the server over HTTP for jobs. For serverless environments (Next.js, Lambda, Cloud Functions), Ironflow also supports Push mode — the server POSTs to your HTTP endpoint. Same functions, same SDK, different deployment model. See Workflows for details.

---

Next Steps

Event SourcingEntity streams with optimistic concurrency for domain modeling.

Projections Deep DiveManaged vs. external projections, partitioning, real-time subscriptions.

Time-Travel DebuggingSDK API, TUI replay, and dashboard timeline.

Scoped InjectionPause a running workflow, modify step outputs, and resume.

WorkflowsSteps, memoization, retries, parallel branches, sagas.

ArchitectureHow the platform works under the hood.

Platform ComparisonHow Ironflow compares to Temporal, Inngest, Hatchet, Restate, Kurrent, and Kafka.

DDD PatternsHow aggregates, CQRS, and sagas map to Ironflow primitives.

ExamplesQuickstart, DDD example, Go quickstart, and reference app.