openhuman Documentation

Your Personal AI super intelligence. A brain that builds a local-first memory of your life, a fantastic orchestrator of agent fleets and workflows, and a...

36,249 stars Rust Rust 1 file · ~4,086 tokens
RAW Doc

Docker & Self-Hosted Deployment Verified OCI

Deploy openhuman on any server, homelab, or cloud container platform.

1-Click Terminal Command
bash (docker run) 
docker run -d --name openhuman -p 7788:7788 --restart always openhuman-core:local
Configured Services & Ports
⚙️ openhuman-core
image: openhuman-core:local
🔌 Ports: ${OPENHUMAN_CORE_PORT:-7788}:7788
docker-compose.yml
yaml (docker-compose.yml) 
# OpenHuman Core — Docker Compose for self-hosted cloud deploy.
#
# Brings up the headless Rust core (`openhuman-core`) on :7788, persists the
# workspace to a named volume, and reads secrets/config from a `.env` file
# next to this compose file.
#
# Usage:
#   1. cp .env.example .env  (then edit values — at minimum BACKEND_URL and
#      OPENHUMAN_CORE_TOKEN; the latter is required for any client that calls
#      /rpc on this instance)
#   2. docker compose up -d
#   3. curl http://localhost:7788/health
#
# The image is built from the repo Dockerfile. To pin a published image
# instead of building, replace `build:` with `image: ghcr.io/.../openhuman-core:`.

services:
  openhuman-core:
    build:
      context: .
      dockerfile: Dockerfile
    image: openhuman-core:local
    container_name: openhuman-core
    restart: unless-stopped
    read_only: true
    security_opt:
      - no-new-privileges:true
    cap_drop:
      - ALL
    # The entrypoint starts as root so it can repair the ownership of a volume
    # Docker created as root:root, then drops to the `openhuman` user. Both
    # steps need capabilities that `cap_drop: ALL` removes:
    #   CHOWN  — heal mis-owned workspace files (scripts/docker-entrypoint-core.sh)
    #   SETUID/SETGID — gosu's privilege drop; without them the container
    #                   crash-loops before openhuman-core ever starts.
    # Deny-by-default is preserved: these three are the entire grant.
    # Alternative if you prefer zero capabilities: pin `user: "10001:10001"`,
    # which makes the entrypoint exec the binary directly and skip the heal —
    # at the cost of no longer being able to repair a root-owned volume.
    cap_add:
      - CHOWN
      - SETUID
      - SETGID
    tmpfs:
      - /tmp
    ports:
      - "${OPENHUMAN_CORE_PORT:-7788}:7788"
    env_file:
      - path: .env
        required: false
    environment:
      # Bind to 0.0.0.0 inside the container so port-forwarding works regardless
      # of what `.env` says. The Dockerfile already sets this default, but make
      # it explicit so an inherited shell value cannot override it.
      OPENHUMAN_CORE_HOST: 0.0.0.0
      OPENHUMAN_CORE_PORT: "7788"
      OPENHUMAN_WORKSPACE: /home/openhuman/.openhuman
      XDG_CACHE_HOME: /home/openhuman/.openhuman/cache
      TMPDIR: /tmp
      RUST_LOG: ${RUST_LOG:-info}
    volumes:
      - openhuman-workspace:/home/openhuman/.openhuman
      # The agent's default projects/action directory lives outside the
      # workspace (~/OpenHuman). With `read_only: true` the core cannot create
      # it and logs "could not create default projects dir ... Read-only file
      # system" at every start; file tools then have nowhere to write.
      - openhuman-projects:/home/openhuman/OpenHuman
    mem_limit: ${OPENHUMAN_CORE_MEM_LIMIT:-4g}
    cpus: ${OPENHUMAN_CORE_CPUS:-2.0}
    healthcheck:
      test: ["CMD", "curl", "-fsS", "http://localhost:7788/health"]
      interval: 30s
      timeout: 5s
      start_period: 15s
      retries: 3

volumes:
  openhuman-workspace:
    name: openhuman-workspace
  openhuman-projects:
    name: openhuman-projects

File: README.md

OpenHuman

Early Beta: Under active development. Expect rough edges.

OpenHuman is not AGI. But it is a meaningful architectural step closer, with better memory, better orchestration, and better tooling.

🎉 Within one week of launch, OpenHuman became the number one trending repository on GitHub for nine days in a row.

Install

Download installers from tinyhumans.ai/openhuman or from the GitHub Releases page.

For terminal installs (Homebrew, Debian/Ubuntu .deb, AUR, install scripts, and platform notes), see INSTALL.md.

What is OpenHuman?

OpenHuman is three things most assistants aren't: a brain that builds a persistent, local memory of your world; a fantastic orchestrator that runs fleets of agents on durable graphs; and a deep researcher that sweeps your data and the web before you finish asking. Every bullet links to the deeper writeup in the docs.

