Set up your agent.
Give it a first task.

What do I need to run BotHearth?

You need macOS or Linux, Node.js 22.18 or newer, Git, a running container runtime, and an eligible model account. BotHearth installs the official Codex and Claude Code CLIs in its computer during image setup. Codex is verified live; Claude Code is listed and not yet verified live. Connect an eligible account in Settings; model access is not included.

Container runtimes have their own licence and eligibility rules. Model plans have their own terms, limits, and charges. Read the provider requirements and cost breakdown before connecting.

1. Clone, build, initialize, start, pair

git clone https://github.com/sanjaygbhat/bothearth.git
cd bothearth
npm ci
npm run build
npm link
bothearth init

npm link installs the bothearth command locally from this checkout. Without a global link, run node dist/cli/index.js followed by the same arguments.

Initialization uses macOS Keychain or an unlocked Linux Secret Service automatically. For an unattended Linux VM, prepare an encrypted vault key using the remote deployment guide before starting an unattended service. Initialization writes ~/.modelbot/modelbot.yaml, private tokens, and data under ~/ModelBot. Keep the encrypted vault and its original key provider available. Do not use --force to fix an unknown initialization problem.

Open BotHearth

bothearth start

Open the localhost link it prints. The default address is 127.0.0.1:7777. The sign-in link expires after ten minutes and works once. Anyone holding an unused link can gain operator access, so keep it out of chats, screenshots, and issue reports.

For a new link, run bothearth pair. A paired browser remains signed in with a seven-day inactivity timeout and a thirty-day maximum session lifetime. Leave the foreground process running; use Ctrl+C to stop it. For background operation, use bothearth start --daemon and later bothearth stop.

2. Connect your model account

In the browser, open Settings → Model connection. Choose Codex (verified live) or Claude Code (listed; not yet verified live) and complete the provider's normal sign-in inside the bot. The official CLI inside the computer handles authentication. Codex uses its device sign-in page; Claude Code shows its native instructions. Your login remains in that computer’s private model home.

Eligibility depends on the provider and your account. Being able to sign in is not a promise that every plan or automated task is permitted. BotHearth is independent of OpenAI and Anthropic.

For the normal task interface, use this connection screen. The separate connect command configures manual MCP integrations and needs additional task binding; it is not needed for this first task. Compare the model connection paths.

3. Run one task you can check

The home screen builds the computer images when you first need them. You can also build them explicitly:

bothearth image build

There are no published prebuilt images in this release. Use the BotHearth image command so the images receive the expected source stamps.

Paste this browser task into the task box, then select Start task:

Open https://bothearth.com/faq/ and https://bothearth.com/security/ in your browser. Save getting-started-answers.md with a short table answering: What do I need to install? Where does my data go? When do I take control? Put the page URL beside each answer. Mark anything the pages do not explain. Do not sign in or submit anything. Finish by naming the saved file.

Watch it open the pages, then open getting-started-answers.md in the results. Follow each source link and check that the page supports the answer. Try a live website audit next, or compare options from their current pages.

When a site needs a password, OTP, passkey, or CAPTCHA, select Take control. Take control requests full screen; Esc leaves full screen without returning control. Model capture and ordinary agent actions are blocked while you drive; the website still receives your input. Select Give control back when ready. Ten minutes without input pauses human control; it does not automatically return the browser to the agent. Review prompts are off by default; Settings → Sensitive actions → Ask before sensitive actions turns them on.

If something stops

Run bothearth doctor for a local diagnostic. Review output for private paths or account data before sharing it. For more detail, read the troubleshooting guide.

The optional macOS app is not notarized. Phones use a paired client with a private connection; do not expose the daemon as a public website. Both are advanced paths in the full quickstart.