Flow’s organizational system creates a hierarchical structure that scales from individual projects to complex multi-project ecosystems. The system balances discoverability with isolation, enabling both focused work within projects and cross-project composition.

Hierarchy Structure

Workspaces serve as the top-level organizational unit, typically mapping to Git repositories or major project boundaries. Each workspace contains its own configuration, executable discovery rules, and isolated namespace hierarchy.

Namespaces provide logical grouping within workspaces, similar to packages in programming languages. They enable organizational flexibility. A single workspace might have namespaces for frontend, backend, deploy, or tools. Namespaces are optional but recommended for workspaces with many executables.

Executables are the atomic units of automation, uniquely identified within their namespace by their name and verb combination. This allows multiple executables with the same name but different purposes (build api vs deploy api).

Reference System

Flow uses a URI-like reference system for executable identification:

workspace/namespace:name
    │         │       │
    │         │       └─ Executable name (Optional but unique within verb group + namespace)
    │         └───────── Optional namespace grouping
    └─────────────────── Workspace boundary

Reference Resolution Rules:

• my-task → Current workspace, current namespace, name=“my-task”
• backend:api → Current workspace, namespace=“backend”, name=“api”
• project/deploy:prod → workspace=“project”, namespace=“deploy”, name=“prod”
• project/ → workspace=“project”, no namespace, nameless executable

Reference Format Trade-offs:

• Chosen: Slightly more verbose for simple cases
• Avoided: Naming collisions, poor tooling support, brittle file/directory coupling

Verb System

Verbs describe the action an executable performs while enabling natural language interaction. Verbs can be organized into semantic groups with aliases:

# Executable definition
verb: build
verbAliases: [compile, package, bundle]
name: my-app

# With the above, all of these commands are equivalent:
flow build my-app
flow compile my-app
flow package my-app

This system allows developers to use whichever verb feels most natural while maintaining executable uniqueness through the [verb group + name] constraint.

I’ve significantly reduced the number of default verb groups to focus on the most common actions with the most semantic clarity. See the flow documentation for the latest default list.

Context Awareness

Flow maintains context awareness to reduce typing and improve ergonomics:

Current Workspace Resolution:

• Dynamic Mode: Automatically detects workspace based on current directory
• Fixed Mode: Uses explicitly set workspace regardless of location

Namespace Scoping:

• Commands inherit current namespace setting
• Explicit namespace references override current context

Note to self: Explicit command overrides of workspace / namespace may become an emerging need with the Desktop UI and MCP server usage.

Cross-Project Composition

The reference system enables powerful cross-project workflows:

executables:
  - verb: deploy
    name: full-stack
    serial:
      execs:
        - ref: "build frontend/"     # Different workspace
        - ref: "build backend:api"   # Different namespace
        - ref: "deploy"              # Current context

Finding the Workspace

Registration is an optimization, not a prerequisite. In dynamic mode flow finds its workspace by walking up from the current directory to the nearest flow.yaml, the same way make and bazel find their root. Clone a repo and its executables work immediately.

An unregistered workspace is named after its directory, runs normally, and is never written anywhere. Not to the config, not to the shared executable cache. What you give up is the ability to flow workspace switch to it, and other workspaces cannot reference its executables by name.

Resolution runs in this order:

1. --workspace or $FLOW_WORKSPACE, which accepts a registered name or a path
2. The nearest flow.yaml at or above the working directory (dynamic mode only)
3. A registered workspace whose directory contains the working directory
4. Whatever flow workspace switch last set

A directory containing its own flow.yaml is a boundary. The closest one wins, and a parent workspace does not scan into it. Discovery also walks past vendor/, node_modules/, third_party/, external/, .git/ and .claude/, because a flow.yaml in there belongs to that copy rather than to your project. The honest caveat is that there is no stopping point above your home directory, so a flow.yaml in ~ makes your entire home directory a workspace.

Git Workspaces

A workspace can be a git remote rather than a local path. Clones are cached under ~/.cache/flow/git-workspaces/, following Go module conventions, and can be pinned to a branch or tag. flow sync --git refreshes them. This is what lets a workspace of shared team executables be consumed the same way a dependency is.

