The loop takes five minutes.

Install it

You need Node 20 or newer. Open a terminal — on macOS press ⌘-Space, type Terminal, press Return; on Windows press the Start key, type PowerShell, press Enter; on Linux press Ctrl-Alt-T — and paste this, then press Return:

node --version

You should see a version number:

v22.14.0

If it says command not found instead, install Node from nodejs.org — the big button marked LTS — then close Terminal, open it again, and try that line once more.

Now install Ferrow. One line, no build step, nothing to configure:

npm install -g @ferrow/ferrow

It takes a few seconds and prints one line when it is done:

added 1 package in 4s

Check that it landed. Type the name on its own:

ferrow

ferrow — a knowledge vault that acts.

Model provider:  none connected yet
Vault:           not created yet

Start here — connect a model:
  A hosted one:  ferrow connect openai
  A local one:   ferrow detect

This machine is yours to use free — vault, notes, search, log, local models.
A plan adds what runs on Ferrow's servers: Managed models, hosted schedules, sync.
Bought Ferrow on the website?  ferrow activate <your key>

Everything else:  ferrow help

That is the whole install. Every command from here on begins with the word ferrow.

ferrow activate <your key>

Activated on this machine — key stored in your keychain.

Plan:     monthly — $20.00/month
Edition:  Private — your own API keys
Status:   trialing — the trial ends , then it renews.

Cancel any time:  ferrow unsubscribe

ferrow activate <your account key>

Give Ferrow a brain

Ferrow does not include an AI model. You point it at one. Ask it what it knows about:

ferrow providers

ID           PROVIDER                                   KEY          GET A KEY
openai       OpenAI                                     —            https://platform.openai.com/api-keys
anthropic    Anthropic (Claude)                         —            https://console.anthropic.com/settings/keys
google       Google (Gemini)                            —            https://aistudio.google.com/app/apikey
openrouter   OpenRouter (400+ models, one key)          —            https://openrouter.ai/keys
xai          xAI (Grok)                                 —            https://console.x.ai
custom       Custom / local OpenAI-compatible endpoint  —            (n/a)

Connect one:  ferrow connect <id>

The dash in the KEY column means "no key stored for this one yet". Open one of those, sign in, create an API key, then:

ferrow connect openai

Ferrow asks for the key, tests it against the provider, and stores it in your keychain. It never prints the key back to you.

Or run everything on your own computer

If you already have Ollama, LM Studio, Jan, llama.cpp, vLLM or GPT4All running, skip the key entirely:

ferrow detect

If nothing is running you get this, which is not an error — it is the list of places it looked:

No local model runtimes detected.
Looked for: ollama (11434), lmstudio (1234), jan (1337), gpt4all (4891), llamacpp (8080), vllm (8000).
Start one of those, or use a hosted model — `ferrow connect openai` — or `ferrow connect custom` for any other base URL.

Either way, check what you can now reach with ferrow models.

The line you will type most

A model is connected, so you can ask it something. That is ferrow chat, and it is the command you will use every day:

ferrow chat openai gpt-4o-mini "what should I read up on before Thursday?"

Your own key, your own model, one message and the reply. On a Ferrow plan the first two words come off — ferrow chat "what should I read up on before Thursday?" — and Ferrow picks the model. Everything below works the same either way.

Make the vault

ferrow vault init

Initialized vault at /Users/you/FerrowVault
  + memory/profile.md
  + memory/preferences.md
  + memory/index.md

Write a note:   ferrow note inbox/today.md "the thing I just learned"
Teach a fact:   ferrow remember likes-tea "I drink tea, not coffee"

That folder — FerrowVault in your home directory — is now yours. Open it in Finder if you like; it is plain text files. Nothing else on your computer changed. Running vault init a second time is safe: it leaves existing files alone and says so.

Write something down, then find it again

ferrow note inbox/today.md "Ferrow keeps my notes as files I can read without it."

Wrote inbox/today.md  (chg_mspk2ve3_86f5cb)

That code in brackets is a change id — it becomes useful in a moment. Read the note back by leaving the text off: ferrow note inbox/today.md.

Now find it again. files here is just the word to look for, so put your own word in its place. Every block on this page is the command and nothing else, on purpose: a trailing # note is not ignored by every terminal — the zsh that ships as the default on macOS answers a pasted one with ferrow: there is no "#" command — so we do not put them in lines you are meant to paste.

