Most OpenHuman install guides only say “click next”—so when something breaks, you cannot tell whether the problem is download, login, models, or memory. This walkthrough follows the normal setup path end to end, with success signals and what to check when stuck at each stage. The goal is not a giant error catalog; it is to get you from zero to a working first run.
0 Overview: seven stages from zero to first run
When you hit a wall, first locate the stage: download → install → login → models → integrations → memory → first output. The table below is your map; later sections go deeper.
| Stage | Success signal | Common blocker | Next step |
|---|---|---|---|
| Prep | Site loads, RAM meets minimum | Network/DNS, low RAM | Fix network or add RAM before installing |
| Download & install | App launches; version matches site | Wrong project, wrong arch | Verify domain and GitHub Release |
| Login | Main UI visible | OAuth redirect fails | Try another browser; disable blockers |
| Models | “Hello” gets a reply | BYOK or local model silent | Confirm cloud routing first, then local |
| Integrations | Source shows connected | OAuth expired, narrow scopes | Re-authorize; check sync scope |
| Memory | Memory has entries | Empty tree, <20 min wait | Wait for first auto-fetch cycle |
| First task | Summary/todos match data | No context, wrong answers | Split “model vs memory” |
1 Before you install: system, network, accounts, test data
Per the official Getting Started guide, OpenHuman runs on macOS, Windows, and Linux desktops with 4 GB+ RAM recommended. For huge mailboxes/repos or local models on the same machine, plan for 16 GB+.
- Network — You can reach tinyhumans.ai/openhuman and GitBook docs. The default path still uses hosted login and model routing (not fully offline).
- Accounts — Have Google/GitHub ready for sign-in. Third-party connectors need separate OAuth; logging in does not connect Gmail by itself.
- Test data — Start with a low-sensitivity mailbox or spare GitHub account so you can verify memory writes. Do not wire your full production inbox on day one.
- Optional local models — If you plan Ollama, run
ollama runsuccessfully in a terminal before enabling Local AI in OpenHuman.
2 Download source: catch the wrong project or version
Success signal: Installer from tinyhumans.ai/openhuman or an official package channel; About version matches the latest GitHub Release.
Official paths (pick one):
- Website installer — macOS DMG, Windows MSI/EXE, Linux AppImage or .deb (clearest for beginners).
- Homebrew —
brew install tinyhumansai/openhuman/openhuman - Script install — macOS/Linux:
curl -fsSL https://raw.githubusercontent.com/tinyhumansai/openhuman/main/scripts/install.sh | bash; Windows PowerShell script in the README. On a primary machine, prefer the signed website download over piping remote shell code.
tinyhumansai/openhuman, or a third-party “all-in-one crack” bundle. When unsure, download only from the official site and GitHub org.3 Platform install: Mac, Windows, Linux checkpoints
| Platform | Pass criteria | If stuck, check |
|---|---|---|
| macOS | DMG installs; app opens; Gatekeeper → Open if prompted | Blocked by security → System Settings → Privacy & Security |
| Windows | MSI/EXE finishes; OpenHuman in Start menu | SmartScreen → verify publisher; missing VC++ runtime |
| Linux | AppImage runs or apt install succeeds | amd64 vs arm64 matches your CPU |
On first launch macOS may ask for Accessibility or Input Monitoring (voice hotkeys). Review under Settings → Automation & Channels; you can deny permissions not needed for your first successful run.
4 First launch: login, workspace, won’t open
The welcome screen is “Sign in! Let's Cook” with social login. Most users can ignore Advanced custom core RPC URL.
Success signal: main UI with chat and Settings. If stuck: OAuth blocked by extensions → try Safari/Edge private window; login works but blank screen → quit fully and relaunch; check in-app logs/diagnostics (entry point varies by version in Settings).
5 Models: default routing, BYOK, local silence
OpenHuman uses Automatic Model Routing per task. For beginners: confirm cloud routing replies first, then enable Local AI.
Success signal: send “Hello” or “Introduce yourself in one sentence” and get a normal reply. If stuck:
- No response at all — network/proxy; Early Beta outage (check Discord/GitHub Issues).
- BYOK fails — full key pasted, provider matches settings, account has quota.
- Ollama / LM Studio silent — verify local service in terminal first; then enable Local AI in Settings and check
local_ai.runtime_enabledper GitBook Configuration.
6 Integrations: OAuth, scope, refresh
Connect Gmail, GitHub, calendars, etc. under Settings. Success signal: list shows connected with no persistent errors.
If stuck: connected but no data → read scopes include fetch rights; Workspace Google may need admin approval; no refresh → wait ~20 minutes for the first auto-fetch cycle (per docs)—do not reinstall after a few minutes.
7 Memory sync: empty context and how to verify
Memory lives locally in the Memory Tree (SQLite + Markdown). Open the vault via Memory → View vault in Obsidian (/wiki/).
Success signal: within ~20 minutes after connecting Gmail, Memory shows new entries; asking “What should I know from the last 12 hours?” cites real subject lines.
If stuck: still empty → OAuth really succeeded, test account actually has mail, first cycle not finished; bad summary → spot-check raw entries in Obsidian to separate model hallucination from missing source data.
8 First real task: validate setup in one shot
Try prompts like the official examples: “Summarize what I missed today.” or “From my connected sources, list my top three todos for today.”
Pass criteria: ① model replies; ② facts in the reply exist in Memory/Obsidian; ③ a narrower follow-up (e.g. a project name) still hits. Only ② fails → memory path; only ① → models; both fail → login and network.
9 Wrap-up: when to reinstall, keep your config
Check docs/Issues before reinstalling: single OAuth failures, one integration, or local Ollama usually do not need a full app reinstall. Reinstall when the package is corrupt, you need a clean major upgrade, or Release notes say so.
To keep data: Memory Tree and the Markdown vault are on disk—note the vault path on the Memory page and back up that folder before uninstall (do not delete unknown directories). Uninstall: brew uninstall openhuman for Homebrew; apt remove for Debian/Ubuntu; manual curl installs see GitHub docs/install.md.
Still blocked → GitHub Issues, Release notes, or Discord (discord.tinyhumans.ai) with version and repro steps.
Check all seven and OpenHuman is working and debuggable on your machine:
- 1Installed from official channels; version matches Release
- 2Signed in; main UI chats
- 3Default model routing answers “Hello”
- 4At least one low-sensitivity integration OAuth’d
- 5Memory has entries; Obsidian opens vault
- 6First summary/todo task matches your data
- 7You know which stage failed and where official docs live
10 Run OpenHuman more reliably on Mac mini
OpenHuman runs background auto-fetch, SQLite writes, and optional Ollama inference. A Mac mini M4’s unified memory fits smaller local models; idle power around ~4W suits quiet 24/7 use. On macOS, Homebrew install, permission prompts, and Obsidian vault access are straightforward. Keeping your personal Memory Tree on a dedicated mini also isolates it from your daily driver. If you are planning a first personal-agent lab machine, Mac mini M4 is a clear value starting point—get the flow working here first, then move to an always-on Mac mini node.
OpenHuman 24/7 · local memoryGet Mac mini M4 for your OpenHuman node
Low-power always-on · unified memory for Ollama · isolated from your main Mac while you test personal AI memory workflows.