Quick Start

Prerequisites

• Node.js ≥ 22 — Download
• pnpm (for development builds) — corepack enable
• An API key from OpenAI, Anthropic, Google Gemini, or any supported provider

Option A: Install from npm (Recommended)

1. Install OpenSoul

npm install -g opensoul@latest

2. Run the Setup Wizard

opensoul onboard --install-daemon

The interactive wizard will guide you through API key configuration, channel pairing (e.g. WhatsApp QR scan), and daemon installation.

3. Pair a Channel & Start

opensoul channels login
opensoul gateway --port 18789

Open http://127.0.0.1:18789 to access the Web Control UI dashboard.

Option B: Build from Source (Development)

1. Clone & Install

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

2. Start Gateway (Dev Mode)

Linux / macOS:

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

OPENSOUL_SKIP_CHANNELS=1 skips loading channel extensions that require external API credentials — ideal for local development.

3. Open the Dashboard

Navigate to http://127.0.0.1:19001 (dev default port).

Production Runtime

opensoul onboard
opensoul gateway run

For production, set your gateway token via OPENSOUL_GATEWAY_TOKEN or gateway.auth.token in config.

Configuration

Config lives at ~/.opensoul/opensoul.json (JSON5 format with ${ENV} substitution).

Environment Variables

Place these in .env or ~/.opensoul/.env:

OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...
GEMINI_API_KEY=AIza...
OPENSOUL_GATEWAY_TOKEN=your-secret-token

Example Config

{
  channels: {
    whatsapp: {
      allowFrom: ["+15555550123"],
      groups: { "*": { requireMention: true } },
    },
  },
  messages: {
    groupChat: { mentionPatterns: ["@opensoul"] }
  },
}

What's Next?

• Explore all features — channels, agent runtime, skills, and more
• Understand the architecture — how the Gateway orchestrates everything
• Browse the Wiki — comprehensive project knowledge base
• Contribute — help make OpenSoul better

Troubleshooting

Symptom	Likely Cause	Fix
Gateway exits immediately	Missing gateway token	Set OPENSOUL_GATEWAY_TOKEN
Channel startup fails	Missing external credentials	Use OPENSOUL_SKIP_CHANNELS=1
Port conflict	Port already in use	Change gateway.port in config
API keys not found in service	Shell env not inherited	Put keys in ~/.opensoul/.env