# browser-use/workflow-use: record a browser task once, replay it with variables

> Workflow Use records browser interactions into a JSON workflow that replays deterministically and falls back to Browser Use when a step breaks. It is early software, and the README says so.

**browser-use/workflow-use** — ⚙️ Create and run workflows (RPA 2.0)

- Repository: https://github.com/browser-use/workflow-use
- Website: https://browser-use.com
- Stars: 4,198 · Forks: 355
- Language: Python
- License: AGPL-3.0
- Published: 2026-09-23 · Updated: 2026-09-23 · Language: en
- Canonical page: https://hysenlabs.com/projects/browser-use-workflow-use

## The problem: browser agents that re-reason on every run

A browser agent driven by a language model decides what to click each time it runs. That is flexible, and it is also the reason the same task can take a different path on Tuesday than it did on Monday. Workflow Use starts from the opposite end. The README describes it as "the easiest way to create and execute deterministic workflows with variables which fallback to Browser Use if a step fails," and the tagline is "Deterministic, Self Healing Workflows (RPA 2.0)". The intended audience is anyone who already has a browser task they repeat: filling a form, pulling a number off a page, walking a known sequence of screens. The README says the project "was born out of customer demand to make Browser Use more reliable and deterministic," which places it as a companion to browser-use rather than a replacement. The pitch is that you show the recorder the workflow once instead of writing a long prompt, and the recorded artifact is what runs afterwards.

## How recording turns into a replayable workflow

The pipeline the README lays out has five stages. You describe a task in natural language, browser-use completes it once, the execution history is turned into a semantic workflow with parameters, the workflow is saved to a database with metadata, and it is then reused with different inputs "no AI needed". The recorder path is the manual equivalent: you perform the actions yourself and the tool generates the workflow file. Storage is plain files rather than a server. Workflows live under `workflows/storage/`, with `metadata.json` acting as a searchable index and individual workflows written to `workflows/<id>.workflow.json`. That layout matters because it means a workflow is a reviewable artifact you can diff, commit or hand to a colleague, not an opaque session. The self-healing half is the fallback: when a step fails during replay, control passes back to Browser Use, which is where the non-determinism re-enters. The README also documents a no-AI execution path, `run_with_no_ai()`, described as using "semantic mapping" rather than LLM calls. That is the mode that makes the determinism claim concrete, and it is the one worth testing first on your own pages.

## Installing workflow-use and running a first workflow

The README splits setup into two parts: building the browser extension, then preparing the workflow environment. The extension is a Node project inside `extension/`, and the workflow runtime is a Python project inside `workflows/` that uses `uv` for dependency management and Playwright for the browser.

```bash
git clone https://github.com/browser-use/workflow-use
cd extension && npm install && npm run build
```

After the extension build, move into the workflows directory and sync the environment. The README then activates the virtualenv, installs Chromium for Playwright and copies the example environment file, which is where your `OPENAI_API_KEY` goes.

```bash
cd .. && cd workflows
uv sync
source .venv/bin/activate # for mac / linux
playwright install chromium
cp .env.example .env # add your OPENAI_API_KEY to the .env file
```

With the environment ready, the fastest way to see a workflow execute is to run one of the checked-in examples. The `run-as-tool` command takes a workflow file and a prompt describing the current inputs.

```bash
python cli.py run-as-tool examples/example.workflow.json --prompt "fill the form with example data"
python cli.py run-workflow examples/example.workflow.json
```

The first command runs the workflow as a tool driven by a prompt; the second runs it with predefined variables. To capture your own instead of using the example, `python cli.py create-workflow` starts the recorder. From Python, loading and running a file is short:

```python
from workflow_use import Workflow

workflow = Workflow.load_from_file("example.workflow.json")
result = asyncio.run(workflow.run_as_tool("I want to search for 'workflow use'"))
```

The README documents a GUI as well. `python cli.py launch-gui` starts the FastAPI backend and the frontend dev server together and opens http://localhost:5173, capturing logs to `./tmp/logs`; the two servers can also be started separately with `uvicorn backend.api:app --reload` and `npm run dev` from `ui/`. The GUI visualizes workflows as graphs, executes them with custom parameters and shows execution logs.

## Generation mode and where the AI still runs

Generation mode is the part that does use a model, and the README is explicit that it does so once. You describe the task, browser-use runs it, and the execution history is converted into a semantic workflow stored in a database. The CLI exposes this directly, and the model for each stage can be set independently:

```bash
python cli.py generate-workflow "Find GitHub stars for browser-use repo"
python cli.py generate-workflow "Your task" \
  --agent-model "gpt-4.1-mini" \
  --extraction-model "gpt-4.1-mini" \
  --workflow-model "gpt-4o"
```

Three separate model flags is a design decision worth noticing: the agent that performs the task, the model that extracts structure from the execution, and the model that writes the workflow are not assumed to be the same. `--use-cloud` routes execution through Browser-Use Cloud, `--output-file` writes the workflow somewhere other than the default, and `--no-save-to-storage` skips the database. The same flow is available programmatically through `HealingService.generate_workflow_from_prompt` and `WorkflowStorageService.save_workflow`. The cloud path is documented for replay too: `Workflow.load_from_file("workflow.json", llm, use_cloud=True)` combined with `await workflow.run_with_no_ai()`. The README notes that `BROWSER_USE_API_KEY` must be set for that, and mentions new signups receiving credits via OAuth or email. Treat that credit detail as a marketing note rather than a cost model; the README does not publish pricing.

