Glossary

Short definitions for Flux's vocabulary — workflow, task, agent, replay, idempotency, namespace, principal, and roughly fifty more.

Terms used across the docs, each with a one- or two-sentence definition and a pointer to the canonical page. Use this when a doc page assumes a term you haven’t met yet.

Workflow and execution model

Workflow: An async Python function decorated with @workflow that orchestrates one or more tasks. The first parameter is always ctx: ExecutionContext[T]; subsequent parameters define the input shape. Learn more
Task: An async Python function decorated with @task that does one unit of work — an API call, a query, a transformation. Tasks are the unit of retry, cache, and resumability. Learn more
Agent: A specialization of a task that runs an LLM-powered reasoning loop with tools, memory, and structured-output options. Agents share the workflow's execution context and persistence model. Learn more
Execution: A single invocation of a workflow. Has a unique ID, an input, an event log, and a terminal state (COMPLETED, FAILED, or CANCELLED). Learn more
Event log: The append-only sequence of events that records every state transition during an execution. Replay walks the event log to reconstruct state. Learn more
Replay: Reconstructing execution state by walking the event log forward — recorded task outputs are returned without re-executing the task body; the workflow body re-runs from the top. Learn more
Checkpoint: The act of persisting one or more new events. ctx.checkpoint() flushes events through the registered checkpoint callable (HTTP POST for server-side, SQLAlchemy save for inline). Learn more
ExecutionContext: The ctx object passed as the first parameter of every workflow. Generic over the input type (ExecutionContext[T]); holds the input, the event log, and lifecycle flags like has_succeeded and is_paused. Learn more
Inline execution: Running a workflow in-process with workflow.run(input) against SQLite — no server, no worker, no network. Used for unit tests and ad-hoc scripts. Learn more
Pipeline: A builtin from flux.tasks that chains tasks so each receives the previous one's output. Called as await pipeline(t1, t2, t3, input=...). Learn more
Parallel: A builtin from flux.tasks that runs multiple task coroutines concurrently and gathers their results. Called as await parallel(coro1, coro2). Learn more
Determinism: The property that a workflow body produces the same calls in the same order every time it replays. Required for resume-after-pause to work correctly. Learn more
Idempotency: The property that running a task more than once with the same input produces the same observable effect as running it once. Flux retries failed tasks; idempotency is the task's responsibility. Learn more
Cache: Disk-backed, cross-execution storage of a task's return value, keyed by the task's internal ID. Enabled via @task.with_options(cache=True). Covers the return value only, not side effects. Learn more
Pause / Resume: A workflow can pause itself with await pause(name=...) (a builtin from flux.tasks) and resume later via flux workflow resume <workflow_name> <execution_id> <input>. Pause persists the execution state; resume rebuilds it via replay. Learn more

Security and identity

Bootstrap token: A one-time secret a worker presents during POST /workers/register to receive an API key and a service principal. Set via FLUX_WORKERS__BOOTSTRAP_TOKEN or [flux.workers] bootstrap_token; the registration endpoint is rate-limited (default 30/minute per client IP) to protect it. Learn more
Execution token: A short-lived JWT scoped to a single execution; used by the worker when calling back into the server during a workflow. Learn more
API key: A long-lived credential associated with a principal. Carried in the Authorization: Bearer <key> header. Learn more
Principal: An authenticated identity — a user, a service account, or a worker. Has zero or more role bindings. Learn more
Service account: A principal that represents a non-human caller (a worker, a scheduled job, a downstream service). Learn more
Namespace: A logical grouping for workflows. Permissions are scoped per namespace (workflow:billing:*:run). Set on the workflow via @workflow.with_options(namespace="billing"). Learn more
RBAC: Role-based access control. Permissions follow resource:scope:scope:verb with * wildcards. Learn more
Permission wildcard: A * in a permission string matches anything in that segment. workflow:*:*:run means "run any workflow in any namespace". Learn more
Built-in role: Roles that ship with Flux: admin (*), operator, viewer, worker. Learn more

Scheduling

