Documentation hub

Learn FlowRunner
one workflow at a time.

Premium guides for building private, local-first AI automations on macOS. Start with Create Workflow, then expand into the rest of the product as the help hub grows.

Runs entirely on your MacNo cloud or API costsBuilt for custom workflows

Main functionality

Choose a part of FlowRunner.

This hub is designed to grow with the product. Create Workflow is fully documented today; the other sections are staged and visually ready for future guides.

Coming soon

My Workflows

How to manage your saved library, re-run workflows, and organize your local automation workspace.

Placeholder section
Coming soon

Marketplace

Guides for browsing curated workflows, evaluating fit, and adding new automations to your Mac.

Placeholder section
Available now

Create Workflow

Build your own AI-powered automation in six steps with inputs, steps, outputs, and local model prompts.

Read guide below ->
Coming soon

Settings

Model loading, performance defaults, and app-level preferences for local execution.

Placeholder section

Create Workflow guide

Build your own AI-powered automations in 6 steps.

Everything runs locally on your Mac. No cloud, no API costs. Start simple, test early, and refine your workflow one step at a time.

Foundations

Before you start

A workflow has three parts:

Inputs

What the user provides before running, such as files, folders, or text.

Steps

Operations that run sequentially, each passing output to the next step.

Outputs

What the user sees after the workflow completes.

Start simple

Begin with one input, one LLM Call step, and one output. You can always add more once the logic works.

Step 1

Metadata

Name, describe, and brand your workflow.

Workflow Name

Keep it short and action-oriented. Describe what the workflow does, not what it is. Good examples: "Resume Bullet Polisher", "Meeting Notes -> Action Items", "Contract Risk Scanner".

Description

Write one or two sentences explaining what the workflow does and what it produces. This appears in My Workflows before a user runs it.

Category

Pick the closest fit: Productivity, Development, Content, Finance, Legal, or Other.

Recommended Model

Qwen2.5 7B Instruct 4-bit is a strong default for most workflows. Use a larger model for complex reasoning and a 3B model for simple transforms when speed matters more.

Icon

Choose an SF Symbol that visually represents the workflow. It appears as the thumbnail in My Workflows.

Workflow type

Writing / rewriting

Suggested icon

square.and.pencil

Workflow type

Document analysis

Suggested icon

doc.text.magnifyingglass

Workflow type

Code / development

Suggested icon

chevron.left.forwardslash.chevron.right

Workflow type

Meeting / notes

Suggested icon

list.bullet.rectangle

Workflow type

Finance / invoices

Suggested icon

banknote

Workflow type

Data / reports

Suggested icon

chart.bar

Workflow type

Files / organization

Suggested icon

folder.badge.plus

Step 2

Inputs

Define what users provide before the workflow runs. Click Add Input to create each one. Most workflows need one to three inputs.

Label

What the user sees on the run form. Keep it descriptive and human-friendly, like "Resume Bullets File" or "Invoices Folder".

ID

This is how the input is referenced in prompt templates. It auto-fills from the label in snake_case. Use only lowercase letters, numbers, and underscores, and keep it unique within the workflow.

Required + Hint

Mark required inputs when the workflow cannot run without them. Use the hint field to tell users exactly what format to provide.

ID example

Resume Bullets File becomes resume_bullets_file. Once steps depend on an ID, avoid changing it.

Type

file

Shows

Single file picker

Best for

One document - .txt, .md, .pdf, code file

Type

folder

Shows

Folder picker

Best for

Batch processing - all files in a directory

Type

text

Shows

Single-line text field

Best for

Short input - a name, keyword, label

Type

textarea

Shows

Multi-line text field

Best for

Longer text - pasted content, instructions

Type

number

Shows

Number stepper

Best for

Limits, counts - e.g. "Max bullets to return"

Type

select

Shows

Dropdown menu

Best for

Fixed options - output format, language, tone

Step 3

Steps

Define the operations that process your data. Steps run sequentially from top to bottom. Each step receives data from an input or prior step and produces output the next step can reference.

Read Files

Reads one or more files and loads their contents into the workflow. Define a unique Step ID, choose a source input, optionally add a file pattern such as **, *.pdf, or *.md, and give the step an output label for progress UI.

LLM Call