The execution engine is the core of Flow, responsible for running executables defined in YAML files.

Runner Interface

The execution system uses a runner interface pattern where each executable type implements:

type Runner interface {
	Name() string
	Exec(
		ctx context.Context,
		exec *executable.Executable,
		eng engine.Engine,
		inputEnv map[string]string,
		inputArgs []string,
	) error
	IsCompatible(executable *executable.Executable) bool
}

Current runner implementations include:

• Exec Runner: Shell command execution
• Request Runner: HTTP request handling
• Launch Runner: Application/URI launching
• Render Runner: Markdown rendering
• Serial Runner: Sequential execution of multiple executables
• Parallel Runner: Concurrent execution with resource limits

Workflows (Serial and Parallel)

The serial and parallel runners allow for composing complex workflows from simpler executables. Steps are defined with a RefConfig that supports inline commands or references to other executables:

type SerialRefConfig struct {
  Cmd string
  Ref Ref
  Args []string

  If string          // Expression to conditionally skip the step
  Retries int
  ReviewRequired bool // Prompts the user before continuing
}

Execution and result handling is managed by the internal engine.Engine interface. The current implementation includes retry logic, error handling, and result aggregation.

Execution Environment and State

Environment Inheritance Hierarchy:

Environment variables are provided to the running executable in the following order:

1. System environment variables (lowest priority)
2. Dotenv files (.env, workspace-specific)
3. Flow context variables (FLOW_WORKSPACE_PATH, FLOW_NAMESPACE, etc.)
4. Executable params (secrets, prompts, static values)
5. Executable args (command-line arguments)
6. CLI --param overrides (highest priority)

State Management

There are two ways state can be managed when composing workflows:

• Cache Store: Key-value persistence across executions with scoped lifetime. Values set outside executables persist globally; values set within executables are cleaned up on completion. Uses bbolt for cross-process storage.
• Temporary Directories: Isolated scratch space (f:tmp) with automatic cleanup and shared access across serial/parallel workflow steps.

File System Access

By default, the working directory is the directory containing the flow file that defines the executable. This can be configured using special prefixes: // (workspace root), ~/ (user home), f:tmp (temporary).

There is no automatic sandboxing. Executables inherit full user permissions. Flow assumes users understand their workflows’ scope and potential for system modification, prioritizing automation flexibility over execution isolation. Containerized execution is a planned future improvement.

See the executable guide and state management for usage details.

Performance and Caching

Flow uses eager discovery with multi-level caching to keep response times fast. Workspace scanning runs up front and is cached to disk, with in-memory caching layered on top for quick lookups. The cache is invalidated and refreshed via flow sync or the --sync flag.

Note to self: Some performance testing needed to validate sub-100ms discovery targets across large workspace trees.

For implementation details, see the DeepWiki reference.

Getting Values Into a Process

Everything reaches an executable as an environment variable. There are four sources:

Each can write to envKey or, when something needs a real file on disk, to outputFile, which is cleaned up after the run.

Arguments are separate from parameters and come from the command line, either positionally (pos: 1) or as flags (flag: name), with a type and an optional default:

flow build container -- v1.2.3 --publish=true

Resolution runs highest to lowest: a --param override, then the executable’s params, then its args, then the surrounding shell environment. Parent values propagate into children in serial and parallel workflows.

Paths get their own small vocabulary, which keeps definitions portable: // is the workspace root, ~/ is home, ./ is relative to the flowfile, $VAR expands from the environment, and f:tmp is a temp directory created once per run and cleaned up after.

Containers

A step can declare an image and run there instead of on the host:

exec:
  cmd: pytest -q
  container:
    image: python:3.13-alpine

The runtime is Docker or Podman, auto-detected unless pinned. The workspace mounts at /workspace by default, additional volumes use the same path prefixes as everything else, and the FLOW_* variables come along automatically. Secrets go in through a temporary --env-file rather than the command line, so they never appear in the container’s argv.

Conditions and State

