iWF turns long-running workflows into ordinary service code on Temporal

Workflows are states, waitUntil conditions and execute actions

The distinctive part of iWF is that a workflow is not a sequence of function calls but a set of discrete states. Each state declares a waitUntil condition and an execute action, and the engine advances between states as conditions are met. Persistence is declarative too: a workflow ships a schema for its data and search attributes for querying, and interaction with the outside world goes through RPC for both reads and writes. That vocabulary is what the basic concepts wiki pages cover, with separate pages for WorkflowState, RPC and Persistence. The stated goal is to use as few concepts as possible, and reading the design this way makes the platform feel less like a workflow DSL and more like a state machine that happens to run on a distributed backend.

Durable timers and automatic retry are the reason the engine exists

The listed differentiators are worth reading closely because they describe the failure model rather than the happy path. The durable timer survives system failure, so a workflow waiting three days for an approval is not tied to a process that has to stay alive. Automatic retry applies to the background execution units, the WorkflowState objects, and the retry uses distributed backoff built on the same durable timer. This is the difference between a workflow engine and a cron job with a database table. The complication is that the durable timer and the state both live in the backend, so the workflow code stays small but the operational surface does not: you are running a Temporal or Cadence service alongside your own.

Two backends, and the Dockerfile makes the choice an environment variable

The repository is Go code that targets both Temporal and Cadence. go.mod pulls in go.temporal.io/sdk at version 1.44.1 along with the Temporal API and workflowcheck tooling, and also go.uber.org/cadence at version 0.17.1-0.20230105221902-f50f452a8eae with a comment noting the pin exists to pick up the GetUnhandledSignalNames API. The Dockerfile shows how that becomes a runtime choice: an environment variable BACKEND_DEPENDENCY defaults to the value temporal, alongside variables for HOST, SRC_ROOT, TEMPORAL_SERVICE_NAME and CADENCE_SERVICE_NAME. Building the image installs netcat-traditional, runs make bins and exposes port 8801, with the entrypoint pointing at script/start-server.sh. The module path is github.com/indeedeng/iwf and the project targets Go 1.24.0.

The all-in-one image is the fastest local setup, and it hides a limitation

For local development the README calls the all-in-one image the simplest option, since it bundles the iWF service and Temporal together and needs one command.

docker pull iworkflowio/iwf-server-lite:latest && docker run -p 8801:8801 -p 7233:7233 -p 8233:8233 -e AUTO_FIX_WORKER_URL=host.docker.internal --add-host host.docker.internal:host-gateway -it iworkflowio/iwf-server-lite:latest

Three ports are published: 8801 for the iWF service, 7233 for the Temporal service and 8233 for the Temporal WebUI. The separate image with docker-compose runs Temporal in its own container and, in the words of the documentation, offers slightly more power with more search attributes allowed. That last point is the trap. If you prototype on the lite image and then need a search attribute your production queries rely on, the difference between the two setups becomes the reason something breaks, so check the attribute limits before you build a workflow that filters on them.

docker-compose gives you the same three endpoints with more headroom

The second local option checks out the repository and starts the full image with a compose file.

docker pull iworkflowio/iwf-server:latest && docker-compose -f ./docker-compose/docker-compose.yml up

The endpoints are the same as before, the iWF service on http://localhost:8801/, the Temporal WebUI on http://localhost:8233/ and the Temporal service on localhost:7233, but Temporal is not bundled into the iWF container, which is what allows the larger set of search attributes. For anything beyond a first look, this is the setup to use. The repository layout supports it, with a docker-compose directory, a Dockerfile, a config directory and a script directory, and the README defers production deployment to a wiki page rather than documenting it here.

Three SDKs and a REST microservice boundary for each application

The framework ships as a coding framework plus a service, and the service side is REST based. iWF applications are described as all REST based micro-services that are easy to deploy, monitor, scale, version and operate with industry standards, which is the argument for putting a workflow engine behind an HTTP interface instead of embedding it in every service. Three SDKs exist, for Java, Go and Python, each with a separate samples repository, and the sample set covers money transfer as a SAGA pattern in all three languages, user sign-up, microservice orchestration, employer and job seeker engagement and subscription flows. The dynamic interaction story matters as much as the SDKs: external applications can reach into a running workflow through RPC, signals and internal channels.

MIT licensing and a service dependency are the real adoption cost

The licence is MIT, which is the simplest part of the decision. The cost sits elsewhere: iWF applications depend on a running orchestration service, and that service is backed by Temporal or Cadence, which is infrastructure you operate or procure. The tooling story is part of the value proposition, with commands for looking up running state definitions, skipping timers and enhanced resetting, but the documentation for those commands lives in the wiki rather than the repository. The repository also carries an iwf-idl directory, a gen directory, a replayTests directory and an integ directory, which tells you that interface definitions are generated and that workflow replay is part of the test story. Releases reached v1.20.0 on 2026-06-24 after v1.19.3 in January 2026, and the last push was on 2026-08-28.

Editorial conclusion

Adopt iWF when your workflows are long-running, wait on external signals, and need retries and durable timers that survive a service restart, and you already run Temporal or are willing to. Do not adopt it for a short job that fits in a queue worker, since a server plus SDK plus state model is real overhead. Verify first that the all-in-one image gives you the search attribute limits your production case needs, that your language SDK matches the workflow you are writing, and that the go.mod backend dependency choice between temporal and cadence matches the deployment you have already standardised on.

Frequently asked questions

Official sources

1. indeedeng/iwf on GitHub
2. Issues
3. License: MIT
4. README
5. Releases