This is where the workflow's intelligence lives. Use a descriptive step ID such as extract_data, summarize, or polish_bullets. Choose an input source, write the prompt, select a strategy, and set temperature and max tokens.

Writing effective prompts for local models:

  1. Define a role at the start, such as You are a professional resume writer specializing in tech industry roles.
  2. Specify the output format explicitly. For example: Return only the rewritten bullets, one per line, no explanations.
  3. Insert variables using chips below the prompt field, never by manually typing the reference.
  4. Keep prompts concise. If instructions exceed roughly 300 words, split the work into two sequential LLM Call steps.

Write File

Writes a step's output to disk. Choose a content source and a destination path such as {{output_folder}}/result.md. Always include a filename and extension.

Transform

Applies a built-in transformation without calling the model. Use operations like to_csv, to_markdown, or to_json.

Variable syntax

A step can only reference inputs or outputs from steps that appear before it in the chain.

User input

{{input_id}}

Example: {{job_title}}

Previous step output

{{step_id.output}}

Example: {{read_bullets.output}}

Step 4

Outputs

Define what users see after the workflow completes. Click Add Output to create each one. Most workflows need only one.

Output type

summary

Shows

Plain text in the output panel

Best for

Rewritten bullets, extracted data, summaries

Output type

rendered_markdown

Shows

Formatted markdown - headings, bold, lists

Best for

Reports, meeting notes, structured documents

Output type

file

Shows

Clickable link to the saved file

Best for

When you used a Write File step

Output type

Choose the display format that matches what your LLM Call step returns.

Source

Pick the step whose output should be shown. This is almost always your last LLM Call step.

Label

Use a clear result heading such as "Polished Resume Bullets" or "Extracted Invoice Data".

Step 5

Test Run

Run the workflow end-to-end before saving it. The test form is auto-generated from your inputs, so fill every required field with real sample data and click Run.

Preparing test data

Use a small representative sample. Five to ten items is enough to validate the logic without slowing iteration.

Reviewing the output

Ask whether the output matches expectations, whether the format is correct, and whether the model actually followed the prompt.

Indicator

Green dot + "Done"

Means

Step completed successfully

Indicator

Spinning indicator

Means

Step is currently running

Indicator

Red indicator + error

Means

Step failed - read the error message

Indicator

Elapsed / Tokens / Speed

Means

Performance info for LLM steps

If quality is poor, the fix is usually in the prompt rather than the step configuration. Tighten the instructions, then re-run.

After a successful run, click Save Workflow -> to move to Step 6.

Error

"No model loaded"

Likely cause

No model is selected

Fix

Go to Settings -> Models and load a model

Error

"File not found"

Likely cause

Selected file no longer exists

Fix

Choose the file again using the picker

Error

"Unresolved reference"

Likely cause

Variable typed manually instead of inserted via chip

Fix

Remove and re-insert using the chip

Error

Output is empty

Likely cause

Max tokens too low, or model didn't follow prompt

Fix

Increase max tokens; rewrite prompt

Error

Wrong output format

Likely cause

Prompt didn't specify format clearly

Fix

Add explicit instructions: "Return only X, one per line"

Step 6

Save

Review your workflow summary and save it to My Workflows. The workflow is stored locally at ~/Library/Application Support/FlowRunner/CustomWorkflows/ as a .flowrunner file and appears in your library immediately.

Exporting

After saving, you can export the workflow as a .flowrunner file and share it with colleagues via email or AirDrop. Custom workflows are local-only and are never uploaded anywhere.

Best practices

Tips & tricks

Always read files before sending to the model

Never connect a file input directly to an LLM Call. Insert a Read Files step first so the model receives text, not a file handle.

One output format per LLM Call

Do not ask one step to return JSON and a markdown summary at the same time. If you need both, use two sequential LLM Call steps.

Use temperature 0.2 for structured tasks

Anything that needs consistent, parseable output such as JSON, CSV, or lists should stay at a low temperature. Use higher values only when variation is intentional.

Name your step IDs well

Step IDs become part of your variable references. Renaming them later means updating every dependent reference manually.

Test with small files, then scale up

Validate the workflow with a tiny sample that runs in seconds, then move on to real data once the logic is proven.

Premium feature

Custom workflows stay on your machine.

Create Workflow is a Premium feature. Custom workflows run entirely on your Mac, and no data leaves your machine while you build, test, save, or export them.