Workflows

A workflow is a versioned graph of nodes that runs inside a container, started by an event, schedule, webhook, or human. The same engine powers every long-running operation in ProxifAI — agent runs, CI/CD pipelines, trigger-rule actions, and even chat — so they all share one execution model, one log surface, and one cost ledger.

Workflow types

Every workflow declares a type that sets sensible defaults (image, CPU, memory, runtime mode) and unlocks UI affordances. Defined in internal/workflows/runtime_broker.go.

Type	What it’s for	Default mode	Default resources
agent	Long-running coding-agent sessions	per_execution	2 CPU / 2 Gi
ci	Pull-request and push pipelines	per_execution	2 CPU / 1 Gi
chat	Per-message handlers for the AI chat	shared	1 CPU / 512 Mi
automation (default)	Triggered automations, scheduled jobs, glue	per_execution	1 CPU / 512 Mi

Override any of these with the workflow’s runtime_config. The type also drives chat-vs-flow tab routing in the UI and what fields show up in the YAML editor.

Authoring

Two tracks, both backed by the same workflow and workflow_version tables:

• Visual editor in Flows → New — drag-and-drop nodes (LLM, command, HTTP, parallel, loop, HITL, …), connect handles, set conditions. Saves as a draft revision.
• YAML in .proxifai/workflows/<name>.yaml — checked into your repo, synced into the database on every server boot, and editable via pfai workflow apply/compile/validate/lint. The schema is documented in internal/workflows/loader.go.

Switching between the two preserves the graph — they’re projections of the same graph JSONB.

Versioning lifecycle

Every save creates a new row in workflow_version. The workflow.active_version pointer decides which version executions actually run.

draft v3 ──────► publish v3 ──────► (active)
                       │
                       └─── promote v2 → (active again)
                       │
                       └─── restore v1 → new draft from v1's graph

State	What it means
draft	Editable; not eligible to fire on triggers/schedules
published	Frozen; can be active
archived	Hidden from default lists; runs preserved in history

pfai workflow publish/promote/versions/export/import/restore cover the lifecycle from the CLI; the UI’s Versions tab covers the same ground with a diff view.

Capabilities

• Multi-step graphs — DAG nodes with explicit handles for branch outputs (success, error, named conditions)
• Conditional logic — condition nodes branch on JS expressions evaluated against execution variables
• Loops — for_each over arrays and repeat_until with bounded iterations
• Parallelism — parallel nodes execute children concurrently with a cancel_in_progress concurrency group option
• Human-in-the-loop — hitl nodes pause execution, route an approval to the inbox, optionally Slack DM, and time out per the HITL scheduler
• AI agent steps — assign a node to one of the pre-built agent images (claude-code, cursor, copilot, opencode, aider, gemini-cli) or any container you build
• Sidecars — nodes that need a different image than the main runtime get a per-(execID, image) sidecar container, reused across nodes that share the image
• Sandbox — declarative allowed_hosts / blocked_hosts per workflow control egress
• Concurrency groups — serialize executions that share a key (e.g. one deploy at a time per environment)
• Retry, timeout, on-error — per-node retry counts, intervals, timeouts, and error-handling branches
• Artifacts — files written under /workspace (or declared paths) are collected at execution end and downloadable for 90 days

The unified Flows projection

Every long-running run in ProxifAI — workflow execution, agent run, CI pipeline, trigger-rule action, webhook delivery, @agent mention — is mirrored into the same workflow_execution view via internal/workflows/bridge. The Flows page in the UI is built on this projection, so cross-system filtering, search, and cost rollups all work uniformly.

A backfill runs on every boot to mirror legacy runs that pre-date the bridge (cmd/proxifai/main.go) — idempotent and safe.