From a93c6c9bbf70616ba4c0428ea18197c1d16f0278 Mon Sep 17 00:00:00 2001 From: Mega Mind <146339422+M3gA-Mind@users.noreply.github.com> Date: Fri, 3 Jul 2026 23:48:55 +0530 Subject: [PATCH] docs(guides): task-oriented setup & recovery guides for non-technical users (#4257) (#4407) --- gitbooks/SUMMARY.md | 13 ++ gitbooks/guides/README.md | 59 +++++++++ gitbooks/guides/child-safe-companion.md | 98 ++++++++++++++ gitbooks/guides/connect-obsidian.md | 80 +++++++++++ gitbooks/guides/doctor-assistant.md | 93 +++++++++++++ gitbooks/guides/local-model.md | 108 +++++++++++++++ gitbooks/guides/move-to-new-pc.md | 121 +++++++++++++++++ gitbooks/guides/organize-project-folders.md | 86 ++++++++++++ gitbooks/guides/personal-assistant.md | 116 ++++++++++++++++ gitbooks/guides/privacy-sensitive-data.md | 97 ++++++++++++++ .../guides/recover-failed-installation.md | 124 ++++++++++++++++++ gitbooks/overview/getting-started.md | 4 + 12 files changed, 999 insertions(+) create mode 100644 gitbooks/guides/README.md create mode 100644 gitbooks/guides/child-safe-companion.md create mode 100644 gitbooks/guides/connect-obsidian.md create mode 100644 gitbooks/guides/doctor-assistant.md create mode 100644 gitbooks/guides/local-model.md create mode 100644 gitbooks/guides/move-to-new-pc.md create mode 100644 gitbooks/guides/organize-project-folders.md create mode 100644 gitbooks/guides/personal-assistant.md create mode 100644 gitbooks/guides/privacy-sensitive-data.md create mode 100644 gitbooks/guides/recover-failed-installation.md diff --git a/gitbooks/SUMMARY.md b/gitbooks/SUMMARY.md index aba74feb0..2482a12c9 100644 --- a/gitbooks/SUMMARY.md +++ b/gitbooks/SUMMARY.md @@ -6,6 +6,19 @@ * [Getting Started](overview/getting-started.md) * [Troubleshooting Sign-In](overview/troubleshooting-sign-in.md) +## Guides + +* [Guides](guides/README.md) + * [Create my personal AI assistant](guides/personal-assistant.md) + * [Use OpenHuman with a local model](guides/local-model.md) + * [Keep sensitive data private](guides/privacy-sensitive-data.md) + * [Recover from a failed installation](guides/recover-failed-installation.md) + * [Move OpenHuman to a new PC](guides/move-to-new-pc.md) + * [Connect OpenHuman to Obsidian](guides/connect-obsidian.md) + * [Organize my project folders](guides/organize-project-folders.md) + * [Create a doctor-specific assistant](guides/doctor-assistant.md) + * [Create a safe companion for a child](guides/child-safe-companion.md) + ## Features * [Realtime Mascot](features/mascot/README.md) diff --git a/gitbooks/guides/README.md b/gitbooks/guides/README.md new file mode 100644 index 000000000..592357bd2 --- /dev/null +++ b/gitbooks/guides/README.md @@ -0,0 +1,59 @@ +--- +description: >- + Outcome-driven, step-by-step guides for getting a real result out of + OpenHuman — set up an assistant, run a local model, protect sensitive data, + recover a broken install, or move to a new machine. +icon: list-check +--- + +# Guides + +The rest of the docs explain **how OpenHuman works**. This section is about **what you want to get done**. Each guide starts from a concrete outcome — "I want a private assistant", "my install is broken", "I'm moving to a new laptop" — and walks you to a working result without asking you to first understand the architecture. + +You do not need to read these in order, and you do not need to be technical. Pick the guide that matches your goal. + +*** + +## Pick your goal + +| I want to… | Guide | +| ---------- | ----- | +| Set up a personal assistant from scratch | [Create my personal AI assistant](personal-assistant.md) | +| Keep model inference on my own machine | [Use OpenHuman with a local model](local-model.md) | +| Understand what leaves my computer and what doesn't | [Keep sensitive data private](privacy-sensitive-data.md) | +| Fix an install that won't start or finish | [Recover from a failed installation](recover-failed-installation.md) | +| Move everything to a new computer | [Move OpenHuman to a new PC](move-to-new-pc.md) | +| Read and edit memory in Obsidian | [Connect OpenHuman to Obsidian](connect-obsidian.md) | +| Let the agent tidy a folder of files | [Organize my project folders](organize-project-folders.md) | +| Build a role-specific assistant (e.g. clinical) | [Create a doctor-specific assistant](doctor-assistant.md) | +| Set up a locked-down assistant for a child | [Create a safe companion for a child](child-safe-companion.md) | + +*** + +## How to read a guide + +Every guide in this section follows the same shape, so you always know where to look: + +* **Prerequisites** — what you need before you start (an account, disk space, another app installed). +* **Privacy implications** — what stays on your machine and what is sent to the OpenHuman backend or a model provider for this workflow, in plain language. +* **Steps** — the actual click-by-click path. +* **Success checks** — how to confirm the workflow is actually working, not just "looks done". +* **Common failures** — the specific ways this flow breaks, and what each symptom means. +* **Recovery** — how to get unstuck without losing your data. + +{% hint style="info" %} +**These guides describe the shipping desktop app.** OpenHuman is in active development; where a guide points at a Settings screen or diagnostic surface, that surface may keep improving. When a screen name and what you see disagree, trust the app and check the [release notes](https://github.com/tinyhumansai/openhuman/releases) — then let us know on [Discord](https://discord.tinyhumans.ai). +{% endhint %} + +## The one thing worth knowing first + +OpenHuman keeps **the memory of your life on your machine**. The managed backend still brokers sign-in, model routing, integration access, web-search proxying, and some real-time integration triggers. That single fact is behind most of the privacy and recovery advice in this section. If you read only one background page, read [Privacy & Security](../features/privacy-and-security.md). + +Where your data physically lives on disk: + +| Platform | Data folder | +| -------- | ----------- | +| macOS / Linux | `~/.openhuman/` | +| Windows | `%USERPROFILE%\.openhuman\` | + +Almost everything in this section — backups, recovery, migration — comes back to that one folder. diff --git a/gitbooks/guides/child-safe-companion.md b/gitbooks/guides/child-safe-companion.md new file mode 100644 index 000000000..34106d294 --- /dev/null +++ b/gitbooks/guides/child-safe-companion.md @@ -0,0 +1,98 @@ +--- +description: >- + Compose OpenHuman's autonomy, approval, and content-screening controls into a + locked-down assistant for a child — with an honest account of the limits. +icon: child +--- + +# Create a safe companion for a child + +**Goal:** set up the most restricted, supervised version of OpenHuman you can, intended for a child to use with an adult present. + +{% hint style="danger" %} +**Read this first — honestly.** OpenHuman has **no dedicated "child mode"**, no age verification, and no content filter on what the model *says*. There is no certified parental-control product here. What you *can* do is compose the existing safety controls into a tightly locked-down setup. That reduces risk; it does not make an AI assistant a safe, unsupervised experience for a child. **Adult supervision is the control that matters most.** Do not rely on software alone. +{% endhint %} + +This guide is about stacking the real controls that exist, and being clear about what they do and don't cover. + +*** + +## Prerequisites + +* OpenHuman set up on the machine the child will use — see [Create my personal AI assistant](personal-assistant.md). +* An adult who owns the account and stays involved. + +## Privacy implications + +* Keep it local. Use a [local model](local-model.md) so conversations aren't sent to a cloud provider, and connect **no** personal integrations. +* Do not connect a child's accounts. The safest memory is minimal memory. + +## What each control actually does + +| Control | What it protects against | What it does **not** do | +| ------- | ------------------------ | ----------------------- | +| **Read-only autonomy** | The assistant taking any action — sending, writing files, running commands, reaching the network on its own | Doesn't filter what it *says* | +| **Approval Gate (on)** | Any state-changing/network action slipping through without an adult's yes | Doesn't review conversation content | +| **Workspace-only + blocked system dirs** | The agent touching files outside a small folder, or any credential/system directory | Doesn't restrict what topics come up | +| **Prompt-injection screening** | Attempts (in pasted text) to hijack the assistant's instructions | Isn't a general content moderator | +| **No integrations connected** | The assistant pulling in or acting on personal data | — | + +The honest gap: **none of these filter the model's language or subject matter.** That gap is filled by an adult in the room and by persona instructions, not by a setting. + +*** + +## Steps + +### 1. Set the strictest autonomy tier + +**Settings → Agents → Agent access:** + +* Autonomy: **Read-only**. The assistant can talk and answer, but cannot act, write files, or reach the network on its own. +* Keep **workspace-only** on. +* Keep the [Approval Gate](../features/approval-gate.md) on. (With Read-only, acting is blocked outright anyway — leave the gate on as a second layer.) +* Review the **auto-approve** list and remove anything you don't want running without a prompt. + +### 2. Keep inference and data local + +* Turn on a [local model](local-model.md), then **route chat and reasoning at the local provider** so conversations run on-device. Enabling Local AI alone keeps only embeddings/memory local — chat still uses the default cloud route until you point the chat/reasoning workloads at the local provider and confirm with a test message. +* Connect **no** integrations. Don't sign the child's accounts in. + +### 3. Write a protective persona + +Edit the behavior prompt (`SOUL.md`, via the **Brain** page `/brain`) to set age-appropriate rules directly — for example: "You are talking with a child. Keep language simple and kind. Refuse and redirect anything violent, sexual, frightening, or unsafe. Never give instructions that could cause harm. Encourage them to ask a parent." Persona instructions are your main lever over *content*, since there's no built-in filter. + +### 4. Supervise, and test first + +* Sit with the child, at least at first. +* Before handing it over, **try to break it yourself**: ask it things a child might, and confirm the persona redirects appropriately. + +*** + +## Success checks + +* [ ] Autonomy is **Read-only**; workspace-only and the approval gate are on. +* [ ] No integrations are connected. +* [ ] Inference is local (`ready`) — conversations aren't going to a cloud provider. +* [ ] In your own testing, the persona refuses and redirects unsafe prompts. +* [ ] An adult is present for use. *(This is a check, not a nicety.)* + +## Common failures + +| Symptom | Cause | Fix | +| ------- | ----- | --- | +| It produced content you consider inappropriate | There is no content filter; the persona alone governs tone | Strengthen the `SOUL.md` rules; supervise; this is an inherent limit of the tool | +| It tried to do something (send/open/fetch) | Tier isn't Read-only | Set autonomy to **Read-only** in Agent access | +| Conversation went to the cloud | Local AI isn't on | Turn on a [local model](local-model.md) and confirm `ready` | +| The child reached settings and changed things | OpenHuman has no separate child login | Use OS-level user accounts/parental controls to lock down the machine itself | + +## Recovery + +* **Instant lockdown:** set autonomy to **Read-only** (if it drifted) — acting stops next turn. +* **Reset persona:** revert your `SOUL.md` edits to defaults if the customization misbehaves. +* **The real recovery is supervision.** If the experience isn't right for the child, step in — no software setting substitutes for that. + +## See also + +* [Keep sensitive data private](privacy-sensitive-data.md) — the controls this guide stacks. +* [Approval Gate](../features/approval-gate.md) — how actions are gated. +* [Privacy & Security](../features/privacy-and-security.md) — autonomy tiers and path hardening in depth. diff --git a/gitbooks/guides/connect-obsidian.md b/gitbooks/guides/connect-obsidian.md new file mode 100644 index 000000000..bf6f6018b --- /dev/null +++ b/gitbooks/guides/connect-obsidian.md @@ -0,0 +1,80 @@ +--- +description: >- + Open OpenHuman's memory as an Obsidian vault so you can read, edit, and link + the agent's notes by hand — and have it pick up your edits. +icon: book-open +--- + +# Connect OpenHuman to Obsidian + +**Goal:** browse and edit the assistant's memory as plain Markdown in [Obsidian](https://obsidian.md), and have your edits flow back into what the agent knows. + +OpenHuman's memory isn't a black box: the same chunks the agent reasons over are written as `.md` files in an Obsidian-compatible vault inside your workspace. See [Memory](../features/obsidian-wiki/) for the full picture; this guide just gets you connected. + +*** + +## Prerequisites + +* [Obsidian](https://obsidian.md) installed (free). +* OpenHuman set up with at least one source connected, so there's memory to look at — see [Create my personal AI assistant](personal-assistant.md). + +## Privacy implications + +* The vault is **local** — it lives in your workspace folder (`…/wiki/`) on your machine. Opening it in Obsidian doesn't upload anything. +* Obsidian reads local files directly; no OpenHuman account or backend is involved in browsing the vault. +* Anything you type into the vault becomes part of what the agent can read on its next ingest — treat it like writing into the assistant's memory. + +*** + +## Steps + +### 1. Open the vault from OpenHuman + +Go to the **Memory** tab and click **View vault in Obsidian**. This opens your `…/wiki/` folder as a vault in Obsidian. + +If you'd rather open it manually, point Obsidian at the `wiki/` folder inside your data folder: + +| Platform | Vault path | +| -------- | ---------- | +| macOS / Linux | `~/.openhuman/…/wiki/` | +| Windows | `%USERPROFILE%\.openhuman\…\wiki\` | + +### 2. Explore the structure + +Inside the vault you'll find auto-generated summaries organized by source, topic, and date, plus a place for your own free-form notes. Each summary file carries provenance in its frontmatter so you can trace a claim back to its source. See [Memory Tree](../features/obsidian-wiki/memory-tree.md). + +### 3. Add your own notes and links + +* Drop in your own Markdown notes. +* Build `[[wiki-links]]` between notes by hand. +* Correct or annotate anything the agent summarized. + +### 4. Let the agent pick up your edits + +Your changes are read on the next ingest — you don't have to import anything. The agent will see notes you added and links you drew. + +*** + +## Success checks + +* [ ] Obsidian opens the vault and shows OpenHuman's summary files. +* [ ] You can open a summary and see source/time provenance in its frontmatter. +* [ ] A note you add by hand is still there after OpenHuman runs (it isn't overwritten), and the agent can reference it in a later chat. + +## Common failures + +| Symptom | Cause | Fix | +| ------- | ----- | --- | +| Vault opens but is nearly empty | No sources ingested yet | Connect a source and wait an auto-fetch cycle (~20 min); see [personal assistant guide](personal-assistant.md) | +| "View vault in Obsidian" does nothing | Obsidian isn't installed, or the OS couldn't hand off the folder | Install Obsidian, then open the `wiki/` folder manually (paths above) | +| Your edits seem ignored | The next ingest hasn't run, or you edited inside an auto-managed summary block | Give it a cycle; put your own content in your own notes rather than inside generated blocks | + +## Recovery + +* The vault is just files. If Obsidian shows something odd, close it and reopen the folder — you can't break OpenHuman by browsing. +* If you deleted a note you wanted, the memory database still holds the underlying chunk; the summary can regenerate. + +## See also + +* [Memory](../features/obsidian-wiki/) — how the vault is produced and organized. +* [Keep sensitive data private](privacy-sensitive-data.md) — why the vault being local is the whole point. diff --git a/gitbooks/guides/doctor-assistant.md b/gitbooks/guides/doctor-assistant.md new file mode 100644 index 000000000..f5d87eb0f --- /dev/null +++ b/gitbooks/guides/doctor-assistant.md @@ -0,0 +1,93 @@ +--- +description: >- + Shape OpenHuman into a role-specific assistant for clinical work — persona, + tight data boundaries, and the limits you must keep in mind. +icon: user-doctor +--- + +# Create a doctor-specific assistant + +**Goal:** tailor OpenHuman for a clinician's workflow — a persona that speaks the part, memory scoped to the right sources, and privacy settings appropriate for sensitive information. + +{% hint style="danger" %} +**Read this first.** OpenHuman is a general-purpose assistant, **not** a medical device and **not** a source of medical advice. It can hallucinate. Nothing here makes it safe for diagnosis, treatment decisions, or handling protected health information under a specific regulatory regime (HIPAA, GDPR, etc.). You are responsible for compliance, for clinical judgment, and for what data you let it touch. Treat its output as draft text a qualified human must verify. +{% endhint %} + +With that boundary set, here's how to shape it responsibly. + +*** + +## Prerequisites + +* OpenHuman set up — see [Create my personal AI assistant](personal-assistant.md). +* A clear decision about **what data this assistant may and may not see**. For anything sensitive, plan to keep inference [local](local-model.md). + +## Privacy implications + +* Decide early whether any real patient data will ever be involved. If regulatory rules apply to your data, the safest posture is: **local model on, minimal integrations, read-only or supervised autonomy.** +* OpenHuman keeps memory local and redacts secrets/PII on save, but **that is not a compliance guarantee** — it's a general privacy design. Do not treat it as certified for regulated health data. +* If you route reasoning to the [OpenHuman backend](../features/privacy-and-security.md) (the default), relevant snippets are sent to the model provider for each turn. For sensitive material, turn on a [local model](local-model.md) so that work stays on-device. + +*** + +## Steps + +### 1. Lock down the boundaries before adding data + +In **Settings → Agents → Agent access**: + +* Set autonomy to **Read-only** (pure Q&A/drafting) or **Supervised** (drafting plus approved actions). Avoid **Full** for clinical use. +* Keep **workspace-only** on so the agent can't wander your disk. +* Keep the [Approval Gate](../features/approval-gate.md) on — nothing gets *acted on* (files written, actions taken) without your yes. Note it gates **actions**, not network transport: prompts and attachments can still be sent upstream for inference. + +### 2. Turn on local inference for sensitive work + +Follow [Use OpenHuman with a local model](local-model.md) and pick at least **"memory + reflection"** so embeddings and background summarization stay on-device. Confirm status reads `ready`. + +### 3. Give it a clinical persona + +The assistant's tone and behavior come from an editable prompt (`SOUL.md`), with mission/values in `IDENTITY.md`. To make it clinical: + +* Set a display name and description in **Settings → Personality**. +* Edit the behavior prompt (via the **Brain** page, `/brain`) to describe the role you want — e.g. "You assist a physician with documentation and literature summaries. You always flag uncertainty, cite sources, and never present output as a diagnosis or treatment recommendation. You remind the user to verify clinically." + +Bake the caveats **into the persona** so they show up in every reply, not just your memory. + +### 4. Connect only the sources that belong + +Add only the integrations relevant to the workflow (e.g. a reference/notes source), and **not** anything carrying data you're not cleared to process. Every integration is a separate, revocable OAuth grant. + +### 5. Verify behavior with safe, synthetic inputs + +Test with **made-up** cases, never real patient data, until you're satisfied with tone, caution, and citations. + +*** + +## Success checks + +* [ ] Autonomy is **Read-only** or **Supervised**, workspace-only is on, approval gate is on. +* [ ] Local AI is `ready` if you're keeping inference on-device. +* [ ] The persona reliably adds uncertainty flags and "verify clinically" language in replies to synthetic prompts. +* [ ] Only intended sources are connected. +* [ ] The assistant declines to present output as a diagnosis when tested. + +## Common failures + +| Symptom | Cause | Fix | +| ------- | ----- | --- | +| It states things with false confidence | Persona doesn't enforce caution | Strengthen `SOUL.md` to require uncertainty flags and citations | +| Sensitive text went to the cloud | Inference is on the default route | Turn on a [local model](local-model.md) and confirm `ready` before using sensitive input | +| It tried to take an action on its own | Tier too permissive | Drop to **Read-only**; keep the approval gate on | +| It "remembered" something it shouldn't have | A source with disallowed data was connected | Revoke the integration; already-ingested chunks are local and can be cleared from the workspace | + +## Recovery + +* **Instant containment:** set autonomy to **Read-only** — acting stops on the next turn. +* **Pull a source:** revoke any integration from Settings; future syncs stop immediately. +* **Reset the persona:** the behavior lives in an editable file; revert your edits to return to default tone. + +## See also + +* [Keep sensitive data private](privacy-sensitive-data.md) — the controls this guide composes. +* [Use OpenHuman with a local model](local-model.md) — keeping sensitive inference on-device. +* [Approval Gate](../features/approval-gate.md) — how actions are gated. diff --git a/gitbooks/guides/local-model.md b/gitbooks/guides/local-model.md new file mode 100644 index 000000000..8374641e3 --- /dev/null +++ b/gitbooks/guides/local-model.md @@ -0,0 +1,108 @@ +--- +description: >- + Run OpenHuman's inference on your own machine with Ollama — detection, model + selection, a real test, and every way it commonly breaks with the fix. +icon: microchip +--- + +# Use OpenHuman with a local model + +**Goal:** move some or all of OpenHuman's model work onto your own computer, so that data used for those workloads never leaves the machine. + +Local AI is **opt-in** and ships **off**. Turning it on doesn't silently reroute everything — you choose which workloads go local. + +For the config-level reference (every flag and provider field), see [Local AI (optional)](../features/model-routing/local-ai.md). This guide is the task-oriented version: get it running and confirm it works. + +*** + +## Prerequisites + +* [**Ollama**](https://ollama.com) installed. OpenHuman talks to it at its default address `http://localhost:11434`. (LM Studio is also supported at `http://localhost:1234/v1` — see the [reference page](../features/model-routing/local-ai.md#lm-studio-troubleshooting).) +* **8 GB+ RAM** to get real value. Machines with less than 8 GB fall back to cloud summarization by design — a small local model won't have the headroom. +* Disk for the weights: a small chat model plus an embedding model is a few GB. OpenHuman does not ship weights; Ollama pulls them on demand. + +## Privacy implications + +* Workloads you route locally (embeddings, summary building, background loops, and — if you choose — chat/reasoning) run **entirely on-device**. Nothing about that work is sent out. +* Anything you leave on the default route still goes through the OpenHuman [model router](../features/model-routing/). Local AI is additive; it doesn't change what you didn't move. +* If the local provider becomes unreachable mid-session, requests **transparently fall back** to the remote provider — so a crashed Ollama means that data may go to the cloud path instead. If strict locality matters, watch the diagnostics (below). + +*** + +## Steps + +### 1. Start Ollama + +Install and launch Ollama so its local server is running. You can confirm it's up from a terminal: + +```bash +curl http://localhost:11434/api/tags +``` + +A JSON list of models (even an empty one) means the server is reachable. This is the exact probe OpenHuman uses to detect Ollama. + +### 2. Turn on Local AI in OpenHuman + +Open **Settings → AI & Skills → Local AI**. It's off until you opt in here. Pick the **model tier** that matches your machine's memory (for example the `ram_2_4gb` tier on a typical laptop). OpenHuman selects sensible on-device models for you — for example `gemma3:1b-it-qat` for chat and `bge-m3` for embeddings. + +By default the tier keeps **embeddings and memory** on-device while chat and reasoning stay on the cloud route. To move those workloads local too, use **custom routing** to point the chat and reasoning workloads at the local provider, then test that a message stays on the machine. + +### 3. Let it pull the models + +When a workload needs a model that isn't installed yet, OpenHuman pulls it through Ollama and shows **download progress**. You can also pull manually: + +```bash +ollama pull gemma3:1b-it-qat +ollama pull bge-m3 +``` + +### 4. Test that it actually answers + +Don't assume — verify. The Local AI settings expose a **test action** that sends a short prompt to the configured local provider and shows you the reply. If you get a coherent response back, the path is live end-to-end (detection → model loaded → inference). + +*** + +## Success checks + +Local AI is operational when: + +* [ ] **Settings → AI & Skills → Local AI** shows Ollama as reachable and your selected models as available (not "downloading" or "missing"). +* [ ] The test action returns a real reply from the local model. +* [ ] The inference status reads **`ready`** (not `degraded`, `downloading`, or `disabled`). +* [ ] For an embeddings-only setup: after the next memory sync, new summaries keep appearing in the **Memory** tab with Ollama running — confirming embeddings are being produced locally. + +{% hint style="info" %} +**Where to look under the hood.** OpenHuman surfaces a live diagnostics view for the local runtime (Ollama reachable? runner OK? which models are installed vs expected? what issues?). If a check fails, the diagnostics name the specific problem — start there before changing config. +{% endhint %} + +## Common failures + +These are the actual failure states the runtime reports, and what each one means: + +| What you see | Meaning | Fix | +| ------------ | ------- | --- | +| **"Ollama server is not running or not reachable"** (status `degraded`) | The app can't reach Ollama at its base URL | Start Ollama; confirm `curl http://localhost:11434/api/tags` works; if you use a non-default port, set the base URL in Local AI settings | +| **"…reachable but cannot execute models. Restart the external runtime and retry."** | Ollama is answering but its model runner is broken (a fork/exec failure) | Quit and relaunch Ollama itself, then retry | +| **"Chat model '…' is not installed"** | The configured model isn't pulled yet | Let OpenHuman pull it, or run `ollama pull ` | +| **"…not reachable after fresh install. Start `ollama serve` manually and retry."** | Ollama was just installed but the server isn't up | Run `ollama serve` (or launch the Ollama app) and retry | +| Embedding model rejected for **context window too small** | The chosen embedding model can't hold enough tokens for the memory layer | Choose a larger-context embedding model such as **`bge-m3`** | +| Status stuck at **`downloading`**, then a retry message | A model pull stream was interrupted | It retries automatically; if it keeps failing, check disk space and network, then pull manually | +| It "works" but answers feel cloud-quality | The local provider was unreachable and OpenHuman **fell back to remote** | Fix reachability above; strict-local users should confirm status is `ready` before relying on it | + +## Recovery + +* **Back to cloud in one step:** turn Local AI back off in **Settings → AI & Skills → Local AI**. Workloads return to the default route immediately; no data is lost. +* **Free up a stuck runtime:** quit Ollama fully and relaunch it, then re-open the Local AI settings so OpenHuman re-probes. +* **Disk pressure:** interrupted pulls are usually low disk. Clear space and let the pull resume, or `ollama pull` the model by hand. + +*** + +## Notes on what stays cloud anyway + +Even with "everything local", some workloads are cloud by default unless you explicitly route them — speech-to-text, text-to-speech, and web search go through the backend proxy. See [what stays in the cloud](../features/model-routing/local-ai.md#what-stays-in-the-cloud-by-default). + +## See also + +* [Local AI (optional)](../features/model-routing/local-ai.md) — the full config reference. +* [Keep sensitive data private](privacy-sensitive-data.md) — the plain-language version of local vs external. +* [Automatic Model Routing](../features/model-routing/) — how tasks get matched to models. diff --git a/gitbooks/guides/move-to-new-pc.md b/gitbooks/guides/move-to-new-pc.md new file mode 100644 index 000000000..bf4c8f8d7 --- /dev/null +++ b/gitbooks/guides/move-to-new-pc.md @@ -0,0 +1,121 @@ +--- +description: >- + Carry your OpenHuman persona, memory, workspace, and model/provider config to + a new computer — and understand which secrets travel and which you re-enter. +icon: truck +--- + +# Move OpenHuman to a new PC + +**Goal:** set up OpenHuman on a new machine so it picks up where the old one left off — same memory, same persona, same settings — with credentials handled at a safe level of detail. + +The short version: **copy one folder, sign back in.** The nuance is in what a folder copy does and does not carry, which this guide makes explicit so you're not surprised. + +*** + +## Prerequisites + +* Both computers available (or a backup of the old one's data folder). +* Your OpenHuman sign-in credentials. +* A way to move files between them (external drive, secure file transfer, etc.). + +## What lives where + +Everything OpenHuman persists is in a single folder: + +| Platform | Data folder | +| -------- | ----------- | +| macOS / Linux | `~/.openhuman/` | +| Windows | `%USERPROFILE%\.openhuman\` | + +Inside it, the things you care about migrating: + +| What | Where (inside the data folder) | Travels with a folder copy? | +| ---- | ------------------------------ | --------------------------- | +| **Memory Tree** (the database) | `…/memory_tree/chunks.db` | ✅ Yes | +| **Obsidian vault** (readable memory) | `…/wiki/` | ✅ Yes | +| **Persona & behavior** | `SOUL.md`, `IDENTITY.md`, `HEARTBEAT.md` | ✅ Yes | +| **Config** (models, providers, routing, autonomy) | `config.toml` | ✅ Yes | +| **Session history** | `sessions/`, `session_raw/` | ✅ Yes | +| **Approval history** | `approval/approval.db` | ✅ Yes | +| **OS-stored secrets** (session token, some local keys) | Your OS keychain — **not** in this folder | ❌ No — re-established on sign-in | +| **Integration access** (Gmail, Slack, …) | Brokered by the backend, tied to your account | ❌ No — reconnects on sign-in | + +{% hint style="info" %} +**Why some things don't travel — and why that's fine.** OpenHuman deliberately keeps secrets out of loose files. Your session token and certain local secrets live in the operating system's secure store (Keychain / Credential Manager / Secret Service), and your integration tokens are held by the backend against your account. So the folder copy carries your *data and persona*; **signing in on the new machine re-establishes the secrets and integrations.** You never hand-copy raw tokens between machines. +{% endhint %} + +*** + +## Steps + +### 1. Quit OpenHuman on the old machine + +Fully close the app so nothing is mid-write to the database. A clean copy needs a quiet source. + +### 2. Copy the data folder + +Copy the **entire** data folder from the old machine to the same location on the new one: + +* macOS / Linux: copy `~/.openhuman/` → `~/.openhuman/` +* Windows: copy `%USERPROFILE%\.openhuman\` → `%USERPROFILE%\.openhuman\` + +Copy the whole folder rather than cherry-picking — it keeps memory, persona, config, and history consistent with each other. + +The data folder holds config and memory but **not** the files the agent created or edited in its action sandbox. Also copy your **projects/action folder** — by default `~/OpenHuman/projects` (or wherever you pointed the action directory) — or those project files stay behind on the old PC. + +{% hint style="warning" %} +Copy it somewhere secure. This folder contains your personal memory in readable form. Treat the transfer like moving personal documents. +{% endhint %} + +### 3. Install OpenHuman on the new machine + +Install the current build from [tinyhumans.ai/openhuman](https://tinyhumans.ai/openhuman). If the data folder is already in place, the app will find it on launch. (Order doesn't strictly matter — installing first and copying after works too, as long as the app isn't running while you copy.) + +### 4. Launch and sign in + +Open the app and sign in with the **same account**. Signing in: + +* Re-establishes your session token in the new machine's OS keychain. +* Reconnects your account so backend-brokered integrations come back. + +### 5. Reconnect anything account-scoped + +* **Integrations** (Gmail, Slack, etc.): confirm they show as connected under **Settings**. If any need a fresh OAuth approval, re-approve them — a quick click each. +* **Bring-your-own keys:** if you had entered your own provider API key, a Composio direct key, or similar **local** secrets, re-enter them on the new machine — those are stored in the OS keychain and don't come across in the folder. + +### 6. Re-check model / provider config + +Your `config.toml` came along, so model routing and provider choices should already match. If you used a [local model](local-model.md), remember that **Ollama/LM Studio is separate software** — install it on the new machine too, and let OpenHuman re-pull the model weights (they aren't in the data folder). + +*** + +## Success checks + +The migration worked when: + +* [ ] The **Memory** tab on the new machine shows your existing summaries — your memory came across. +* [ ] The assistant replies in your configured style, and your display name/persona is intact. +* [ ] Connected integrations show as connected under **Settings** (reconnect any that don't). +* [ ] Your autonomy tier and settings match what you had (check **Settings → Agents → Agent access**). +* [ ] If you use local AI: Ollama is installed on the new machine and Local AI reports `ready` after models re-pull. + +## Common failures + +| Symptom | Cause | Fix | +| ------- | ----- | --- | +| New machine starts fresh, no memory | Data folder wasn't in the right place, or app was running during the copy | Quit the app, place the folder at `~/.openhuman/` (or `%USERPROFILE%\.openhuman\`), relaunch | +| Signed in but integrations are disconnected | Integration access is account/backend-scoped, not in the folder | Reconnect each integration in Settings (one OAuth click each) | +| Local model doesn't work on the new PC | Ollama/LM Studio and the weights aren't on the new machine | Install the runtime and let models re-pull — see [local model guide](local-model.md) | +| Assistant lost its personality | `SOUL.md` / `IDENTITY.md` weren't copied | Copy the **whole** data folder, not just the database | +| Sign-in stalls on the new machine | An auth/handler issue unrelated to migration | See [Troubleshooting Sign-In](../overview/troubleshooting-sign-in.md) | + +## Recovery + +* **Keep the old machine's folder until you've verified the new one.** Don't wipe the source until every success check passes. +* If the new machine won't start at all, treat it as a fresh-install problem: [Recover from a failed installation](recover-failed-installation.md). Your copied folder is safe to move aside and restore. + +## See also + +* [Recover from a failed installation](recover-failed-installation.md) — same data folder, different problem. +* [Keep sensitive data private](privacy-sensitive-data.md) — why secrets are stored the way they are. diff --git a/gitbooks/guides/organize-project-folders.md b/gitbooks/guides/organize-project-folders.md new file mode 100644 index 000000000..a15844fbf --- /dev/null +++ b/gitbooks/guides/organize-project-folders.md @@ -0,0 +1,86 @@ +--- +description: >- + Let OpenHuman tidy, rename, and restructure a folder of files — safely, inside + a boundary you set, with every change gated by your approval. +icon: folder-tree +--- + +# Organize my project folders + +**Goal:** point the assistant at a folder and have it clean it up — sort files, rename consistently, remove clutter — without letting it roam your whole disk or make changes you didn't see. + +The core idea: the agent works inside a **boundary you define**, and any file change that isn't provably read-only is **parked for your approval** before it runs. + +*** + +## Prerequisites + +* OpenHuman set up — see [Create my personal AI assistant](personal-assistant.md). +* A specific folder you want organized. Ideally, make a copy first if the contents are irreplaceable. + +## Privacy implications + +* File organizing is **local** — reading, moving, and renaming files happens on your machine. +* If you ask the agent to *reason about* file contents (e.g. "group these by topic"), it may send relevant snippets to the model to do that. Route inference to a [local model](local-model.md) if you want that reasoning on-device too. +* The agent cannot touch system or credential folders (`~/.ssh`, `~/.gnupg`, `~/.aws`, OS directories) — those are blocked outright regardless of settings. + +*** + +## Steps + +### 1. Decide where the agent may act + +By default the agent's read/write root is its **projects** area (by default `~/OpenHuman/projects`), and it's confined there — it does **not** have ambient access to the rest of your disk. To let it work on a folder elsewhere, add that folder as a **trusted root**: + +* Open **Settings → Agents → Agent access**. +* Add the target folder as a trusted root with read-write access. + +Keep the boundary as tight as the task — grant the one folder, not your home directory. + +### 2. Set the right autonomy tier + +* **Supervised** *(recommended)* — the agent proposes each change and you approve moves/renames/deletes as they come. +* **Full** — routine file writes run automatically; still tighten the trusted root so "automatic" stays contained. + +Leave the [Approval Gate](../features/approval-gate.md) on. Deleting and moving files are state-changing actions, so they'll be parked for your yes/no. + +### 3. Ask for the reorganization + +Be concrete about the folder and the rules. For example: + +* "In my trusted `~/Documents/receipts` folder, rename every file to `YYYY-MM-DD-vendor.pdf` based on its contents, and move anything older than 2023 into an `archive/` subfolder." +* "Group the loose files in this folder into subfolders by type, and show me the plan before doing anything." + +### 4. Review each proposed action + +When the agent wants to move, rename, or delete, an **Approval Request card** appears with the exact action. **Approve** one, **Always allow** a repetitive safe one, or **Deny**. You can also just type **yes** / **no**. + +*** + +## Success checks + +* [ ] The agent only touched the folder you granted — nothing outside the trusted root changed. +* [ ] Each move/rename/delete showed up as an approval prompt (unless you chose "Always allow" for that tool). +* [ ] The folder matches the structure you asked for. +* [ ] Files you didn't mention are untouched. + +## Common failures + +| Symptom | Cause | Fix | +| ------- | ----- | --- | +| "I can't access that folder" | The folder isn't a trusted root, or `workspace_only` is confining the agent | Add it in **Settings → Agents → Agent access** as a read-write trusted root | +| It asks for approval on every single file | Supervised tier gates each write | Use **Always allow** for the specific safe tool, or narrow the request so there are fewer actions | +| It refuses to touch a path | The path is a blocked system/credential directory | That's by design — those are never accessible; choose a normal working folder | +| It reorganized more than you wanted | The instruction was broad | Ask it to "show the plan first"; approve selectively | + +## Recovery + +* **Nothing runs without approval** in Supervised tier — if a plan looks wrong, **Deny** and it doesn't happen. +* **Undo is manual.** OpenHuman doesn't roll file operations back for you, so work on a **copy** of anything precious, or keep the folder under version control (e.g. `git`) so you can revert. +* If the agent is doing too much, drop to **Read-only** in Agent access — it can still suggest a plan but can't change files. + +## See also + +* [Approval Gate](../features/approval-gate.md) — exactly what gets parked and why. +* [Coder toolset](../features/native-tools/coder.md) — the filesystem/git tools the agent uses here. +* [Privacy & Security](../features/privacy-and-security.md) — workspace scoping and path hardening. diff --git a/gitbooks/guides/personal-assistant.md b/gitbooks/guides/personal-assistant.md new file mode 100644 index 000000000..4c27141ce --- /dev/null +++ b/gitbooks/guides/personal-assistant.md @@ -0,0 +1,116 @@ +--- +description: >- + Go from a fresh install to a working personal assistant that knows your + context, respects your boundaries, and acts only with your approval. +icon: robot +--- + +# Create my personal AI assistant + +**Goal:** a working assistant that has some memory of your world, replies in a style you like, and never takes a real-world action without your say-so. + +This is the "start here" guide. It assumes nothing beyond a downloaded app. + +*** + +## Prerequisites + +* OpenHuman installed on macOS, Windows, or Linux. If you haven't installed yet, do [Getting Started](../overview/getting-started.md) first, then come back. +* 4 GB+ RAM (16 GB+ if you plan to connect very large mailboxes or run a [local model](local-model.md)). +* An account to sign in with (social login works). +* Optional: one account you'd like the assistant to know about (Gmail is the usual first one). + +## Privacy implications + +* Signing in **does not** grant ongoing access to anything. Every integration is a separate, explicit OAuth approval you can revoke later. +* Your memory (the local database and the Markdown vault) is created **on your machine**. Raw source data does not sit on the OpenHuman backend. +* By default, chat/reasoning runs through the OpenHuman-hosted [model router](../features/model-routing/). If you want inference on-device instead, see [Use OpenHuman with a local model](local-model.md). +* Full detail: [Keep sensitive data private](privacy-sensitive-data.md). + +*** + +## Steps + +### 1. Sign in + +Launch the app. The first screen is **"Sign in! Let's Cook"**. Choose a login option. There is an **Advanced** panel for pointing at a custom core — most people ignore it. + +### 2. Choose how AI runs + +After sign-in you'll hit a **runtime choice**: + +* **Cloud** — one click, and the hosted model router handles inference. This is the fastest path to a working assistant. +* **Custom** — walk through choosing your inference provider, voice, integrations (OAuth), web search, and embeddings yourself. + +If you're not sure, pick **Cloud**. You can change any of this later in **Settings**. + +### 3. Give it something to remember + +An assistant with no memory is just a chatbot. Connect at least one source so it has context to draw on: + +* Open **Settings** and connect an integration (Gmail is the common starting point). Each connection is a one-click OAuth approval. +* Once connected, [auto-fetch](../features/obsidian-wiki/auto-fetch.md) starts pulling data into your [Memory Tree](../features/obsidian-wiki/memory-tree.md) on a schedule (the first Gmail tick lands within about twenty minutes). + +### 4. Set your boundaries + +Open **Settings → Agents → Agent access**. This controls how much the assistant can do on its own: + +| Tier | What it means | +| ---- | ------------- | +| **Read-only** | The assistant can observe and answer, but never acts (no sending, no file writes, no commands). | +| **Supervised** *(default)* | It can act, but any state-changing, network, install, or destructive action is **parked for your approval** first. | +| **Full** | Routine actions run automatically; network/install/destructive actions still ask. | + +Leave it on **Supervised** unless you have a reason not to — nothing with an external effect will happen in a chat without you saying yes. This is the [Approval Gate](../features/approval-gate.md), and it's on by default. + +### 5. Shape its personality (optional) + +How the assistant talks and behaves is defined by an editable prompt called **`SOUL.md`** (its mission and values live in a companion **`IDENTITY.md`**). You don't have to touch these — they ship with sensible defaults — but you can: + +* Set a display name and short description in **Settings → Personality**. +* Edit the behavior itself via the **Brain** page (the raised center button in the bottom bar, `/brain`), where memory, goals, and intelligence live. + +OpenHuman also **learns** durable preferences from how you correct it over time — see [Personalization & Self-Learning](../features/personalization.md). + +### 6. Run your first real request + +Once a source has been ingested, try: + +* "What do I need to know from the last 12 hours?" +* "What's waiting on me?" +* "Summarize what I missed today." + +*** + +## Success checks + +You have a working assistant when **all** of these are true: + +* [ ] The app is signed in (you're past the welcome screen and in the chat/home view). +* [ ] At least one integration shows as **connected** in Settings. +* [ ] A briefing prompt ("what's waiting on me?") returns something drawn from your actual data, not a generic answer. +* [ ] Opening the **Memory** tab shows summaries appearing (give it one auto-fetch cycle — up to ~20 minutes — after connecting a source). +* [ ] When you ask it to do something with an external effect (e.g. "draft and send an email"), you see an **Approval Request card** appear above the chat box rather than it silently acting. + +## Common failures + +| Symptom | What it means | Fix | +| ------- | ------------- | --- | +| Sign-in returns to the welcome screen | The OAuth callback didn't reach the app | Follow [Troubleshooting Sign-In](../overview/troubleshooting-sign-in.md) | +| Connected a source but memory stays empty | First auto-fetch tick hasn't run yet, or the OAuth scope is too narrow | Wait one cycle (~20 min); re-check the connection in Settings | +| Assistant answers generically, ignores your data | It answered without recalling memory | Ask again and reference the source explicitly ("from my email…"); confirm the source is connected | +| It performed an action you didn't expect | Autonomy tier may be set to **Full** | Set **Settings → Agents → Agent access** back to **Supervised** | + +## Recovery + +* **Reset boundaries fast:** if the assistant is doing too much, drop the tier to **Read-only** in Agent access — it takes effect on the next turn and blocks all acting immediately. +* **Nothing you connect is permanent:** revoke any integration from Settings; chunks already in your local memory stay (they're yours), and the next sync tick stops pulling that source. +* **If the app itself won't start,** see [Recover from a failed installation](recover-failed-installation.md) — your configuration is preserved by default. + +*** + +## Next steps + +* [Use OpenHuman with a local model](local-model.md) — keep inference on-device. +* [Connect OpenHuman to Obsidian](connect-obsidian.md) — read and edit the memory by hand. +* [Keep sensitive data private](privacy-sensitive-data.md) — understand exactly what leaves your machine. diff --git a/gitbooks/guides/privacy-sensitive-data.md b/gitbooks/guides/privacy-sensitive-data.md new file mode 100644 index 000000000..8e3ae0f75 --- /dev/null +++ b/gitbooks/guides/privacy-sensitive-data.md @@ -0,0 +1,97 @@ +--- +description: >- + A plain-language map of what OpenHuman keeps on your computer versus what it + sends out, and the settings that let you keep sensitive work local. +icon: lock +--- + +# Keep sensitive data private + +**Goal:** understand — in everyday language, not architecture — what stays on your machine and what leaves it, so you can decide what OpenHuman should touch. + +If you want the engineering detail, read [Privacy & Security](../features/privacy-and-security.md). This guide is the version you can act on in five minutes. + +*** + +## The one-sentence version + +**Your memory lives on your computer. The OpenHuman backend only handles the things that genuinely have to be brokered — signing you in, routing model requests, and talking to the services you connect.** + +Everything below is an expansion of that sentence. + +*** + +## What stays on your machine + +These never leave your computer as raw data: + +| Thing | Plain meaning | +| ----- | ------------- | +| **Your Memory Tree** | The database of everything OpenHuman has learned about your world. It's a file on your disk. | +| **Your Obsidian vault** | The human-readable Markdown version of that memory. Yours to read, edit, or delete. | +| **Audio you speak** | Captured to transcribe, then discarded. | +| **Local model state** | If you turn on [local AI](local-model.md), the model and its work stay on-device. | +| **Your persona and settings** | The files that define how your assistant behaves and what it's allowed to do. | + +## What the backend handles (and why) + +These leave your machine because they can't work otherwise — but note *what* is sent: + +| Thing | What's actually sent | +| ----- | -------------------- | +| **Model requests** | Only what the assistant needs for that turn — your prompt plus the specific bits it pulled from your local memory. Not your whole memory, not background uploads. | +| **Web search** | Your search query goes to the backend proxy (so you don't need your own search key). | +| **Connected services** | When you connect Gmail, Slack, etc., the backend brokers each request. Your login tokens for those services are held by the backend, **not written in plain text on your laptop**. | +| **Text-to-speech** | The words to be spoken are streamed to generate audio, then discarded — not retained. | + +{% hint style="info" %} +**Why local memory *is* the privacy design.** Most assistants trade privacy for context — more context means more of your raw data uploaded. OpenHuman does the heavy work (chunking, scoring, summarizing) inside the local core, so the model only ever sees what you asked it to retrieve, at the moment you ask. Locality is the privacy feature, not a setting bolted on top. +{% endhint %} + +## Two promises worth knowing + +* **No training on your data.** Your conversations, memory, and personal information are never used to train models. +* **Secrets are stored by your operating system.** Local secrets are kept in your platform's secure store — macOS Keychain, Windows Credential Manager, or the Linux Secret Service — not lying around in app files. See [OS Keyring & Secret Storage](../features/os-keyring-and-secret-storage.md). + +*** + +## Turning the dial toward "more local" + +You have real controls. From most to least private: + +1. **Route inference on-device.** Turn on [local AI with Ollama](local-model.md) so embeddings, summarization, and optionally chat/reasoning happen on your machine. *(Speech and web search still use the backend proxy even then.)* +2. **Tighten what the assistant can do.** In **Settings → Agents → Agent access**, set the autonomy tier. **Read-only** means it can observe and answer but never act or reach the network on its own. See the [Approval Gate](../features/approval-gate.md). +3. **Keep it in one folder.** By default the agent is confined to your workspace and cannot read the rest of your disk (`workspace_only` is on). System and credential folders (`~/.ssh`, `~/.gnupg`, `~/.aws`, and OS directories) are blocked outright, regardless of settings. +4. **Connect only what you need.** Every integration is a separate OAuth approval you grant — and can revoke — individually. Revoking stops the next sync; memory already collected stays local because it's yours. + +## Built-in protections you didn't have to configure + +* **Prompt-injection screening.** Incoming content is screened for attempts to hijack the assistant's instructions before it acts on them. +* **Secret & PII redaction on save.** When content is written into long-lived memory, OpenHuman strips things like API keys, tokens, private-key blocks, and personal identifiers so they don't get stored. +* **Encrypted in transit.** All traffic between the app and the backend is TLS. Nothing travels in plain text. + +*** + +## Success checks + +You know your privacy posture when you can answer these: + +* [ ] Do you know your autonomy tier? (Check **Settings → Agents → Agent access**.) +* [ ] Do you know which integrations are connected? (Check **Settings**; disconnect any you don't need.) +* [ ] If locality matters for a workload, is [local AI](local-model.md) on and reporting `ready`? +* [ ] Are you comfortable that model turns send *retrieved snippets*, not your whole memory? + +## Common misunderstandings + +| Belief | Reality | +| ------ | ------- | +| "OpenHuman uploads my whole memory to answer." | It sends only what it retrieves for that specific turn. | +| "My service passwords are on my laptop." | Integration tokens are held by the backend; local secrets go in your OS keychain. | +| "Turning on local AI makes *everything* local." | Speech-to-text, text-to-speech, and web search still use the backend proxy by default. | +| "Revoking an integration deletes what it already gathered." | Already-ingested memory is yours and stays local; revoking only stops future syncing. | + +## See also + +* [Privacy & Security](../features/privacy-and-security.md) — the detailed architecture. +* [Use OpenHuman with a local model](local-model.md) — keep inference on-device. +* [Create a safe companion for a child](child-safe-companion.md) — the strictest lockdown, composed from these controls. diff --git a/gitbooks/guides/recover-failed-installation.md b/gitbooks/guides/recover-failed-installation.md new file mode 100644 index 000000000..080784a72 --- /dev/null +++ b/gitbooks/guides/recover-failed-installation.md @@ -0,0 +1,124 @@ +--- +description: >- + Get a broken or half-installed OpenHuman running again without losing your + memory, personas, or settings — configuration is preserved by default. +icon: life-ring +--- + +# Recover from a failed installation + +**Goal:** the app won't install, won't start, or starts broken — and you want it working again **without wiping your data**. + +The guiding rule of this guide: **your configuration and memory are preserved by default.** Recovery means fixing the runtime around your data, not deleting the data. We only touch your data folder as an explicit, backed-up last resort. + +*** + +## Prerequisites + +* Nothing special — you can do all of this from the app plus a file manager and, occasionally, a terminal. +* Know where your data lives. **Everything OpenHuman persists is in one folder:** + + | Platform | Data folder | + | -------- | ----------- | + | macOS / Linux | `~/.openhuman/` | + | Windows | `%USERPROFILE%\.openhuman\` | + + Leave that folder alone unless a step here explicitly says to touch it. + +## Privacy implications + +* Recovery is local. You're restarting or reinstalling software; your memory never gets uploaded as part of this. +* If you file a bug report, **redact secrets** — attach status codes, app version, OS, and log lines, never tokens or JWTs. + +*** + +## First: read the logs + +Almost every failure names itself in the log. Get to the logs first — it turns guessing into fixing. + +* **In the app (if it opens):** **Settings → About → App Logs Folder**. There's a button to reveal the folder in your file manager. +* **On disk:** logs are under your data folder, e.g. `~/.openhuman/logs/openhuman..log` (Windows: `%USERPROFILE%\.openhuman\logs\openhuman.*.log`). They rotate daily. + +Open the most recent log and read the last error lines. Match the message to the tables below. + +*** + +## Recovery ladder + +Work top to bottom. **Stop as soon as it works** — each rung is more disruptive than the last, and the early rungs never touch your data. + +### Rung 1 — Restart cleanly + +* Fully quit OpenHuman (make sure no leftover process is running) and reopen it. +* Only **one** instance should run at a time. A second copy can hold a lock the first one needs. + +### Rung 2 — Reinstall the app over your data + +Reinstalling the **application** does not delete your **data folder** — they're separate. This fixes a corrupted or partial install while preserving everything. + +* Download the current build from [tinyhumans.ai/openhuman](https://tinyhumans.ai/openhuman) and install over the top. +* On macOS, install the real `.app` bundle (some features need the bundle, not a dev build). +* Reopen. Your memory, personas, and settings are still there because they live in `~/.openhuman/`, which you didn't touch. + +### Rung 3 — Fix the specific error + +Match your symptom: + +| Symptom in logs / UI | Cause | Fix | +| -------------------- | ----- | --- | +| Sign-in stalls after the provider step; log mentions `openhuman://` scheme **not registered** (Windows) | The URL handler didn't register, or the install was moved after first launch | Follow the repair steps in [Troubleshooting Sign-In](../overview/troubleshooting-sign-in.md#windows-openhuman-handler-not-registered) | +| App won't render / crashes on launch citing a **CEF / cache lock** (`SingletonLock`, cache "held by another instance") | A previous instance's browser cache is still locked | Ensure no other OpenHuman is running; if it persists, close all instances and relaunch | +| Local AI / Ollama errors on startup | The local model runtime isn't reachable | This does **not** block the app — see [Use OpenHuman with a local model](local-model.md#common-failures) | +| "Low disk space" warning, or writes failing | The workspace can't be written | Free up space (the app wants a healthy margin — a few hundred MB minimum) and restart | + +### Rung 4 — Move the data folder aside (non-destructive reset) + +If the app still won't start and you suspect the **data folder** itself is the problem, **rename** it rather than delete it. This gives you a clean start while keeping a full backup you can restore from. + +{% hint style="warning" %} +Quit OpenHuman completely before moving its folder. +{% endhint %} + +```bash +# macOS / Linux +mv ~/.openhuman ~/.openhuman.backup-$(date +%Y%m%d) +``` + +```powershell +# Windows (PowerShell) +Rename-Item "$env:USERPROFILE\.openhuman" ".openhuman.backup" +``` + +Relaunch. OpenHuman recreates a fresh data folder and you sign in again. + +* If the fresh start **works**, the old folder was the issue — but your data is safe in the backup. You can copy specific pieces back (your memory database and vault) and test after each. +* If it **still fails**, the data folder wasn't the cause. **Restore your backup** by renaming it back, so you lose nothing, and escalate (below). + +*** + +## Success checks + +You've recovered when: + +* [ ] The app launches to the sign-in or chat screen without crashing. +* [ ] You can sign in and reach your home/chat view. +* [ ] Your **Memory** tab still shows your existing summaries (confirming your data survived). +* [ ] The most recent log file shows a clean startup with no repeating error. + +## What "preserved by default" means here + +At no point in Rungs 1–3 do you delete anything. Rung 4 **renames** — never removes — your data folder, so even the most aggressive step is fully reversible. Reinstalling the app and reinstalling the OS-level runtime never target your `~/.openhuman/` data. + +## If you're still stuck + +Gather this and open an issue on [GitHub](https://github.com/tinyhumansai/openhuman) or ask on [Discord](https://discord.tinyhumans.ai): + +* App version and OS. +* The last error lines from the log (**tokens/JWTs redacted**). +* Which rung you reached and what happened. +* Whether moving the data folder aside changed anything. + +## See also + +* [Troubleshooting Sign-In](../overview/troubleshooting-sign-in.md) — the deep dive for auth-specific failures. +* [Move OpenHuman to a new PC](move-to-new-pc.md) — the same data folder is what you carry over. diff --git a/gitbooks/overview/getting-started.md b/gitbooks/overview/getting-started.md index e1517b5cf..7887426fb 100644 --- a/gitbooks/overview/getting-started.md +++ b/gitbooks/overview/getting-started.md @@ -11,6 +11,10 @@ This page walks you through installing OpenHuman, going through the in-app onboa OpenHuman is open source under the GNU GPL3 license. The codebase is at [github.com/tinyhumansai/openhuman](https://github.com/tinyhumansai/openhuman). +{% hint style="info" %} +**Want a specific outcome?** If you're here to accomplish something concrete — set up a private assistant, run a local model, recover a broken install, or move to a new machine — the [Guides](../guides/README.md) section has task-by-task walkthroughs. +{% endhint %} + *** ## System requirements