ferrow search files

inbox/today.md:1                       Ferrow keeps my notes as files I can read without it.

1 match in 3 notes.

It shows the line it matched, not just the filename, so you can see why it thinks it is a hit. The three notes are your one note and the two memory files vault init wrote; Ferrow's own memory/index.md is machine-generated and is kept out of the search, so your first search returns your own writing and nothing else. When there is no match it says so plainly rather than showing you nothing.

Teach it a fact about you

Notes are things you wrote. Memory is things that stay true — and every agent reads memory before it starts work.

ferrow remember drinks-tea "I drink tea, not coffee"
ferrow recall tea

Remembered "drinks-tea" → memory/facts/drinks-tea.md
Index memory/index.md updated.
3.00    drinks-tea               fact        I drink tea, not coffee

The first two lines are the storing, the last one is the recall. The number is how strongly it matched. To take a fact back:

ferrow forget drinks-tea

Forgot "drinks-tea" — memory/facts/drinks-tea.md moved to .trash (recoverable, chg_mspk2wqz_3fb525).
Index memory/index.md updated.

Recoverable, and logged — which is the next step.

See what changed, and undo it

This is the part that makes agents safe to use. Every write, by you or by an agent, is recorded.

ferrow log

ID                   WHEN                 KIND    PATH                           AGENT        REASON
chg_mspk2wrq_98d67d  2026-08-12 03:54:58  write   memory/index.md                cli:user     manual forget (index regenerated)
chg_mspk2wqz_3fb525  2026-08-12 03:54:57  remove  memory/facts/drinks-tea.md     cli:user     manual forget
chg_mspk2w39_580af1  2026-08-12 03:54:57  write   memory/index.md                cli:user     manual memory (index regenerated)
chg_mspk2w1r_8b2dc9  2026-08-12 03:54:57  write   memory/facts/drinks-tea.md     cli:user     manual memory
chg_mspk2ve3_86f5cb  2026-08-12 03:54:56  write   inbox/today.md                 cli:user     manual note
chg_mspk2ugg_2c141d  2026-08-12 03:54:55  write   memory/index.md                cli          vault init (index regenerated)
chg_mspk2uan_e10e15  2026-08-12 03:54:54  write   memory/preferences.md          cli          vault init
chg_mspk2uac_c79170  2026-08-12 03:54:54  write   memory/profile.md              cli          vault init

Undo any of them:  ferrow log revert <id>

Everything is there, including the three files vault init wrote for you and the index Ferrow rebuilds each time memory changes. Copy any id from the first column and undo that one change — here, the forgetting:

ferrow log revert chg_mspk2wqz_3fb525

Reverted chg_mspk2wqz_3fb525 — restored memory/facts/drinks-tea.md (106 bytes).
Logged as chg_mspk2ybh_95c042. Reverting that undoes this.

The undo is itself recorded, so you can always see what happened — including the undoing.

Put an agent to work, then see it in a window

ferrow council "should I take the contract or keep freelancing?"

You get a Strategist, a Skeptic, a Builder, a User-Advocate and a Realist, and their disagreements — which is the point. It reads your memory first, so it knows who is asking.

If you have connected one at step 2, that is the model it uses — there is nothing else to pass. If you have not connected one yet, Ferrow tells you exactly what to do instead of failing:

No provider or model set — nothing is connected on this machine yet.
Connect one you have a key for:  ferrow connect <provider>     (the list: ferrow providers)
Or use one running here:         ferrow detect
Once either is done this command needs no flags at all.

Both of those are real work you can do right now, and neither needs a flag afterwards: once something is connected, council, run and workflow use it, with the model that connection was verified against.

If you would rather be explicit — a second provider, a bigger model — the --provider and --model flags work the same on all three systems, and FERROW_PROVIDER/FERROW_MODEL hold for a whole terminal session: export NAME=value on macOS and Linux, $env:NAME="value" in PowerShell on Windows.

ferrow ui

  Ferrow is running at  http://127.0.0.1:60541/

  Vault    /Users/you/FerrowVault

  Paste that address into any browser on this computer as it is — there is nothing
  else to copy. Only this machine can reach it (127.0.0.1). The key the page needs is
  minted fresh at boot, handed to the page itself, and dies when you stop the app; it
  stops websites you visit from reading your vault through the browser. It is not a
  lock against other programs on this computer.

  Stop it with Ctrl-C.