Steps can be skipped with an if expression evaluated against os, arch, env, store, and a ctx object carrying the current workspace, namespace and flowfile paths. Conditions are the one place where a $("command") shell escape is available.

The store is a small key-value cache with two lifetimes, and the distinction matters more than it looks:

• Global, set outside a run with flow cache set, persists until cleared.
• Execution, set from inside an executable, is cleared automatically when the parent finishes. A serial workflow can pass state between its own steps without leaking it.

Two more things exist at the step level because workflows meet reality: retries: N, and reviewRequired: true, which pauses for a human before continuing.

The vault system provides secure storage, management, and retrieval of secrets across workspaces and executables. It extends the executable environment with multiple encryption backends.

Implementation: github.com/flowexec/vault

Provider Architecture

The vault system supports multiple storage backends through a common Provider interface:

type Provider interface {
  ID() string
  GetSecret(key string) (Secret, error)
  SetSecret(key string, value Secret) error
  DeleteSecret(key string) error
  ListSecrets() ([]string, error)
  HasSecret(key string) (bool, error)
  Metadata() Metadata
  Close() error
}

Current Providers

• Unencrypted Provider: Simple key-value store for development and testing
• AES Provider: Symmetric file encryption using AES-256-GCM (single key management)
• Age Provider: Asymmetric file encryption using the Age specification (supports multiple recipients)
• Keyring Provider: Uses system keyring (macOS Keychain, Linux Secret Service)
• External Provider: Integration with external CLI tools (1Password, Bitwarden) via command execution

Vault Switching

Vaults can be switched using a context-based system:

flow vault switch development
flow secret set api-key "dev-value"

flow vault switch production
flow secret set api-key "prod-value"

Secret references support both current vault context (secretRef: "api-key") and explicit vault specification (secretRef: "production/api-key").

Backends

Key storage is configurable per vault, and an existing valid key in the target variable is reused rather than regenerated, which is how one key ends up shared across several vaults.

External Vaults

This is the design I am happiest with. An external vault holds links, not secrets. Each link pairs a name you choose with a reference the provider understands. Reading the name resolves the reference and reads through. Nothing is copied into flow and nothing is ever written back, so pointing a vault at a store you already use cannot damage it.

The configuration carries a get command, an optional metadata command, and two patterns that turn out to matter a lot:

• reference_pattern describes what a reference for this provider looks like, so a typo is caught when you link it rather than weeks later when you read it.
• not_found_pattern separates “this link is broken” from “the provider is unreachable”. Without it, an expired session is indistinguishable from a deleted secret.

Because it is read-through, flow secret set fails against an external vault and flow secret remove removes the link rather than the secret.

Injection

Secrets never appear in a command line. They are resolved at run time and handed to the process as environment variables:

params:
  - secretRef: api-key
    envKey: API_KEY
  - secretRef: production/db-password   # a different vault
    envKey: DB_PASSWORD

When something genuinely needs a file, outputFile writes one and deletes it afterwards. In container runs the same values go through a temporary --env-file, for the same reason.

flow already had the pieces to do better. It knows your workspace, it holds your secrets, it captures logs, and it records every run. Exposing that over MCP turns it from a task runner into somewhere an agent can work.

The Scope Boundary

Worth stating up front, because it shapes everything else:

flow is an AI tool provider, not an AI consumer.

The core exposes deterministic capabilities: an MCP server, published JSON schemas, an llms.txt. It does not make model calls. No LLM parsing of natural-language commands, no generation inside the CLI. That would put vendor keys, per-call cost, and non-determinism in the critical path of a task runner. Anything applying a model to flow does so from outside, through the MCP surface. Mochi is exactly that: a consumer built on top.

The Ladder

The run tools are deliberately ordered, closest fit first:

The reason run_python is its own tool rather than a flag on run_command is small and practical: agents select tools by name, and a tool called “run_command” is not what gets reached for when the task is Python.

Around those sit discovery and inspection tools (list_executables, get_executable, list_workspaces, get_workspace, switch_workspace, get_info), history (get_execution_logs), and authoring (write_flowfile, which validates against the schema server-side before writing). There are MCP resources for workspaces, executables, flowfiles and logs, and prompts for generating and debugging executables.

