Skip to content

Firefox companion

The companion saves posts from profiles you visit in Firefox. This guide sets up its two parts on your computer: the extension, and Homestead Helper.

When it’s released

Section titled “When it’s released”

The web app will show a three-step setup guide, each step turning green when it’s detected:

  1. Add Homestead Companion to Firefox from addons.mozilla.org.
  2. Install Homestead Helper: download it for macOS, Windows or Linux, then run one command with your server address.
  3. Connect: the extension opens its options page with your address filled in, and you enter the pairing code shown in Homestead.

Before you start (from source)

Section titled “Before you start (from source)”
  • Firefox 140 or newer, on a computer.
  • A clone of the repository.
  • Node 22 and pnpm 9 to build the extension, and Go 1.26 to build the helper. make tools installs the pinned versions with mise.

Build and load the extension

Section titled “Build and load the extension”

  1. From the repository root, install the JavaScript workspace.

    Terminal window
    pnpm install

  2. Build the Firefox extension.

    Terminal window
    pnpm -C extension build

  3. The build lands in extension/.output/firefox-mv3. For testing, Firefox can load that folder as a temporary add-on from about:debugging.

The extension’s ID is companion@homestead.app. It asks for storage, tabs, tabGroups, scripting, nativeMessaging and webNavigation. Access to each platform’s pages is optional and requested only when you turn that platform on. It never asks for all sites.

Build and install the helper

Section titled “Build and install the helper”

  1. Build the helper binary from the helper folder.

    Terminal window
    cd helper
    Terminal window
    go build ./cmd/homestead-helper

  2. Move the binary to where it will live. The registration records its full path, so if you move it later, run install again.

  3. Register it with Firefox and pin your server’s address. Use the address you open Homestead at, with no path.

    Terminal window
    homestead-helper install --server https://home.example.com

install writes Firefox’s native-messaging manifest and stores the pinned address in the per-user config directory (homestead-helper/config.json):

~/Library/Application Support/Mozilla/NativeMessagingHosts/app.homestead.helper.json

The manifest only allows the Companion extension to talk to the helper. The helper only uploads to the pinned address.

Connect the extension

Section titled “Connect the extension”

Open the extension’s options page. Enter your Homestead address and a pairing code. A pairing code comes from Open on my phone on the last welcome step, and will come from the setup guide. It lasts 10 minutes. The extension then holds its own device token and acts as you.

In the options you choose which platforms to capture, whether to scroll pages during updates (2 screens by default, 0 to turn it off), and whether to show a small in-page note. The popup shows the current page’s status, a Save when I visit switch, the helper’s status, and Add to Homestead for profiles you don’t follow yet.

Check the helper

Section titled “Check the helper”
Terminal window
homestead-helper status

It prints the binary path, the manifest path and whether it’s present, the registry key on Windows, the pinned server, and how many Firefox profiles with a cache it found.

Terminal window
homestead-helper version

Remove it

Section titled “Remove it”
Terminal window
homestead-helper uninstall

This removes the manifest, the registry key on Windows, and the pinned address. Remove the extension from Firefox’s add-ons page.