Ferrow in 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.

If you bought Ferrow on the website

Paying and switching a machine on are two steps on purpose — nothing about your purchase reaches this computer until you tell it to. One line does it:

ferrow activate <your key>

Your key looks like ferrow_ followed by a long string, and it is on the page you landed on after paying. The same command also accepts the cs_ checkout reference or that page's whole web address, so whatever you copied is the right thing to paste. It prints your plan when it works:

Activated on this machine — key stored in your keychain.

Plan:     monthly — $20.00/month
Edition:  Private — your own API keys
Status:   trialing

Cancel any time:  ferrow unsubscribe

Status: trialing is what the 3-day trial prints; once the trial converts it reads active. Run the line again on a second machine to switch that one on too. Nothing below this point needs a subscription: the vault, agents, skills and the Council all work on your own keys.

If you did not buy anything

You do not have to. An email and a password, and nothing else, makes a free account, and everything on this page keeps working on your own machine for as long as you want it: the vault, memory, search, the log and undo, agents, skills and projects, on your own API key or a model running on your own computer. What a subscription adds is Ferrow's side of it — the relay so your phone can reach your hub, sync between machines, the hosted app, and models billed through Ferrow. Pricing says which is which.

None of this needs an account — everything above already works. If you want one anyway (it is what lets a purchase or another machine find you later), create it at app.ferrow.ai — the plan step has a “Free, on this machine. No card.” door — and the page you land on shows your account key with the one line that uses it:

ferrow activate <your account key>

Run it here and ferrow billing answers Plan: free. The same key stays in Settings, under Account, if you ever need it again.

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 run `ferrow connect custom` to point Ferrow at any 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.

ferrow search files            # "files" is the word to look for

inbox/today.md:1                       Ferrow keeps my notes as files I can read without it.
memory/index.md:3                      <!-- GENERATED by Ferrow from the files in memory/. Do not edit: it is rewritten on every

2 match(es) in 4 note(s).

It shows the line it matched, not just the filename, so you can see why it thinks it is a hit. The second hit is Ferrow's own index of your memory, which is a file like any other — nothing is hidden from you. 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 not connected a model yet, Ferrow tells you exactly what to do instead of failing:

No provider or model set.
Pass them:      --provider openai --model gpt-4o-mini
Or set them:    export FERROW_PROVIDER=openai FERROW_MODEL=gpt-4o-mini
See what you can reach:  ferrow models

ferrow ui

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

  Vault    /Users/you/FerrowVault

  Only this machine can reach it (127.0.0.1). Its key is minted fresh at boot 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 parts not covered above:

• ferrow import conversations.json --dry-run — bring in your ChatGPT or Claude history. --dry-run shows what it would write and writes nothing. The parsing happens on your machine.
• ferrow project new work — a second vault, kept apart from the first. project list, project switch, project remove.
• ferrow skills — the skills in your vault and what each one is allowed to touch. 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.
• ferrow schedule add|list|remove|run|tick — run skills on a cadence while you are away.
• ferrow workflow run spec.json — a multi-step, auto-routed workflow.
• ferrow voice status|listen|speak — speech in, speech out.
• ferrow hub start|pair|status|stop — make this machine the one that thinks, and reach it from a browser anywhere. The relay carries sealed blobs it cannot read; the vault and the model stay here.
• 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: run npm prefix -g, which prints npm's folder — the command lives in the bin folder inside it — and add that bin folder to your PATH.
• command not found: node or : npm — Node is not installed. nodejs.org, the LTS button, then reopen Terminal.
• 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 lives in your keychain under ferrow-*.

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