Getting Started

Goal: go from zero to a first working chat with minimal setup.

Info: Fastest chat: open the Control UI (no channel setup needed). Run opensoul dashboard and chat in the browser, or open http://127.0.0.1:18789/ on the gateway host. Docs: Dashboard and Control UI.

Recommended path: use the CLI onboarding wizard (opensoul onboard). It configures:

• Model/Auth (OAuth recommended)
• Gateway settings
• Channels (WhatsApp, Telegram, Discord, etc.)
• Pairing defaults (secure DMs)
• Workspace bootstrapping + Skills
• Optional background services

For deeper reference, see: Wizard, Setup, Pairing, Security.

Sandbox Note

agents.defaults.sandbox.mode: "non-main" uses session.mainKey (default "main"), so group/channel sessions are sandboxed. If you want a main agent to always run on the host, set an explicit per-agent override:

{
  "routing": {
    "agents": {
      "main": {
        "workspace": "~/.opensoul/workspace",
        "sandbox": { "mode": "off" }
      }
    }
  }
}

0) Prereqs

• Node >=22
• pnpm (optional; recommended if building from source)
• Recommended: Brave Search API key for web search. Easiest path: opensoul configure --section web (stores tools.web.search.apiKey). See Web tools.

macOS: If you plan to build the app, install Xcode / CLT. For CLI + Gateway only, Node is enough. Windows: Use WSL2 (Ubuntu recommended). Native Windows is untested and has more tool compatibility issues. See Windows (WSL2).

1) Install OpenSoul (CLI)

macOS/Linux

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

Windows (PowerShell)

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

Note: Other install methods and requirements: Install.

2) Run the onboarding wizard

opensoul onboard --install-daemon

You will choose:

• Local vs Remote Gateway.
• Auth: Anthropic API key (recommended) or OAuth.
• Providers: WhatsApp QR login, Telegram/Discord bot tokens, etc.
• Daemon: Background installation (launchd/systemd).
• Gateway Token: Generated and stored in gateway.auth.token.

See Onboarding Wizard for details.

3) Check the Gateway

If you installed the service, it should already be running:

opensoul gateway status

Manual run (foreground):

opensoul gateway --port 18789 --verbose