2026 OpenHuman Complete Install & Configuration Guide: Step-by-Step Hands-On Tutorial from Zero to Running

2. Do not install the wrong project: desktop assistant vs WebGL SDK

OpenHuman (this guide) is the tinyhumansai/openhuman open-source desktop personal AI assistant: UI-first, Memory Tree, Obsidian-style Markdown vault, 118+ OAuth integrations, optional local Ollama. It still uses OpenHuman hosted services for account login, model routing, search proxy, and Composio-layer OAuth by default (you can gradually switch to BYOK / direct Composio in settings).

There is also an OpenHuman WebGL digital-human SDK online—aimed at web 3D avatars, not what this guide installs. If your goal is “personal knowledge base + email/calendar/repo context,” use the desktop repo and the tinyhumans.ai/openhuman download page.

It is also not a generic web chat tab: OpenHuman emphasizes local workflow data + scheduled integration pulls, not a one-off browser window. Compared with CLI-first agents, OpenHuman uses a graphical UI + short onboarding—you do not need a config file before your first message.

3. Pain points

1. Constraint: treating “installed” as “it already understands me.” Official docs state Memory Tree, Markdown vault, workspace config, and local runtime state live on your machine; login, model routing, search proxy, and default OAuth may still use hosted backends. Without connected integrations and a completed sync, the agent can only speak in generalities.
2. Hidden cost: over-broad permissions and production accounts on day one. One OAuth grant can cover mail read, calendar, repos, and more. While the app is still Beta, start with a test inbox or test GitHub repo, confirm scopes and revoke paths, then connect real work data.
3. Stability & audit: not knowing where memory and logs live. Uninstall-and-reinstall without notes can erase the only SQLite and vault sync trail. Record workspace path, integration IDs, and model mode (hosted / BYOK / Ollama) for rollback.

4. Pre-install checklist

Goal: discovering network or disk issues halfway through wastes hours. Pass criteria: every item below checked before downloading.