Scheduler: The component inside the server process that polls for due schedules and dispatches workflows. Runs in every replica; on PostgreSQL each cycle executes as a fleet-wide singleton via an advisory lock, so no leader election is needed. Learn more
Cron expression: A five- or six-field cron string defining when a schedule fires. Built via cron("0 9 * * *") from flux.domain.schedule. Learn more
Interval schedule: A schedule that fires every N seconds, minutes, or hours. Built via interval(seconds=N). Learn more
Once schedule: A schedule that fires exactly once at a specific timestamp. Built via once(run_time=datetime(...)). Learn more
Schedule history: The log of schedule firings, scoped per schedule. Queryable via flux schedule history <schedule_id>; each entry carries started_at and completed_at timestamps. Learn more

Workers and dispatch

Worker: A process that registers with the server, opens an SSE stream, and claims workflows to execute. Run via flux start worker. Learn more
Runner: The pluggable backend a worker uses to execute a workflow: subprocess (the default — one credential-less child process per execution), inprocess (the worker's event loop, lowest latency), or docker (one container per execution). Workflows pin one via @workflow.with_options(runner=...); workers advertise enabled runners at registration. Learn more
SSE dispatch: The server uses Server-Sent Events to push scheduled workflows to workers. Workers hold the SSE stream open; the server publishes dispatch messages over it for executions in the WORKFLOW_SCHEDULED state. Learn more
Dispatch mode: The server-side dispatch strategy, [flux.dispatch] mode: poll (the default — a per-worker query loop) or event (one dispatcher per replica with PostgreSQL LISTEN/NOTIFY wakeups and batched claims — the scalable mode for large fleets). Learn more
Heartbeat: A periodic ping from the server to the worker (default every 10 seconds) confirming the SSE stream is alive. Configurable via [flux.workers] heartbeat_interval. The worker's reply is persisted to workers.last_seen_at, giving every server replica the same liveness view. Learn more
Capacity slots: The concurrent-execution budget a worker advertises at registration ([flux.workers] max_concurrent_executions, default 16; 0 = unlimited). The server never assigns work beyond a worker's free slots. Learn more
Drain: The graceful shutdown a worker performs on SIGTERM: stop accepting work, finish running executions up to [flux.workers] drain_timeout (default 60 seconds), flush terminal checkpoints, then exit. Learn more
Claim generation: A fencing counter on each execution claim. When an evicted worker's executions are reassigned, checkpoints from the stale claim are rejected with HTTP 409, so a partitioned worker cannot corrupt state after the partition heals. Learn more
Eviction grace: The time after a missed heartbeat before the server evicts the worker. Configurable via [flux.workers] heartbeat_timeout. Learn more
Module cache: The TTL-cached in-memory cache on each worker of compiled workflow modules. Default TTL is 300 seconds. Workflow source travels base64-encoded over SSE and is exec-loaded into a synthetic module name. Learn more
Affinity: A label-based matching rule on a workflow that constrains which workers can claim it. Set via @workflow.with_options(affinity={"gpu": "true"}). Learn more
Resource request: A ResourceRequest(cpu=2, memory="512Mi") on a workflow that constrains which workers can claim it. Matching metadata, not enforcement — Flux doesn't cgroup workers. Learn more

Storage and persistence

Output storage: A pluggable backend for storing large task outputs outside the event log. InlineOutputStorage (default) keeps the output in-row; LocalFileStorage writes it to disk and stores a pointer. Learn more
Encryption at rest: Secrets and config values are encrypted in the database using PyCryptodome AES with PBKDF2 key derivation. Requires [flux.security.encryption] encryption_key; never defaulted — set it explicitly and back it up with the database. Learn more
Retention: The background job ([flux.retention]) that deletes terminal executions and their events older than retention_days (default 30). Off by default; enable it in production or the execution-history tables grow without bound. Learn more
Schema migration: An Alembic-managed database schema change shipped inside the flux-core package. Migrations run automatically when the database is opened; legacy pre-Alembic databases are stamped and upgraded in place. Controllable via flux db upgrade|current|history. Learn more
Bootstrap secret: A loose term for the encryption key, bootstrap token, and other one-time secrets the operator must supply at install time. Learn more

Authentication providers

OIDC discovery: The OpenID Connect discovery document at <issuer>/.well-known/openid-configuration that publishes the IdP's JWKS endpoint, supported algorithms, and audience expectations. Flux fetches it on startup. Learn more
JWKS: JSON Web Key Set — the public keys an IdP publishes for verifying signed JWTs. Flux caches JWKS for a configurable TTL. Learn more
Clock skew: Tolerated drift between the IdP's clock and Flux's clock when validating token exp and iat claims. Configurable via [flux.security.auth.oidc] clock_skew. Learn more

MCP and services

MCP server: Flux's Model Context Protocol server, exposed via flux start mcp. Lets MCP clients (Claude, Continue, etc.) discover and call Flux workflows as tools. Learn more
MCP tool: A workflow or capability exposed through the MCP server. Each tool has a name, a description, and a JSON-schema input. Learn more
Workflow Service: A workflow exposed as an HTTP endpoint or MCP tool with a stable name, independent of execution. Learn more
Catalog: The store of registered workflows. Held in the database; populated by flux workflow register and auto-populated on first inline run. Learn more

Agents

Reasoning effort: A hint to LLM providers about how much compute to spend reasoning before producing the final answer. Mapped to provider-specific knobs (Anthropic's thinking budget, OpenAI's reasoning effort). Learn more
Tool approval: A human-in-the-loop checkpoint before an agent invokes a tool marked requires_approval=True. The agent pauses; a human approves or rejects via the CLI or API. Learn more
Structured output: Constrained output from an agent matching a Pydantic model. OpenAI, Anthropic, and Gemini enforce the schema at the API — Anthropic through a forced tool call. Ollama drops the constraint when tools are present and logs a warning when it does. Learn more
Working memory: The agent's short-term context — recent messages, current tool results, the active plan. Cleared when the agent session ends. Learn more
Long-term memory: The agent's persistent store — durable facts, summaries, and embeddings retrieved across sessions. Learn more
Dreaming: A periodic background process that consolidates working memory into long-term memory by summarizing, embedding, and pruning. Learn more
Delegation: An agent invoking another agent or a workflow as a sub-task. The sub-agent runs in its own context; results return to the parent agent. Learn more
Sub-agent: An agent invoked by another agent, typically with a narrower system prompt or tool set. Learn more
Plan: A multi-step structured output the agent commits to before acting. Replanning happens when a step fails. Learn more
Skill: A reusable bundle of tools and prompt fragments an agent can compose. Loaded from a skills_dir with path-traversal protection. Learn more

Reliability and error handling

Durable execution: A design pattern where a workflow's progress is persisted as it runs, so it can survive process crashes and resume from where it stopped instead of restarting. Flux implements it by recording each task result to an event log and replaying the log on restart. Learn more
Transient durability: A workflow mode (@workflow.with_options(durability="transient")) that persists only the outer execution lifecycle — no task-level checkpoints, at-most-once semantics, and no pause, approvals, or schedules. Built for high-frequency agent/mesh workflows; a same-worker call() to a transient workflow object skips the server round-trip entirely. Learn more
Hook: A user-supplied callable that runs at a workflow lifecycle event. on_complete runs when the workflow finishes; on_pause runs when it pauses. Learn more
Saga: A multi-step transaction with compensating actions. In Flux, modeled as a workflow where each forward task has a rollback defined; on failure, rollbacks run in reverse order. Learn more
Rollback: A compensating action defined on a task via rollback=.... Runs when the task or a downstream task fails, after retries are exhausted. Learn more
Fallback: An alternative action defined on a task via fallback=.... Runs when the task itself fails after retries; if the fallback succeeds, the workflow continues. Learn more
Retry chain: The error-handling sequence on a task: retry the task body, then run the fallback, then run the rollback. Each step emits its own event types so you can see in the event log which step ran. Learn more