First run

The first person to open a new Homestead creates the household and becomes its owner. Setup only works while no household exists; after that, /setup sends everyone to the login screen.

Create your Homestead

Open the setup screen at /setup: http://localhost:5173/setup while the web app runs on its development server.

The web app runs separately for now

On main, the server answers the API on port 8080 but doesn't serve the web app yet: opening http://localhost:8080/ returns 501 not_implemented (webdist is still empty). Until that lands, run the web app's development server from the same checkout, as in Quick start. It listens on http://localhost:5173 and forwards /api, /media and /mcp to the server.

1. Choose your language. Pick English, 中文（简体） or ไทย. The page switches language straight away. Homestead suggests one from your browser’s language settings.

2. Name your home. This is the household name family members see, for example “The Wongs’ Homestead”. Up to 60 characters.

3. Your name. How you appear to the rest of the household. Up to 60 characters.

4. Username. What you sign in with: 3 to 32 letters, digits, dots, dashes or underscores.

5. Password. At least 8 characters.

6. Select Create my Homestead. You’re signed in and taken to the welcome steps.

Tip

Write the username down somewhere safe. If you forget the password, the server owner can reset it from the command line; see Troubleshooting.

The welcome steps

Three short steps follow. Each one can be skipped with I’ll do this later, and you can come back to all of them later.

1. Who do you want to keep up with?

Paste profile links, share text or @handles, one or many. Homestead finds the people and adds them. Below the paste box you can choose which circles to start with: Family and Friends are on by default, Favourites is off.

The Add people page shows what you can paste.

2. Let an AI agent help?

An agent can fetch stories from Instagram, Facebook, Douyin and Xiaohongshu using your own logged-in browser. Choose Hermes, OpenClaw or Other, or Not now. The button takes you to the Agents screen, which is still being built. Available on main (W-08) Until then, see Connect an agent for the command-line way.

3. Bring the family

This step shows two QR codes:

• Invite someone. Anyone with this link can join your household as a viewer. Viewers can read the feed and stories but can’t add or change people. See Invite family.
• Open on my phone. A pairing code for the Homestead phone app. See Open on your phone.

Select Go to my Homestead to finish. You land on the feed.

What you’ll see next

If you added people on Bluesky or Truth Social, their posts arrive within the fetch interval (an hour by default for server-tier platforms). People on Instagram or Douyin need an agent. People on WeChat or personal LINE show up as visit suggestions, because Homestead can’t see their posts.

An empty household shows “Your Homestead is empty” with a button to add people.

Check that it worked

• The feed opens at / with your household name in the sidebar (on wide screens).

• GET /api/v1/setup now returns "needsSetup": false:

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