The server is built on mcp-go, and exposes Tools, Prompts and Resources. I discovered that client support for Resources is still thin but I have them for clients that do support them.

The boundary is stated honestly in the server instructions: fall back to a raw shell for things that genuinely should not be recorded, or that flow is not suited to, like anything needing a TTY.

What Running Through flow Buys You

Compared to a generic execute tool:

• Named work first. Discovery means the agent runs your actual test executable rather than its own approximation of one.
• Workspace resolution from a directory. Pass a path and flow walks up to the nearest flow.yaml. Works in a fresh clone or a git worktree with nothing registered.
• Secrets from the vault, injected as environment, never in the argv.
• Provenance on every run. source, clientName, sessionId, workingDir.
• Lifecycle-aware history. Written as running at start and upserted on completion, so a log can be read while the run is still going.
• Approval gates in the workflow, via reviewRequired on a step, rather than depending on the client to ask.
• Byte-capped structured output, so a runaway log cannot eat the context window.

Provenance Has Opinions

Three environment variables carry it: FLOW_RUN_SOURCE, FLOW_RUN_CLIENT, FLOW_RUN_SESSION. Two decisions behind that are worth repeating.

There is no client registry. flow does not sniff for CLAUDE_CODE_SESSION_ID or any other vendor’s variables. Those are undocumented internals that get renamed, and detection built on them fails silently, so history quietly stops grouping and nobody notices. Each tool maps its own variables onto the contract instead.

And identity is exported, not passed. Environment beats a flag the assistant has to remember on every call: a model can silently omit an argument, but it cannot omit a variable it never sees. Parameters are for intent, which is the only thing the model actually knows.

The Python Interpreter

You can run python alongside the built-in POSIX shell:

executables:
  - verb: run
    name: report
    exec:
      interpreter: python
      cmd: |
        import json, sys
        print(json.dumps({"python": sys.version_info[:2]}))

A .py file needs no interpreter field at all, since the extension implies it. The same field works on serial and parallel steps, and inside containers, where the entrypoint follows the interpreter rather than being hardcoded to a shell.

Nothing is embedded. There is no bundled CPython, no Starlark, no WebAssembly. flow resolves a real interpreter on the host, preferring a project’s virtualenv over bare system Python, so an agent running Python inside a repo gets that repo’s dependencies. The search order is FLOW_PYTHON_BIN, then $VIRTUAL_ENV, then the workspace’s .venv, then python3 on the path. An override that does not resolve fails rather than quietly falling back.

Two details I liked:

Inline code runs from a temporary file, never python -c. That keeps user code, which may have interpolated secrets, out of the process table; it produces tracebacks with real line numbers; and it sidesteps shell quoting for multi-line scripts.

PYTHONUNBUFFERED is set by default, because flow pipes stdout to a log writer rather than a terminal, and CPython block-buffers to a pipe. Without it a long run emits nothing until it exits, which looks hung to anyone watching, human or otherwise.

The MCP side is the reason the rest exists. run_python gives an assistant a Python runtime with the same workspace environment and secrets, the same captured logs, and the same attributable history entry it already gets for shell. It is the difference between an agent writing a scratch file and an agent doing work you can audit afterwards.

Flow includes a templating system for generating executables and workspaces from reusable templates, built on Go’s text/template and the Expr expression language. See the documentation for usage details and examples.

Where flow Plugs In

Two integration surfaces have their own pages, because both turned out to be more than a paragraph:

• The GitHub Action runs the same executables in CI that you run locally.
• flow as an agent runtime covers the MCP server and the tools it exposes.

There is also a Docker image at ghcr.io/flowexec/flow for other CI systems, though it has not been exercised nearly as hard as the Action has.

Schemas

The flowfile, workspace, template and config formats are published as JSON Schema (see the configuration reference), which is what gives editors completion and validation, and what lets an assistant author a valid flowfile without guessing. There is an llms.txt alongside them. The Go types are generated from those same schemas, so the contract has one source.

