Getting Started

Getting Started

Get OpenSoul installed and run your first chat in minutes.

Prerequisites

• Node.js >= 22
• pnpm (recommended for building from source)
• An API key from a supported provider (OpenAI, Anthropic, Gemini, etc.)

Installation

From Source (Recommended for Developers)

git clone https://github.com/NJX-njx/opensoul.git
cd opensoul
pnpm install
pnpm build

Quick Install (CLI)

macOS / Linux:

curl -fsSL https://opensoul.ai/install.sh | bash

Windows (PowerShell):

iwr -useb https://opensoul.ai/install.ps1 | iex

Run the Onboarding Wizard

opensoul onboard --install-daemon

The wizard guides you through:

• Auth: API key (Anthropic recommended) or OAuth
• Gateway settings: Port, token, bind host
• Channels: WhatsApp QR login, Telegram/Discord bot tokens
• Daemon: Background service installation (launchd/systemd)

Start the Gateway

Development Mode

# Skip channels that require external credentials
export OPENSOUL_SKIP_CHANNELS=1
export OPENSOUL_GATEWAY_TOKEN=dev-token
pnpm gateway:dev

Windows (PowerShell)

$env:OPENSOUL_SKIP_CHANNELS = "1"
$env:OPENSOUL_GATEWAY_TOKEN = "dev-token"
node scripts/run-node.mjs --dev gateway

Production

opensoul onboard
opensoul gateway run

Verify

opensoul gateway status
opensoul health

Open the Control UI at http://127.0.0.1:18789/ to chat directly in the browser — no channel setup needed.

Connect a Channel

WhatsApp (QR Login)

opensoul channels login

Scan the QR code via WhatsApp → Settings → Linked Devices.

Telegram / Discord

The wizard can configure tokens for you, or set them manually:

• See Channels for per-channel setup guides

DM Safety (Pairing Approval)

By default, unknown DMs receive a shortcode and are not processed until approved:

opensoul pairing list whatsapp
opensoul pairing approve whatsapp <code>

Environment Variables

Place API keys in .env or ~/.opensoul/.env:

OPENAI_API_KEY=
ANTHROPIC_API_KEY=
OPENROUTER_API_KEY=
GEMINI_API_KEY=
MINIMAX_API_KEY=
OPENSOUL_GATEWAY_TOKEN=

Next Steps

• Configuration — Customize gateway and agent settings
• Channels — Set up messaging channels
• Control UI — Use the browser dashboard
• Architecture — Understand the system design