The number after the colon is different every time — Ferrow takes whichever port is free when it starts, so read the address off your own screen rather than copying the one above. Open it in your browser. 127.0.0.1 means your own machine and only your own machine: that address is not reachable from the internet or from anyone else's computer. Press Ctrl-C when you are done.

The whole command surface

ferrow help prints all of it, grouped. The overview covers the promises — the contract a skill runs under, the undo, the kill switch, the spend cap. This is the rest of the surface: the ordinary good tooling, which is worth a manual rather than a sales page.

In the vault

• Notes. Markdown with wikilinks and backlinks. ferrow search ranks every note and shows you the line it matched on, not just the filename — which is the difference between finding a file and finding the thing you were looking for.
• Bringing your history in. ferrow import conversations.json --dry-run reads a ChatGPT or Claude export, or a .jsonl file — one message per line, which is what some other tools export — into the vault; --dry-run shows what it would write and writes nothing. ferrow vault import obsidian brings an Obsidian vault in with its wikilinks intact. All of the parsing happens on your machine.
• More than one vault. ferrow project new work makes a second one, kept apart from the first — separate notes, memory, skills and history. project list, project switch, project remove. Your personal memory is read by all of them.

Putting agents to work

• The skills you have. ferrow skills lists them, valid and broken, and names any outside reach a skill was granted — an MCP server, a real browser — under the skill it belongs to. ferrow run <skill> <task> runs one inside its contract. A new vault has none, and that screen prints the path to the three Ferrow ships with — daily-note, link-check, weekly-review — so ferrow skill install is a copy away.
• More than one job at a time. ferrow dispatch queues prompts against a project and fans out across several; ferrow tickets is that queue, with state, age and project against each one.
• Multi-step work. ferrow workflow run <spec.json> runs an auto-routed graph of steps. If a step needs your decision it stops there rather than guessing, and ferrow workflow resume picks it back up. The spec is a JSON file you write; there is a worked example below.
• On a cadence. ferrow schedule add|list|remove|run|tick runs skills while you are away. The timer is ferrow hub start: while a hub is up it fires every due schedule once a minute, and with no hub running nothing fires by itself. On a Managed plan, --hosted runs that schedule on Ferrow so it keeps going with your computer off — model only, no vault access.
• A decision you are stuck on. ferrow council puts it to a Strategist, a Skeptic, a Builder, a User-Advocate and a Realist, and gives you their disagreement back rather than an average of it.

What a workflow spec looks like

A spec is a plain JSON file: a list of steps, each with an id, and each saying what it waits for. Steps that wait for nothing run at the same time; steps that name another step wait for it. This one reads the week, then writes it up:

{
  "steps": [
    { "id": "skim",
      "kind": "agent",
      "prompt": "List, one line each, everything in my notes from the week just ended.",
      "need": { "difficulty": "trivial" } },

    { "id": "review",
      "kind": "agent",
      "dependsOn": ["skim"],
      "prompt": "From that list, write what moved, what stalled, and at most five things next.",
      "need": { "difficulty": "hard" } }
  ],
  "limits": { "maxConcurrency": 2, "maxSteps": 16 }
}

Save it as week.json and run ferrow workflow run week.json. Ferrow prints a line as each step starts and finishes, then a tick or a cross against every step id at the end. The fields:

• steps — required, and at least one. Every step needs a id that is unique in the file.
• kind — agent is one model call. map repeats a step over a list, either items written into the spec or itemsFrom naming the step whose output to fan out over. reduce waits for everything it depends on and folds it into one answer.
• prompt — what the step asks. Required.
• dependsOn — the ids that must finish first. Leave it out and the step starts immediately. A step that names a step that does not exist, or a loop of steps waiting on each other, is refused before anything runs.
• need — what the step actually needs, which is how Ferrow picks the model for it: difficulty is trivial, bounded or hard, and a hard step deliberately gets a rung more capability. tools, vision, jsonMode and minContext are hard requirements — a model that cannot do them is not considered, however cheap it is.
• model and provider — pin a step to one model. Both or neither; a model with no provider is refused, because Ferrow cannot route on half a name. Leave them out and it chooses per step.
• limits — maxConcurrency (4 by default) is how many calls may be in flight at once, maxSteps (1000) is the total work, and maxTotalTokens caps the estimate. Each is a refusal, checked before the step that would break it runs, so a runaway spec stops instead of spending.
• approval on a step — that step parks rather than running, and ferrow approve then ferrow workflow resume pick it up. verify asks for the step's work to be graded before it counts as done. Both are optional and a spec without them behaves exactly as the one above does.

