Ferrow Overview Pricing Docs
Docs

Ferrow in five minutes.

This page assumes you have never used a terminal on purpose. Every command is one line you can copy, and every screen Ferrow prints back is shown here, so you can tell whether it worked.

Before you start

You need Node 20 or newer. To check, open the Terminal app (on macOS: press ⌘-Space, type Terminal, press Return) and paste:

node --version

You should see something like v22.14.0. If it says command not found, install Node from nodejs.org — the button marked LTS — then close and reopen Terminal and try again.

Everything below starts with npx ferrow. npx downloads Ferrow the first time and runs it, so the first command takes a few seconds longer than the rest.

Before launch

The npm package is not published yet, so npx ferrow will not resolve until it is. Until then, clone the repository and run node bin/ferrow.mjs in place of npx ferrow — every command below is otherwise identical.

Step 1

Give Ferrow a brain

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

npx ferrow providers
ID           PROVIDER                                   KEY   GET A KEY
openai       OpenAI                                     —     platform.openai.com/api-keys
anthropic    Anthropic (Claude)                         —     console.anthropic.com
google       Google (Gemini)                            —     aistudio.google.com
openrouter   OpenRouter (400+ models, one key)          —     openrouter.ai/keys
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:

npx 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:

npx 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).

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

Step 2

Make the vault

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

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.

Steps 3–4

Write something down, then find it again

npx ferrow note inbox/today.md "Ferrow keeps my notes as files I can read without it."
Wrote inbox/today.md  (chg_mslp2mfy_448dca)

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

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

1 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. When there is no match it says so plainly rather than showing you nothing.

Step 5

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.

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

The number is how strongly it matched. To take a fact back: npx ferrow forget drinks-tea — which trashes it recoverably, and logs it.

Step 6

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.

npx ferrow log
ID                   WHEN                 KIND    PATH               AGENT
chg_mslp2v8w_975365  2026-08-09 11:03:49  write   memory/index.md    cli:user
chg_mslp2v8c_148900  2026-08-09 11:03:49  remove  memory/facts/…     cli:user
chg_mslp2mfy_448dca  2026-08-09 11:03:38  write   inbox/today.md     cli:user

Undo any of them:  ferrow log revert <id>

Copy any id from the first column and undo that one change:

npx ferrow log revert chg_mslp2v8c_148900

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

Steps 7–8

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

npx 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
npx ferrow ui
Ferrow is running at  http://127.0.0.1:7777/

Only this machine can reach it (127.0.0.1), and only this browser tab
is let in: a one-time key is handed to the page when it loads and dies
when you stop the app.

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 rest

The whole command surface

npx 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.
  • 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: npx — Node is not installed. nodejs.org, the LTS button.
  • A command printed a wall of red text — copy the whole thing into an issue.
  • 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.