Getting Started with Hearth

Hearth lets you run AI agents on your home computer and manage them from your iPhone. The agents do the work; you stay in control of what they're allowed to do. This guide walks you through setup from scratch.

What You'll Need

• A Mac or Linux computer (or Windows with WSL2) where agents will run — this can be a machine that stays on at home
• An iPhone with the Hearth app installed (coming soon to the App Store)
• Basic comfort with a terminal application

Step 1: Install Hearth on Your Computer

Open a terminal and run:

curl -sSL https://hearthcmd.dev/install.sh | bash

This downloads and installs the hearth command to /usr/local/bin/hearth. Confirm it's installed correctly:

which hearth
hearth -v

Step 2: Log In

hearth login you@example.com

Hearth sends a 6-digit code to your email. Paste it at the prompt:

A 6-digit code has been sent to you@example.com.
Enter the code: 123456

On first login you'll be asked for your name and a name for your household (your "organization" in Hearth). Defaults are fine — just press Enter. Once verified, this computer is enrolled and ready.

Step 3: Start the Hearth Daemon

The daemon is a small background process that keeps your computer connected and manages your agents:

hearth host start

Check that it's running:

hearth host status

To stop it: hearth host stop. Note that it does not restart automatically after a reboot — you'll need to run hearth host start again, or set it up as a startup item.

Step 4: Sign In on Your iPhone

Open the Hearth app, enter the same email address, and verify with the code that arrives. The app will find the computer you just enrolled and show it connected.

Step 5: Start Your First Agent

Agents are the AI assistants that do the actual work. You can start one from the app or from your terminal.

From your phone

1. Tap the + button on the home screen.
2. Choose Temp Agent for a one-off task, or Full-time Agent for something you want to run regularly.
3. Choose the AI (Claude, Gemini, and others are supported).
4. Tap Start and give the agent its first instruction.

From the terminal (quick start)

Navigate to the folder you want the agent to work in, then:

hearth hh agent create --temp

This spins up a temp agent in the current directory and opens a live view of what it's doing.

Approving Requests

When an agent wants to do something that needs your sign-off — read a file outside its working folder, access the web, run a system command — you'll get a notification. Open it to see exactly what the agent is asking to do, then tap:

• Allow — let it proceed this one time
• Always Allow — approve this type of action automatically from now on
• Deny — block this action; the agent will move on
• Deny & Stop — block the action and halt the agent immediately

The first few sessions will have more requests as the system learns your preferences. After you've tapped "Always Allow" a few times on the things you trust, most actions will happen automatically.

Smart Rules

Every "Always Allow" creates a rule. Hearth's rules are specific: approving one web request doesn't open the floodgates to all web requests. Rules are scoped by action type, and for sensitive operations like deleting files, each exact command gets its own rule.

You can review, edit, and delete your rules any time in the Grants tab for any agent.

Tips for Getting the Most Out of Hearth

• Start with a specific task. "Research the best air purifier under $200 and write up a comparison" works better than "help around the house."
• Use temp agents for one-off jobs. They're quick to spin up and clean up after themselves.
• Set up full-time agents for recurring work. A full-time agent remembers context across sessions and builds up a useful set of permissions over time.
• Enable push notifications. Agents can get stuck waiting for you. With Pro, you'll get notified on your phone the moment one needs a decision.
• Check the Chat tab. It's the best way to understand what your agents are actually doing and catch anything unexpected.

Troubleshooting

See the support page if something isn't working.

Questions?

Email support@vergelabs.org — we're happy to help.