Homestead

An offline library of practical knowledge — first aid, water, food preservation, power, repair, livestock — that stays searchable when the internet does not.

Everything runs locally: the documents sit on your disk, the embedding model runs on your machine, and no query ever leaves it. It ships with an MCP server, so Claude or any other MCP-speaking assistant can search the library and file new documents into it.

$ homestead search "how do I treat a deep cut"

Wilderness First Aid Curriculum and Doctrine Guidelines  [first-aid]
    Control bleeding with direct pressure. Apply a gloved hand and firm,
    steady pressure directly over the wound for at least ten minutes...

Install

pip install 'homestead-library[all]'   # the machine that hosts the library
homestead install                 # choose your shelves, pull the documents in

homestead install asks what you want on your shelves, downloads it from the original publishers, and builds the search index:

What would you like on your shelves?
  1) Essentials  --  9 documents, ~66 MB
     Keeping people alive and fed when the power is out: first aid, water,
     food preservation, emergency preparedness.
  2) Growing & keeping food  --  8 documents, ~90 MB
  3) Building & fixing  --  5 documents, ~75 MB
  4) Everything  --  22 documents, ~200 MB
  5) Choose shelf by shelf

Then start it:

homestead serve                   # http://127.0.0.1:8021

Where the documents come from

This project ships a catalog, not a corpus. Nothing is redistributed here. Every entry in shelves.toml points at the publisher's own copy — mostly US federal agencies (FEMA, CDC, NOAA, USDA, the armed services), university extension services, and open-licence publishers like Hesperian and the FAO. The catalog records the licence for each one.

That keeps the repo small, keeps sources current, and keeps the licensing honest. It also means links rot: if a download fails, the installer says so, and a catalog fix is a welcome pull request.

Related MCP server: diamond

Using it from an AI assistant

The MCP server is dependency-free and starts instantly, so it can live on a different machine from the library if you like.

Claude Code

claude mcp add homestead -- homestead-mcp

Hermes

hermes mcp add homestead --command "$(command -v homestead-mcp)"

Claude Desktop — add to claude_desktop_config.json:

{
  "mcpServers": {
    "homestead": {
      "command": "homestead-mcp",
      "env": { "HOMESTEAD_URL": "http://127.0.0.1:8021" }
    }
  }
}

Query tools — talk to a running library:

Lifecycle tools — set a library up from nothing, no shell required:

MCP tools are read at client start-up, so restart your assistant's session after adding the server.

For agents

This is built to be installed and driven by agents, not just people.

Nothing blocks. Installing takes minutes and the first index build downloads a ~2 GB model, so homestead_install returns a job id straight away and you poll homestead_job until status is done or error.

Start with homestead_status. It works with nothing running and no corpus on disk, and every failing check carries its own remedy. The top-level next field is the single command to run:

{
  "ready": false,
  "checks": {
    "corpus":     {"ok": false, "documents": 0, "remedy": "homestead install --pack essentials --yes"},
    "index":      {"ok": false, "remedy": "homestead index"},
    "embeddings": {"ok": true,  "remedy": null},
    "server":     {"ok": false, "remedy": "homestead serve"}
  },
  "next": "homestead install --pack essentials --yes"
}

From a shell, every command takes --json, and errors carry the fix:

homestead doctor --json            # same object as homestead_status
homestead install --list --json    # the whole catalog, with licences
homestead bootstrap --pack essentials --json    # install + index, one step
homestead search "water purification" --json
homestead --url http://other-host:8021 search "..."   # target another library

homestead install never prompts when stdin is not a terminal. Without a selection it exits 2 and tells you which flags would have worked, rather than guessing or hanging:

{
  "ok": false,
  "error": "no shelves selected and stdin is not a terminal",
  "remedy": "homestead install --pack essentials --yes --json",
  "valid_packs": ["essentials", "growing", "fixing", "everything"]
}

Downloads are idempotent — a finished file is never re-fetched, so re-running an install is safe and cheap.

Commands

homestead install          choose shelves and download them
homestead install --list   show the catalog and its licences
homestead index            (re)build the search index
homestead serve            run the library server (loopback only)
homestead serve --host 0.0.0.0   share it on your network
homestead search QUERY     search from the terminal
homestead add FILE -c soil add a document of your own
homestead bootstrap        install + index in one step (unattended)
homestead paths            where everything lives
homestead doctor           check the installation (--json for agents)

Where things live

Defaults follow the XDG spec; every path is overridable.

Set HOMESTEAD_HOME to move all of it at once.

Local shelves

A library grows shelves the packaged catalog knows nothing about. Declare them in site.toml (in HOMESTEAD_HOME, or set HOMESTEAD_SITE_CONFIG) rather than forking:

[[category]]
slug  = "boatbuilding"
label = "Boatbuilding"
icon  = "~"
match = "boats"        # any corpus path containing this lands on this shelf

How it works

Documents are split into overlapping ~1200-character passages and embedded with BAAI/bge-m3 locally. Search embeds the query and takes a cosine top-k, grouped by document. For PDFs the server keeps a chunk → page map, so an answer can tell you the page to turn to.

The corpus index is read-only. Anything you add later goes into a separate overlay that is searched alongside it, so adding documents can never corrupt the base index — and deleting the overlay loses only your additions.

A word on trust

This is reference material, gathered for the situation where better help is not available. It is not medical, legal, or engineering advice. Two shelves carry explicit cautions the software will show you — foraging (misidentification kills) and food preservation (follow current USDA process times, not the ones in century-old cookbooks). Semantic search has no idea a 1918 canning time has since been proven dangerous. Read accordingly.

Security

The server binds 127.0.0.1 by default and has no authentication. That combination is safe: nothing off your machine can reach it.

To use the library from a phone or another computer, bind wider:

homestead serve --host 0.0.0.0        # or set HOMESTEAD_HOST

Now anyone who can reach that port can read your whole library and add documents to it, so do this only on a network you trust — a home LAN, or better, a private network like Tailscale. Loopback and Tailscale peers are always trusted; other clients are challenged with Basic Auth if you set credentials (.auth.env, or HOMESTEAD_AUTH_USER / HOMESTEAD_AUTH_PASS). With none set there is no challenge at all. The server warns you on startup when it is bound beyond loopback without credentials.

Contributing

Adding a source to the catalog is the most useful contribution. It must be free to download from the publisher, correctly licensed, and recorded with its real licence in shelves.toml. See the notes at the top of that file.

Installing

pip install homestead-library              # CLI + MCP server, no dependencies
pip install 'homestead-library[server]'    # + embeddings, to host a library
pip install 'homestead-library[all]'       # + Stack Exchange dump support

The command is homestead; the MCP server is homestead-mcp.

Licence

MIT. The documents the installer downloads carry their own licences, recorded per-entry in the catalog. The Stack Exchange corpora are CC BY-SA 4.0 — attribution belongs to Stack Exchange and the individual authors.