🧠 The brain

  • Memory Tree + Obsidian Wiki: your data compressed into scored Markdown trees in SQLite on your machine, mirrored as an Obsidian vault you can open and edit. No vector-soup black box.
  • 100+ OAuth integrations, 5,000+ MCP servers, 90,000+ Skills: one click into Gmail, Notion, GitHub, Slack and the rest of your stack. Auto-fetch feeds the brain every 20 minutes, so it has tomorrow's context this morning.
  • A subconscious: a background loop that diffs your world, advances your goals, and writes your morning briefing. Thinking continues after you stop typing.
  • Goals & Todos: long-term goals, durable per-thread goals, and a shared kanban board per conversation.
  • TokenJuice: tool output compressed before it hits the model: same information, up to 80% fewer tokens. A brain this big would be unaffordable without it.

🕸️ The orchestrator

  • Workflows: the agent proposes the automation; you review it on a canvas and save. Durable, trigger-driven, approval-gated runs on open-source tinyflows.
  • A harness that finishes the job: checkpointed graph runs on open-source tinyagents. Stuck agents get steered, halted ones return a root cause, and every run replays with real per-call costs.
  • A split brain, always on: a fast reflex agent triages inbound traffic while a deep reasoning core delegates to worker fleets, steered by the subconscious.
  • An agent economy: a @handle on tiny.place, Signal-encrypted agent-to-agent orchestration, x402 USDC bounties and trading. Keys never touch disk.

🔬 The deep researcher & doer

  • SuperContext: a research scout sweeps your memory and files before the model reads your first message. No cold starts.
  • Batteries included: managed web search, powered by Exa, is included with your OpenHuman subscription and needs no API key; bring your own Exa key to search directly on your own Exa account and billing. Plus scraper, coder toolset, a real browser, and native voice with in-process Whisper. Model routing picks the right LLM per workload on one subscription. That subscription is a default, not a lock-in: point any workload at your own provider key or a fully local Ollama model, and mix the three however you like.
  • Meeting agents: joins Meet, Zoom, Teams, and Webex with a face and a voice. It auto-joins from your calendar, streams a live transcript, answers by name, and files a summary with action items.
  • Image & video generation: Seedream/SeedEdit images and Seedance/Veo video, straight into your workspace on the same subscription.
  • 17 messaging channels: Telegram, Discord, Slack, WhatsApp, Signal, iMessage… plus native email (IMAP IDLE + SMTP). Your agent reaches you where you already are.

🧍 Human, private, yours

  • Simple, UI-first & Human: install to working agent in a few clicks, with no config files and no terminal. And it has a face: a mascot that speaks, reacts, and remembers you.
  • Privacy & security: on-device encrypted data, approval gate, OS-keyring secrets, and opt-in sandboxing. There is also Privacy Mode: flip one switch and no inference leaves your machine, enforced in the Rust core.
  • Themes & Theme Studio: five theme families plus a full visual editor, exportable as JSON.

Context in minutes, not weeks

OpenHuman is the first agent harness that gets to know you in minutes. Inspired by Karpathy's LLM Knowledgebase. Most agents start cold. Hermes learns by watching you work; OpenClaw waits for plugins to ferry context in. Either way, you spend days or weeks before the agent knows enough about your stack to be genuinely useful.

OpenHuman summarizes and compresses all your documents, emails & chats; and creates a memory graph that lets your agent remember everything about you.

OpenHuman skips the wait. Connect your accounts, let auto-fetch pull data locally on a 20-minute loop, and then have Memory Trees compress everything into Markdown files stored intelligently in a Karpathy-style Obsidian wiki.

In just one sync pass, the agent has full (compressed) context of your inbox, your calendar, your repos, your docs, your messages. No training period. No "give it a few weeks.". It becomes you, controlled by you.

Already self-host agentmemory across other coding agents? OpenHuman ships an optional Memory backend that proxies to it. Set memory.backend = "agentmemory" in config.toml and the same durable store powers OpenHuman alongside Claude Code, Cursor, Codex, and OpenCode. See the agentmemory backend page for setup.

An orchestrator, not a chatbot

Most agent harnesses run one agent in one loop. OpenHuman is an orchestrator:

Agent-to-agent messaging runs over Signal-protocol end-to-end encryption, so you can connect anything (Claude Code, Codex, OpenClaw, Hermes) and use OpenHuman to orchestrate all of your agents and tools.

  • Graphs, not loops: turns run as checkpointed graphs on tinyagents. They pause for a human, survive a restart, and resume mid-run.
  • Sub-agent fleets: specialists spawn three levels deep; stuck agents become root-cause reports.
  • Agent-to-agent, encrypted: instances orchestrate each other over Signal-protocol E2E sessions with x402 payments. No server ever sees plaintext.

Workflows you can see

Heavily inspired by n8n and Zapier, workflows bring the same visual, trigger-driven automation to your agent, except the agent builds them for you. Ask for an automation and it proposes one: a tinyflows graph you review on a visual canvas before saving.

The agent proposes the workflow; you review it on a canvas and save it.

Saved workflows are durable and trigger-driven. They fire on schedules, webhooks, or channel events, survive restarts, and gate side effects behind approvals.

