Install

Install Homestead

Homestead runs on your own computer, NAS or Raspberry Pi. There's no release yet, so you build it from the source. It takes a few minutes.

Not released yet. There are no tags, no published image and no store listings. The commands below buildmain as it is today (5256875, 2026-10-24). Expect rough edges, and back up before you update.

Requirements

  • A machine that runs Docker: Linux, macOS or Windows, on amd64 or arm64 (the image is multi-arch, so a Raspberry Pi or a NAS works).
  • Git, to get the source.
  • Node 22 and pnpm 9, to run the web app for now (pinned in mise.toml).
  • Ports 8080 (server) and 5173 (web app) free.
  • To build without Docker: Go 1.26 as well (server/go.mod).

Pick your system to see the right prerequisites. Everything else is the same everywhere.

Linux

Install Docker Engine with the Compose plugin from your distribution or Docker's packages, plus git. Node 22 and pnpm 9 come from your package manager, or from mise, which reads the repo's mise.toml.

macOS

Install Docker Desktop (or another Docker engine), Git (included with the Xcode command line tools), and Node 22 with pnpm 9, for example with mise, which reads the repo's mise.toml.

Windows

Install Docker Desktop with the WSL 2 backend, Git for Windows, and Node 22 with pnpm 9. Run the commands below in a WSL shell or PowerShell from the folder you cloned.

Install the server

First, get the source:

git clone https://github.com/aprajnaparamita/homestead.git
cd homestead

Then choose how to run it.

Docker Compose (recommended)

Open deploy/compose.yaml and look atHOMESTEAD_BASE_URL. It ships set to the example https://home.example.com. For use athttp://localhost or on your home network, delete that line (and the environment: line if nothing is left under it). With an https base URL the server rejects saves from any other address.

Build and start

docker compose -f deploy/compose.yaml up -d --build

The household's data lives in the homestead-data volume. The service restarts on its own. An optional caddy profile adds a TLS reverse proxy; see remote access.

Docker

Build the image (from the repo root)

docker build -f deploy/Dockerfile -t homestead .

Start the container

docker run -d --name homestead -p 8080:8080 -v homestead-data:/data homestead

The container runs as a non-root user (uid 10001). Everything it keeps is in /data, the homestead-data volume.

From source (Go)

Build the server binary with Go. CGO_ENABLED=0 matches the Docker build; the SQLite driver is pure Go.

Build

cd server && CGO_ENABLED=0 go build -trimpath -o ../homestead ./cmd/homestead && cd ..

Run, keeping data in ./data

HOMESTEAD_DATA_DIR=./data ./homestead serve

Or let the repo do it: make tools installs the pinned toolchains with mise, and make dev runs the server and the web app together.

After the first release, the app's docs name a ready-made image:docker run -d --name homestead -p 8080:8080 -v homestead-data:/data ghcr.io/homestead-app/homestead:latest. It doesn't exist yet and the address may change.

Open the web app

On main, the server answers the API on port 8080 but doesn't serve the web app yet (openinghttp://localhost:8080/ returns 501). Until it does, run the web app's development server from the same checkout. It forwards /api, /media and /mcp to the server.

Install the workspace (from the repo root)

pnpm install --frozen-lockfile

Start the web app (leave it running)

pnpm --dir web dev

Now open http://localhost:5173/setup, name your household and create the owner account. First run walks through each step.

Check it works

curl http://localhost:8080/api/v1/health

A healthy server answers {"status":"ok","version":"dev"} (a local build reports dev). docker ps shows the container as healthy, because the image runs the same check every 30 seconds.

On your phone

Web app (works today)

Start the web app with pnpm --dir web dev --host so other devices can reach it, then open the machine's address on port 5173 in your phone's browser, for example http://192.168.1.20:5173. Sign in, and add it to your home screen from the browser menu: it's a PWA, and on Android Chrome it can receive links through "Share to Homestead".

Homestead app

The Flutter app for iOS 15+ and Android 8+ can already connect, sign in and pair by QR code, and it finds Homestead on your Wi-Fi by itself. Its feed, stories and people screens are still being built Coming in 1.0, and it isn't in any store yet. Developers can build it from mobile/.

Away from home, use Tailscale, a Cloudflare Tunnel or a reverse proxy with TLS, in that order of simplicity. See remote access.

Firefox companion Coming in 1.0

The companion saves posts from profiles you follow while you browse in Firefox 140 or later. It has two parts: the extension, and Homestead Helper, a small program that reads images from Firefox's cache. The extension and the helper are built, but the server side of captures, the setup screen and the add-ons listing are still to come.

When it's ready, the helper installs with one command, which registers it with Firefox and pins your server's address:

homestead-helper install --server https://your-homestead.example

Linux

Registration file: ~/.mozilla/native-messaging-hosts/app.homestead.helper.json. The helper reads ~/.cache/mozilla/firefox/*/cache2/entries only.

macOS

Registration file: ~/Library/Application Support/Mozilla/NativeMessagingHosts/app.homestead.helper.json. The helper reads ~/Library/Caches/Firefox/Profiles/*/cache2/entries only.

Windows

Registration file: %LOCALAPPDATA%\homestead-helper\app.homestead.helper.json, registered under HKCU\Software\Mozilla\NativeMessagingHosts\app.homestead.helper. The helper reads %LOCALAPPDATA%\Mozilla\Firefox\Profiles\*\cache2\entries only.

homestead-helper status shows what is registered, and homestead-helper uninstall removes it. More in the companion guide.

Update

Back up first. The archive holds the database, media and secret key:

Docker: back up inside the volume

docker exec homestead homestead backup --out /data/backup.tar.gz

Get the latest main

git pull

Compose: rebuild and restart

docker compose -f deploy/compose.yaml up -d --build

With plain Docker, rebuild the image, then remove and recreate the container. The volume keeps your data. Database migrations run on their own at start.

Uninstall

Stop and remove the containers (data stays)

docker compose -f deploy/compose.yaml down

Warning: this deletes the household for good. Removing the volume deletes people, media, settings and the secret key. Make a backup first if you might want it back.

Compose volume (the compose project is named homestead; check with docker volume ls)

docker volume rm homestead_homestead-data

Plain Docker volume

docker volume rm homestead-data

Remove the helper with homestead-helper uninstall.

Troubleshooting

The browser shows "not implemented" at port 8080
Expected on main: the server doesn't serve the web app yet. Use the web app at port 5173 (above).
Saving fails with "403 cross-origin request rejected"
HOMESTEAD_BASE_URL doesn't match the address in your browser. Remove it for home use, or set your real public address.
The phone app can't find the server on Wi-Fi
Docker's bridge network can't reach the LAN multicast group, so discovery stays silent. On Linux, run the container on the host network (network_mode: host in the compose file), or type the address in the app.
Where are the logs?
docker logs homestead (or docker compose -f deploy/compose.yaml logs homestead). Set HOMESTEAD_LOG_LEVEL=debug for more detail.
Forgot the owner password
Run homestead user reset-password USERNAME inside the container. It generates a random password unless you give one with --password-file.

Still stuck? See troubleshooting or report a bug.