• OS: macOS (Apple Silicon or Intel), Windows 10/11 (64-bit), Debian/Ubuntu or Arch Linux desktop. Minimum versions follow the current Release notes; product is labeled Early Beta—UI paths may change.
• Hardware: 16GB+ RAM recommended (local Ollama needs more); reserve ≥5GB disk (app + vault + SQLite + model cache—actual use varies).
• Network: Reach GitHub, tinyhumans.ai, and OAuth redirect domains; configure system proxy or allow browser pop-ups if behind corporate proxy.
• Accounts: OpenHuman product account; BYOK API keys from model vendors if needed; Ollama installed and a model pulled if using local inference.
• Test data: Dedicated test Gmail / test GitHub repo—do not connect company Slack or production inbox on first run.
• Permissions: macOS may ask for notifications, microphone (voice), and file/folder access; on Linux, note known AppImage + Wayland issues (official issue #2463).

5. Download sources & security verification

Official priority (README): ① Official site / GitHub Release installers → ② Native package managers (Homebrew, signed apt, MSI) → ③ Script install (no standalone script signature—use only if you understand the risk).

Check first on failure: corrupted file → re-download from Release; SmartScreen / Gatekeeper block → confirm publisher then allow; do not substitute unknown “mirror” sites for official packages.

6. Three-platform install steps

6.1 macOS (Homebrew recommended)

brew tap tinyhumansai/core
brew install openhuman

Alternatively download the .dmg from Release and drag to Applications. Pass criteria: OpenHuman opens from Launchpad. Check first on failure: “cannot verify developer” → System Settings → Privacy & Security → Open Anyway; allow notifications/microphone/file access on first run (minimum set for features you actually use).

6.2 Windows (signed MSI)

Download .msi from the latest release and run the installer. On SmartScreen, confirm the publisher. Pass criteria: Start menu shortcut launches the app. Check first on failure: enterprise policy block, antivirus quarantine, firewall blocking OAuth browser callback.

6.3 Linux (apt recommended; AppImage with caution)

sudo apt-get install -y --no-install-recommends gnupg2 curl ca-certificates
curl -fsSL https://tinyhumansai.github.io/openhuman/apt/KEY.gpg \
  | sudo gpg --dearmor -o /etc/apt/keyrings/openhuman.gpg
echo "deb [signed-by=/etc/apt/keyrings/openhuman.gpg arch=amd64] \
  https://tinyhumansai.github.io/openhuman/apt stable main" \
  | sudo tee /etc/apt/sources.list.d/openhuman.list
sudo apt-get update
sudo apt-get install -y openhuman

Arch users can try the repo’s openhuman-bin AUR recipe (yay -S openhuman-bin—verify AUR listing). AppImage may fail on Wayland or some Arch setups (official issue #2463); Debian/Ubuntu should prefer .deb / apt. Pass criteria: desktop menu launches the app. Check first on failure: missing libraries, Wayland env vars, switch to X11 session.

6.4 Platform install decision matrix

Uninstall & reinstall: disconnect all OAuth integrations first and back up vault directories you care about; after uninstall, workspace and SQLite may remain under your user profile—confirm official data paths before deleting the only memory copy.

7. First launch & account login

1. Launch the app and choose a dedicated workspace directory—avoid pointing at your entire home folder.
2. Sign in with your OpenHuman product account (default hosted login flow). Pass criteria: Settings shows logged-in state.
3. Review update channel and privacy-related toggles (notifications, voice, search proxy)—keep defaults until the first run passes, then tune.

Check first on failure: blank login page → try default browser, disable ad blockers; repeated failure → verify system time, DNS, proxy needs; regional or subscription policies follow current official docs—this guide does not promise identical features in every region.

8. Model configuration & BYOK

Hosted models (default): OpenHuman backend performs model routing (picking reasoning/fast/vision models per task). Official wording includes multi-model routing within subscription; pricing and quotas on your account page may change.

BYOK (Bring Your Own Key): Enter vendor API keys in settings—you pay usage and manage quotas; good for existing enterprise contracts or fine cost control.

Local models (Ollama): Official docs support optional local AI; Apple Silicon Mac unified memory helps smaller models, but large models still hit RAM limits—verify latency and quality yourself.

Pass criteria: send a test prompt (e.g. “Introduce yourself in one sentence”) and get a coherent reply. Check first on failure: hosted → subscription/network; BYOK → key permissions and billing; Ollama → service listening and model name match.

9. Integrations & permission configuration

OpenHuman exposes Gmail, Slack, Notion, GitHub, Calendar, Drive, and 118+ connectors via a Composio connector layer. Default OAuth handshake and tool calls proxy through the hosted backend; for direct Composio, add your own Composio API key in settings and host real-time trigger webhooks yourself.

OAuth is the standard “sign in via browser and grant the app limited access on your behalf” flow. Read the permission scopes on the consent screen—grant only what your hands-on case needs; if a scope is unclear, do not approve it yet.

Pass criteria: integration shows Connected and OAuth callback completes without error. Check first on failure: blocked pop-ups, corporate SSO, Composio status, network proxy.

10. How to accept the memory system

For newcomers, OpenHuman memory works like this:

• Memory Tree: organizes pulled integration data into hierarchical summaries stored locally in SQLite for agent retrieval.
• Markdown vault (Obsidian-compatible): the same knowledge also lands as .md files you can browse and edit in Obsidian.
• auto-fetch: each active connection pulls new data roughly every 20 minutes—no manual polling script required.

Acceptance steps: connect test integration → wait at least one 20-minute cycle (or manual trigger if UI offers it) → check Memory view or vault for new Markdown blocks → ask a question only test data can answer (e.g. a unique keyword from a test email).

Pass criteria: answer references correct sources or file snippets. Check first on failure: integration inactive, sync incomplete, or asking about production data when only test source is connected (empty-context hallucination).

11. First hands-on case: test inbox “weekly summary + todo”

Goal: verify model, integration, memory, output, and revoke loop in one pass.

1. Create a test Gmail account; send yourself 2–3 emails with clear subjects (e.g. “Q2 budget discussion”, “Submit weekly report by Friday”).
2. In OpenHuman connect only that test inbox; complete OAuth.
3. Wait for first auto-fetch (≥20 minutes recommended); confirm vault / Memory has new content.
4. Ask: “Based on recent mail in my test inbox, produce a weekly summary and todo list, and cite which email each item came from.”
5. Verify: summary matches test mail; no invented topics; save exported output if the app supports it.
6. Revoke authorization on both OpenHuman and Google; confirm Disconnect stops the agent referencing that inbox.

Pass criteria: output matches test mail, sources are checkable, access stops after revoke. Check first on failure: isolate model layer (④) vs memory layer (⑥)—do not mix troubleshooting.

12. Common issues (layered troubleshooting)

13. Post-setup checklist: expand after the loop is stable

• Revoke test OAuth, then add real inbox/repo one integration at a time.
• Back up workspace, vault, and key settings screenshots; note model mode and approximate monthly cost.
• Read official Privacy & Security; review notification and voice toggles.
• Keep an uninstall path: know where data is stored so you do not delete the only memory library.

Seven-step runbook at a glance: prep → official install → login → model test → one low-risk integration → wait for memory → hands-on and revoke. Only then add Slack, Notion, and long-term workflows.