flowexec/action is how. It publishes to the Marketplace as flow-execute, and the smallest useful thing you can write with it is:

- uses: flowexec/action@v1
  with:
    executable: 'build app'

That is the whole point of it. The executable named there is the same one you run with flow build app at your desk. Every repository in the flowexec organization uses this on itself.

What It Actually Is

A composite action, not a container or a JavaScript action. It is a handful of bash steps in a trench coat, which is the right shape for something whose job is to install a binary and run it:

1. Resolve where flow should be installed, then restore it from the runner cache.
2. Install the CLI if the cache missed.
3. Register workspaces, cloning any that are git remotes.
4. Create a vault and load secrets into it, but only if secrets were passed.
5. Run the executable.
6. Upload logs as an artifact, but only on failure, and only if asked.

Keeping it composite means each step shows up separately in the workflow log, so a failure points at the thing that failed rather than at one opaque action.

Workspaces, Including Ones That Are Not There Yet

The interesting input is workspaces. A workspace can be a local path, but it can also be a git URL, which the action clones and registers before running anything:

- uses: flowexec/action@v1
  with:
    executable: 'deploy staging'
    workspaces: |
      backend: ./backend
      frontend: https://github.com/user/frontend-repo.git
      shared:
        repo: https://github.com/myorg/shared-flows.git
        ref: v1.0.0
    clone-token: ${{ secrets.GITHUB_TOKEN }}

This is the CI expression of flow’s cross-project composition. A workflow can pull in a shared workspace of common executables, pin it to a tag, and reference its executables the same way it would locally. Clone depth defaults to 1, because CI almost never needs the history.

Secrets and the Ephemeral Vault

Secrets were the part that needed real thought. flow reads secrets from a vault, and a CI runner has no vault, so the action makes one and throws it away.

When secrets are passed, it creates a vault named github-actions keyed to an environment variable, loads each secret in, and switches to it. The generated key is immediately masked in the log with ::add-mask:: and exposed as an output.

That output exists for one reason, and it is the nicest bit of the design: a vault can outlive a job. Emit the key from one job, pass it to the next, and the second job decrypts the same vault rather than re-loading every secret from GitHub:

jobs:
  setup:
    outputs:
      vault-key: ${{ steps.init.outputs.vault-key }}
    steps:
      - uses: flowexec/action@v1
        id: init
        with:
          executable: 'validate'
          secrets: |
            SHARED_SECRET=${{ secrets.SHARED_SECRET }}

  deploy:
    needs: setup
    steps:
      - uses: flowexec/action@v1
        with:
          executable: 'deploy production'
          vault-key: ${{ needs.setup.outputs.vault-key }}

The vault step is skipped entirely when there are no secrets and no key, so a plain build job does not pay for machinery it is not using.

Failing Usefully

A CI action that only tells you “exit code 1” is not much better than running the command yourself. This one parses flow’s structured JSON error output and surfaces the code:

Which means a workflow can branch on why something failed rather than just that it did:

- name: Handle failure
  if: steps.migrate.outputs.exit-code != '0'
  run: |
    if [ "${{ steps.migrate.outputs.error-code }}" = "TIMEOUT" ]; then
      echo "Consider increasing the timeout"
    fi

Captured output is truncated at 65,000 bytes, because that is GitHub’s limit on a step output, and the full log is available as an artifact instead.

The Unglamorous Parts

Most of the commit history is Windows and shell edge cases, which is what this kind of tool is actually made of:

• Windows runners need $HOME/bin pushed onto GITHUB_PATH, and workspace paths in native form rather than the POSIX form the rest of the script assumes.
• TERM=dumb on Windows, because flow’s TUI would otherwise try to render into something that is not a terminal and hang the job.
• The vault key is extracted from structured JSON output, with a fallback to scraping the plain text message for older CLI versions.
• The binary is cached between runs, keyed on the resolved version, so a workflow that runs the action several times installs flow once.

None of that is interesting to write about, and all of it is the difference between an action that works on your machine and one that works on someone else’s.

Resources

• flowexec/action
• flow-execute on the Marketplace
• flow’s own CI workflow, which uses it