## The early-development warning is not boilerplate

The README states plainly that the project is "in very early development so we don't recommend using this in production," that "lots of things will change" and that there is no release schedule. That is an unusual amount of candor, and it should be read literally. The release history supports the caution: v0.2.9, v0.2.10 and v0.2.11 all landed within a two-week window in November 2025, which is the cadence of a project still finding its shape rather than one with a stable interface. Nothing in the README describes a migration path between workflow file versions, so a workflow recorded today may need re-recording after an upgrade. The fallback mechanism is the other limitation to weigh. Self-healing means that when a step fails, an AI takes over and improvises. That keeps the task moving, and it also means a run can silently diverge from the deterministic path without anyone noticing, which is precisely the property RPA users usually want to avoid. There is no documented alerting or audit trail for when the fallback fires. Finally, the tool is browser-only. Anything outside a browser tab is out of scope.

## How this differs from Playwright or Selenium

The obvious alternative is a hand-written Playwright or Selenium script, and the difference is where the brittleness lives. A Playwright script encodes selectors and waits that a developer chose deliberately; when the page changes, the script fails loudly at a known line. Workflow Use encodes the same kind of sequence but derives it from a recording, then adds a model-driven fallback for the failure case. That trades a loud failure for a quiet recovery, which is better if you care about the task completing and worse if you care about knowing exactly what happened. The other axis is authoring. A Playwright script needs someone who writes code; the recorder path needs someone who can perform the task in a browser, and generation mode needs only a sentence. The cost shows up in reviewability: a Python test file is diffable in a way that a recorded interaction history is not, though the `workflows/<id>.workflow.json` files are at least plain JSON. If your pages are stable and your team writes code, Playwright remains the more predictable choice. If the task is repetitive, the pages shift, and the person who knows the task is not a developer, the recorder model is the reason to look here.

## Licence and the cost of keeping workflows alive

The repository is licensed AGPL-3.0. That is a copyleft licence with a network clause: if you modify the software and let users interact with it over a network, the AGPL's source-disclosure obligations can reach that deployment. How far those obligations extend into a workflow file you recorded, or into a service you build around the CLI, is a question for a lawyer, not for this article. What can be said from the repository is that the licence is AGPL-3.0 and that the code is Python. On maintenance cost, one concrete statement is supportable: the last push to the default branch was on 2026-09-18, and the most recent tagged release listed is v0.2.11 from 2025-11-19. The gap between a September push and a November release tag is worth understanding before you plan upgrades, because the README offers no release schedule and no compatibility promise for the workflow JSON format. Budget for re-recording workflows after upgrades rather than for a migration script, since none is documented.

## Conclusion

Adopt Workflow Use if you have a small set of repetitive browser tasks on stable pages and you want the AI call to happen once at recording time rather than on every run; the recorder, the JSON workflow format and the run_with_no_ai path are the parts worth evaluating. Do not adopt it for production automation yet, since the README states the project is in very early development, has no release schedule and is not recommended for production. Before committing, verify that your target pages survive the semantic mapping by running one recorded workflow with run_with_no_ai and no LLM configured, and check the AGPL-3.0 obligations against how you intend to distribute anything built on top of it.

## FAQ

### What is workflow-use used for?

It records browser interactions into a deterministic workflow with variables, then replays that workflow, falling back to Browser Use when a step fails. The README frames it as a way to make Browser Use more reliable and deterministic, and it can also generate a workflow from a natural language task description.

### What is an example of a workflow-use task?

The README's own example is generating a workflow with `python cli.py generate-workflow "Find GitHub stars for browser-use repo"`, which runs browser-use once and stores a reusable semantic workflow. The repository also ships `examples/example.workflow.json`, used in the `run-as-tool` and `run-workflow` commands.

### Does workflow-use need an AI model on every run?

No. The README documents `run_with_no_ai()`, described as using semantic mapping with no LLM calls, and the generation pipeline is described as executing browser-use once and then reusing the stored workflow with different inputs. The fallback to Browser Use is what brings a model back in, and only when a step fails.

### Where does workflow-use store the workflows it creates?

Under `workflows/storage/`, according to the README, with a `metadata.json` index of all workflows and individual files at `workflows/<id>.workflow.json`. The `generate-workflow` command accepts `--no-save-to-storage` if you do not want the database entry, and `--output-file` to write elsewhere.

### Is workflow-use ready for production?

The README states the project is in very early development, that the authors do not recommend using it in production, that lots of things will change and that there is no release schedule. The most recent tagged release listed is v0.2.11 from 2025-11-19.

## Sources

- [browser-use/workflow-use on GitHub](https://github.com/browser-use/workflow-use)
- [License: AGPL-3.0](https://github.com/browser-use/workflow-use/blob/main/LICENSE)
- [Project website](https://browser-use.com)
- [README](https://github.com/browser-use/workflow-use/blob/main/README.md)
- [Releases](https://github.com/browser-use/workflow-use/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/browser-use-workflow-use