One step failing does not stop the rest: it is recorded as failed and the steps after it run with whatever did succeed. If you forget the shape, ferrow workflow run with no file prints it back in one line.

Reaching past the folder

• Ferrow inside the agent you already use. ferrow serve-mcp runs Ferrow as an MCP server — MCP is the open standard agents use to reach outside tools — so something else reads and searches this vault without you switching to anything. Reading is on; writes and skills are off until you say otherwise.
• Your other devices. ferrow hub start|pair|status|stop makes this machine the one that thinks and reaches it from a browser anywhere. The relay carries sealed blobs it cannot read; the vault and the model stay here.
• From a chat app. ferrow channel add and ferrow channel start answer from Telegram, polled by your machine — nothing listens in. A chat can ask, take a note, search and check status. It can never run a skill.
• Out loud. ferrow voice status|listen|speak — speech in, speech out.

Checking on it, and paying for it

• A second opinion. ferrow doctor reads every part of your setup and says what is working. It reports and never repairs, and it tells "not set up yet" apart from "broken" — which is the distinction every other diagnostic collapses.
• Billing. ferrow subscribe · ferrow billing · ferrow unsubscribe · ferrow spendcap — see pricing.

If you get stuck

• command not found: ferrow — the install worked but your terminal has not noticed it yet. Close the Terminal window, open a new one, and try again. If it still says that, npm put the command somewhere your terminal does not look, and the fix is the three lines below.
• command not found: node or : npm — Node is not installed. nodejs.org, the LTS button, then reopen Terminal.
• node --version prints a number below v20 — that Node is too old; Ferrow needs 20 or newer. Install the current LTS from nodejs.org — it replaces the old one, there is nothing to uninstall first — then close the terminal, open a new one, and run node --version again. It has to read v20 or higher before the install line will work.
• npm install -g answers permission denied, or EACCES — npm is trying to write into a folder your account does not own. The fix is two lines and it is below; the one thing not to do is re-run it with sudo.
• A command printed a wall of red text — send the whole thing to support, not a summary of it.
• You want to start over — delete the FerrowVault folder in your home directory. Nothing else on your machine is touched. Your stored API key is not in that folder: on macOS it is in the keychain, in the items Keychain Access lists when you search it for ferrow; on Windows and Linux it is in a file called keys.json, inside a hidden .ferrow folder in that same home directory, readable by your account and no other.

Adding npm's folder to your PATH

PATH is the list of folders your terminal searches when you type a command name. If npm's folder is not on that list, Ferrow is installed and the terminal still cannot find it. Each line below asks npm where it put things and adds that folder to the list for good. Paste the one for your machine, press Return — it prints nothing, which is success — then close the terminal and open a new window.

macOS, in the Terminal app (it uses zsh):

echo "export PATH=\"$(npm prefix -g)/bin:\$PATH\"" >> ~/.zshrc

Linux, if your shell is bash:

echo "export PATH=\"$(npm prefix -g)/bin:\$PATH\"" >> ~/.bashrc

Windows, in PowerShell — one line, and it is long:

[Environment]::SetEnvironmentVariable('Path', [Environment]::GetEnvironmentVariable('Path','User') + ';' + (npm prefix -g), 'User')

Open a new terminal window — the old one keeps the old list — and type ferrow again. You should get the screen from step 1. If you still do not, the support page answers by email, and the useful thing to send is what npm prefix -g printed.

If the install itself was refused

On macOS and Linux, npm install -g can answer permission denied or EACCES: npm is trying to write into a folder your account does not own. Do not re-run it with sudo — that leaves root-owned files in your home directory and the next install fails from the other side. Give npm a folder you already own instead:

mkdir -p ~/.npm-global
npm config set prefix ~/.npm-global

Then run npm install -g @ferrow/ferrow again, and use the PATH line above — npm prefix -g now prints the new folder, so the same line adds the right one.

If something on your screen does not match what is printed on this page, that is worth reporting.