OpenHuman vs Other Agent Harnesses

High-level comparison (products evolve, so verify against each vendor). OpenHuman is built to minimize vendor sprawl, keep workflow knowledge on-device, and give the agent a persistent memory of your data, not only chat.

Claude Cowork OpenClaw Hermes Agent OpenHuman
Open-source 🚫 Proprietary ✅ MIT ✅ MIT ✅ GNU
Simple to start ✅ Desktop + CLI ⚠️ Terminal-first ⚠️ Terminal-first ✅ Clean UI, minutes
Cost ⚠️ Sub + add-ons ⚠️ BYO models ⚠️ BYO models ✅ One sub + TokenJuice
Memory ✅ Chat-scoped ⚠️ Plugin-reliant ✅ Self-learning 🚀 Memory Tree + Obsidian vault, optional agentmemory backend
Integrations ⚠️ Few connectors ⚠️ BYO ⚠️ BYO 🚀 100+ OAuth · 5k+ MCP · 90k+ Skills
Auto-fetch 🚫 None 🚫 None 🚫 None ✅ 20-min sync into memory
Orchestration ⚠️ Sub-tasks ⚠️ Single loop ⚠️ Single loop 🚀 Agent graphs + checkpoints + E2E-encrypted A2A
Workflows 🚫 None ⚠️ Scripts ⚠️ Scripts 🚀 Visual, durable, agent-proposed, approval-gated
Meetings 🚫 None 🚫 None 🚫 None 🚀 Joins Meet/Zoom/Teams/Webex, speaks, live transcript
Messaging channels 🚫 None ⚠️ A few ⚠️ A few ✅ 17 incl. native email (IMAP/SMTP)
Local-only mode 🚫 Cloud-only ⚠️ BYO local ⚠️ BYO local ✅ One-switch enforced Privacy Mode
Observability 🚫 Opaque ⚠️ Logs ⚠️ Logs ✅ Replayable run journals + per-call cost accounting
API sprawl 🚫 Extra keys 🚫 BYOK 🚫 Multi-vendor ✅ One account
Model routing 🚫 Single model ⚠️ Manual ⚠️ Manual ✅ Built-in
Native tools ✅ Code-only ✅ Code-only ✅ Code-only ✅ Code + search + scraper + browser + voice + media gen

Contributing from source

New contributor? Start with CONTRIBUTING.md for the fork/PR workflow and local validation commands, or use the copy-paste AI-agent prompt in CONTRIBUTING-BEGINNERS.md. The short path is:

  1. Install Git, Node.js 24+, pnpm 10.10.0, Rust 1.93.0 (rustfmt + clippy), CMake, Ninja, ripgrep, and the platform desktop build prerequisites.
  2. Fork and clone the repo, then run git submodule update --init --recursive before pnpm install so the vendored Tauri/CEF sources are present.
  3. Use pnpm dev for web-only UI work, pnpm --filter openhuman-app dev:app for the desktop shell, and focused checks such as pnpm typecheck, pnpm format:check, and cargo check -p openhuman --lib before opening a PR.

Deeper docs: Architecture · Getting Set Up · Cloud Deploy.

Star us on GitHub

Building toward AGI and artificial consciousness? Star the repo and help others find the path.

Contributors Hall of Fame

Show some love and end up in the hall of fame. Contributors get free merch and special access to our Discord.

File: app/src/providers/README.md

App Providers

This directory contains the React context providers that manage the global state and services of the application.

CoreStateProvider

Manages the authoritative global state of the application, including user authentication, session tokens, and the application snapshot.

Turn-Boundary Refetch Contract

To ensure that the UI stays in sync with the backend state (especially during onboarding and context gathering), the application follows a refetch-on-turn-end contract:

  • Refetch Timing: After every agent reply completes (the chat_done event in ChatRuntimeProvider), the application refetches the authoritative user state via userApi.getMe().
  • Debounce: Multiple rapid turn-finalized events within 750ms are collapsed into a single refetch call to avoid unnecessary network traffic.
  • Single Source of Truth: The refetched state is merged into the global snapshot using patchSnapshot. Components should bind to this global snapshot to ensure they reflect the latest backend state without requiring a full remount.
  • Fire-and-Forget: The refetch operation is non-blocking and fires on a microtask after the chat UI has painted the final response.

ChatRuntimeProvider

Manages the live chat state, including message streaming, tool execution timeline, and subagent orchestration. It subscribes to socket events and updates the Redux store.

SocketProvider

Manages the Socket.IO connection to the Rust core, providing the underlying transport for real-time chat events.

File: app/README.md

Tauri + React + Typescript

This template should help get you started developing with Tauri, React and Typescript in Vite.

Explore Related Technologies & Topics

View All 9,111+ Repositories →

Discover similar high-velocity repositories, agent skills, and OpenAPI specifications across the ecosystem.

⚡ MCP Servers Model Context Protocol → 🧠 Agent Skills Prompt & rule files → 🔌 OpenAPI Specs REST & Swagger schemas →