Quickstart

Run a Flux server, register a workflow, and execute it — in five minutes.

Go from “Flux is installed” to “I ran my first workflow and saw the result” in five minutes. You’ll register a workflow with the Flux server, execute it, and inspect the result.

  1. Write a workflow

    Create hello.py:

    from flux import ExecutionContext
from flux.task import task
from flux.workflow import workflow


@task
async def say_hello(name: str) -> str:
    return f"Hello, {name}"


@workflow
async def hello_world(ctx: ExecutionContext[str]):
    if not ctx.input:
        raise TypeError("Input not provided")
    return await say_hello(ctx.input)


if __name__ == "__main__":  # pragma: no cover
    ctx = hello_world.run("Joe")
    print(ctx.to_json())

    Two decorators: one task, one workflow. The @workflow-decorated function receives an ExecutionContext with whatever input you pass to .run().

  2. Run it directly

    python hello.py

    You should see JSON output containing "output": "Hello, Joe" plus the workflow’s execution metadata (event log, timestamps, status).

    That ran the workflow in-process. Flux recorded the execution to a .flux/ directory in your current working directory (auto-created on first run). No server, no worker, no networking. Useful for development; not how you’d run it in production.

  3. Start the Flux server

    Open a new terminal:

    flux start server

    The server listens on http://localhost:8000 and exposes a REST API plus the flux CLI’s transport. Leave this running; it blocks the terminal.

  4. Start a worker

    Workers are separate processes that pick up queued executions and run them, authenticating to the server with a bootstrap token.

    flux start server blocks its terminal, so open a second terminal and fetch a token from there:

    flux server bootstrap-token

    Copy the token. In the same second terminal, start a worker with it:

    export FLUX_WORKERS__BOOTSTRAP_TOKEN="<paste-token-here>"
flux start worker my-worker

    flux start worker also blocks. Without a worker, flux workflow run will queue executions but they’ll sit in CREATED state forever.

  5. Register and run via the CLI

    Open a third terminal (or background the worker and reuse the second one), then go to the directory containing hello.py:

    flux workflow register hello.py
flux workflow run hello_world '"Joe"'

    The first command registers the workflow with the server. The second invokes it. Input is a positional argument, JSON-encoded — a string is '"Joe"', a dict would be '{"key":"value"}'.

    You’ll see a JSON response with workflow_id, execution_id, and the initial state (CREATED or SCHEDULED). The worker picks it up within a second.

  6. Inspect what happened

    flux workflow list
flux execution list

    workflow list shows registered workflows; execution list shows recent executions with status. To see one execution in detail (use the execution_id from the previous step):

    flux execution show <execution-id> --detailed

    This prints the full event log — every task call, its input, its output, its timestamps.

What just happened

Flux recorded every step (the task call, its input, its output) to a durable event log. If your process had crashed mid-run, you could replay from the last completed task. That’s the whole pitch.

Next