Quickstart

This guide is for local development. To deploy on a server, see Docker Compose.

Prerequisites

Node.js 20+ and pnpm — npm install -g pnpm
Docker — used for Redis only
A Supabase project — free tier works
An Anthropic API key

Step 1: Clone and install

git clone https://github.com/NousC/opennous.git
cd nous
pnpm install

Step 2: Configure environment

cp .env.example .env

Open .env and fill in:

# Supabase — Settings → API
SUPABASE_URL=https://your-project.supabase.co
SUPABASE_ANON_KEY=your-anon-key
SUPABASE_SERVICE_ROLE_KEY=your-service-role-key
VITE_SUPABASE_URL=https://your-project.supabase.co
VITE_SUPABASE_ANON_KEY=your-anon-key

# Anthropic
ANTHROPIC_API_KEY=sk-ant-...

# Generate with: node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
ENCRYPTION_KEY=
API_SECRET=

Step 3: Run the database schema

Required on first setup. Skip this and the app will start but nothing will work.

Open your Supabase project → SQL Editor → paste and run the full contents of supabase/schema.sql.

Step 4: Start Redis

docker compose -f docker-compose.dev.yaml up -d

This starts Redis on localhost:6379. The API and worker need it to run.

Step 5: Start the app

pnpm dev

Starts all four services in parallel:

Service	URL	What it does
API	`http://localhost:3000`	REST API, identity resolution, signal ingestion
Frontend	`http://localhost:5173`	Web UI
MCP server	`http://localhost:3001`	Agent tool interface
Worker	background	AI synthesis, two-way sync, ICP scoring

Step 6: Connect your first integration

Open http://localhost:5173 → Settings → Integrations and connect at least one source:

HubSpot

One-time import of existing contacts and deal history.

Gmail

Ingest email signals in real time via OAuth.

Pull connection requests and messages via Unipile.

Webhooks

Connect any custom signal source with HMAC auth.

Step 7: Connect your AI agent via MCP

Add Nous to your mcp.json (Claude Desktop, Cursor, or any MCP host):

{
  "mcpServers": {
    "nous": {
      "command": "npx",
      "args": ["-y", "@opennous/mcp"],
      "env": {
        "NOUS_API_KEY": "your-api-key",
        "NOUS_API_URL": "http://localhost:3000"
      }
    }
  }
}

Generate your API key under Settings → API Keys.

What’s next

How it works

Identity resolution, signal ingestion, and the unified record architecture.

MCP tools reference

Full reference for all MCP tools your agents can call.

Production deploy

Deploy on your own server with Docker Compose.

REST API

Integrate via REST API from any language or platform.

Getting Started

Installation

Providers

Prerequisites

Step 1: Clone and install

Step 2: Configure environment

Step 3: Run the database schema

Step 4: Start Redis

Step 5: Start the app

Step 6: Connect your first integration

HubSpot

Gmail

LinkedIn

Webhooks

Step 7: Connect your AI agent via MCP

What’s next

How it works

MCP tools reference

Production deploy

REST API

​Prerequisites

​Step 1: Clone and install

​Step 2: Configure environment

​Step 3: Run the database schema

​Step 4: Start Redis

​Step 5: Start the app

​Step 6: Connect your first integration

HubSpot

Gmail

LinkedIn

Webhooks

​Step 7: Connect your AI agent via MCP

​What’s next

How it works

MCP tools reference

Production deploy

REST API

Prerequisites

Step 1: Clone and install

Step 2: Configure environment

Step 3: Run the database schema

Step 4: Start Redis

Step 5: Start the app

Step 6: Connect your first integration

Step 7: Connect your AI agent via MCP

What’s next