OpenHuman

Build AI coworkers that work alongside your team.

OpenHuman lets teams create AI coworkers that work alongside them, gather context from company knowledge, generate memory over time, and handle the grunt work that slows teams down. Each coworker can be scoped to a role, trained on relevant documents and conversations, backed by long-term memory through supermemory, and connected to MCP tools so it can take action across the systems your team already uses.

Architecture

What You Can Build

• A support engineer that has read every past ticket, runbook, and postmortem, then recalls how similar incidents were resolved.
• An onboarding buddy that knows the employee handbook, team norms, and role-specific context for new hires.
• A product expert trained on specs, research notes, customer calls, and decision history.
• A community moderator that applies your guidelines consistently across active channels.
• A compliance assistant that understands policies, audit findings, and regulatory requirements.
• Tool-using AI coworkers that connect to calendars, CRMs, issue trackers, databases, and internal APIs through MCP, then do the follow-through work instead of only giving advice.

How It Works

1. Define an AI coworker and its area of expertise.
2. Add company knowledge such as documents, policies, conversations, notes, and past decisions.
3. OpenHuman stores and retrieves long-term memory through supermemory.
4. The agent uses that memory, its role definition, and connected MCP tools to answer questions, update systems, run workflows, and complete repetitive tasks.
5. Coworkers can participate through the web dashboard and team channels such as Slack and Discord.

OpenHuman is designed around memory, not one-off chat context. Coworkers can remember prior questions, resolved issues, organizational relationships, and decisions made over time.

Features

• AI coworker creation and management
• Organization setup and dashboard flows
• Document and memory-source ingestion
• supermemory-backed long-term memory
• MCP tool connections for taking action across external systems
• FastAPI backend with PostgreSQL persistence
• Next.js dashboard frontend
• Generated TypeScript API client
• Slack OAuth and gateway support
• Discord gateway support
• MCP marketplace and OAuth credential support
• Activity logs and operational visibility
• Docker Compose setup for local full-stack development

Repository Structure

.
├── apps
│   ├── api              # FastAPI backend, workers, gateways, database models
│   └── web              # Next.js dashboard
├── packages
│   └── api-client       # Generated TypeScript client from the OpenAPI spec
├── supermemory          # Local supermemory container build context
├── docker-compose.yml   # Postgres, supermemory, backend, and web services
├── package.json         # Bun workspaces and Turborepo scripts
└── turbo.json           # Monorepo task pipeline

Tech Stack

• Frontend: Next.js, React, TypeScript, Tailwind CSS, shadcn-style components
• Backend: FastAPI, SQLAlchemy, Alembic, Pydantic
• Database: PostgreSQL
• Memory: supermemory
• Agent runtime: LangGraph, LangChain, MCP adapters
• Package manager: Bun
• Monorepo orchestration: Turborepo
• Python tooling: uv

Getting Started

Prerequisites

• Docker and Docker Compose
• Bun 1.3.10 or newer
• Python 3.12 and uv, if running the API outside Docker

1. Clone and Install

git clone https://github.com/icyzh/openhuman.git
cd openhuman
bun install

2. Configure Environment

Create a .env file in the repository root. If an .env.example file is available in your checkout, copy it first; otherwise create .env manually and start with:

DATABASE_URL=postgresql+asyncpg://postgres:postgres@localhost:5432/openhuman
FRONTEND_URL=http://localhost:3000
SUPERMEMORY_URL=http://localhost:6767
OPENAI_API_KEY=
OPENAI_BASE_URL=
OPENAI_MODEL=gpt-4o-mini
JWT_SECRET_KEY=change-me-in-development
ENCRYPTION_KEY=
GATEWAY_ENABLED=false

For production, set a strong JWT_SECRET_KEY and a 64-character hex ENCRYPTION_KEY.

3. Run the Full Stack with Docker

docker compose up --build

Services:

• Web dashboard: http://localhost:3000
• API: http://localhost:8000
• API readiness: http://localhost:8000/ready
• supermemory: http://localhost:6767
• PostgreSQL: localhost:5432

The backend container runs Alembic migrations before starting the API.

Local Development

Install workspace dependencies:

bun install

Run all monorepo development tasks:

bun run dev

Run only the web app:

bun --filter @openhuman/web dev

Run backend dependencies with Docker:

docker compose up postgres supermemory

Run the API locally from apps/api:

cd apps/api
uv sync
uv run alembic upgrade head
uv run uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

Useful Commands

# Build all workspaces
bun run build

# Typecheck all workspaces
bun run typecheck

# Lint all workspaces
bun run lint

# Generate OpenAPI spec and TypeScript API client
bun run generate

# Generate only the backend OpenAPI spec
bun --filter @openhuman/api generate:spec

# Generate only the TypeScript API client
bun --filter @openhuman/api-client generate

Backend Tests

From apps/api:

uv sync --extra dev
uv run pytest

Environment Variables

Common API settings:

Variable	Purpose	Default
DATABASE_URL	Async PostgreSQL connection string	postgresql+asyncpg://postgres:postgres@localhost:5432/openhuman
FRONTEND_URL	Public frontend origin for redirects and CORS	http://localhost:3000
SUPERMEMORY_URL	supermemory service URL	http://localhost:6767
SUPERMEMORY_API_KEY_FILE	Optional file path for the supermemory API key	empty
OPENAI_API_KEY	API key for agent model calls	empty
OPENAI_BASE_URL	Optional OpenAI-compatible base URL	empty
OPENAI_MODEL	Model used by the agent	gpt-4o-mini
JWT_SECRET_KEY	Secret used for JWT signing	change-me-in-production
ENCRYPTION_KEY	32-byte hex key for encrypted bot tokens	empty
GATEWAY_ENABLED	Enables Slack and Discord gateway workers	false

Integration settings include Slack OAuth, fixed Slack bot credentials, Discord gateway configuration, and MCP OAuth credentials for providers such as Gmail, Notion, Vercel, GitHub, and Canva.

API Client

The TypeScript client in packages/api-client is generated from apps/api/openapi.json with Orval. When backend routes or schemas change, regenerate the spec and client:

bun run generate

Frontend code imports the generated client through the workspace package:

import { ... } from "@openhuman/api-client";

Deployment Notes

The included Docker setup builds:

• apps/api as the FastAPI service
• apps/web as a standalone Next.js service
• supermemory as the local memory service
• PostgreSQL as the application database

Set production secrets through your deployment platform, not in source control. At minimum, production requires secure values for JWT_SECRET_KEY, ENCRYPTION_KEY, database credentials, model provider keys, and any integration OAuth credentials.

License

No license file is currently included in this repository.