A computer for your agent.
Start with your own.

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. Install and authenticate the official Codex or Claude Code CLI on the same host. BotHearth does not include model access.

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. Build and initialize

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. The development command modelbot remains an alias. Without a global link, run node dist/cli/index.js followed by the same arguments.

At the vault passphrase prompt, press Enter to use the OS keychain: macOS Keychain or Secret Service on Linux. Initialization writes ~/.modelbot/modelbot.yaml, private tokens, and data under ~/ModelBot. These legacy storage names are intentional; the rename does not move your data. Keep the encrypted vault and its original key provider available. Do not use --force to fix an unknown initialization problem.

Start the daemon

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 → AI connection. Choose Codex or Claude Code and complete the provider's normal sign-in. The installed CLI handles authentication; BotHearth does not ship a provider CLI or ask you to paste consumer session credentials.

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 into the task box and select Start task:

Open https://example.com/ and read the visible page. Save out/example.md with its page title, source URL, and a one-sentence summary in your own words. Do not follow links, submit forms, or sign in. Finish by naming the saved file.

Approve only the expected destination. Watch the activity feed and live browser. Open the saved file and compare it with the page yourself. The complete example includes an expected title and a checklist; model-generated output can still be wrong.

When a site needs a password or code, select Take 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.

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 shell is still built as ModelBot.app and 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.