FAQ

FAQ

Frequently asked questions about OpenSoul.

General

What is OpenSoul?

OpenSoul is a self-hosted AI agent gateway that connects messaging apps (WhatsApp, Telegram, Discord, Slack, iMessage, and 30+ more) to AI agents. You run one gateway process and chat with the same AI from any channel.

Is OpenSoul free?

Yes. OpenSoul is open source under the MIT License. You need your own API keys for model providers (OpenAI, Anthropic, etc.).

What AI models does OpenSoul support?

OpenSoul supports multi-model routing across:

• OpenAI (GPT-4o, GPT-4, o1, o3, etc.)
• Anthropic (Claude 4, Claude 3.5, etc.)
• Google Gemini (2.5 Pro, 2.0 Flash, etc.)
• AWS Bedrock
• Ollama (local models)
• MiniMax
• OpenRouter
• And more through the plugin system

Does OpenSoul require an external database?

No. OpenSoul uses embedded SQLite with sqlite-vec for storage and vector search. No PostgreSQL, Redis, or other external database is needed.

What operating systems are supported?

• Server/Gateway: macOS, Linux, Windows (WSL2 recommended for full compatibility)
• Native apps: macOS, iOS, Android, Windows
• Web UI: Any modern browser

Setup

What do I need to get started?

• Node.js >= 22
• pnpm (for building from source)
• An API key from a supported model provider
• 5 minutes

How do I get an API key?

Sign up with a model provider:

• OpenAI
• Anthropic
• Google AI Studio (for Gemini)

Can I use local/self-hosted models?

Yes, via Ollama integration. Install Ollama, download a model, and configure it in OpenSoul.

How do I connect WhatsApp?

Run opensoul channels login and scan the QR code with WhatsApp → Settings → Linked Devices.

Architecture

How does the gateway work?

The gateway is a single Node.js process that:

1. Receives messages from all connected channels
2. Routes them to the appropriate agent/session
3. Sends responses back through the originating channel

See Architecture for details.

Can I run multiple agents?

Yes. OpenSoul supports multi-agent routing with independent workspaces, model configs, identities, and tool permissions.

Where is my data stored?

All data stays on your machine:

• Config: ~/.opensoul/opensoul.json
• Workspace: ~/.opensoul/workspace/
• Database: Local SQLite
• Logs: Local files

No data is sent to any third party except the model provider APIs you configure.

Development

How do I contribute?

See the Contributing guide. We welcome code, docs, skills, extensions, and translations.

How do I create a custom channel extension?

See Extension Development. Extensions use the public Plugin SDK and live in extensions/<name>/.

How do I create a custom skill?

Skills live in skills/<name>/. See Skills and Tools for the structure and manifest format.

How do I run tests?

pnpm test          # All tests
pnpm check         # Type-check + lint + format

Troubleshooting

The gateway won't start

Most likely cause: missing OPENSOUL_GATEWAY_TOKEN. Set it via environment variable or config. See Troubleshooting.

My bot doesn't respond to messages

Check:

1. Is the gateway running? (opensoul gateway status)
2. Is the channel connected? (opensoul channels status)
3. Is pairing approved? (opensoul pairing list <channel>)
4. Is the API key valid?

How do I reset everything?

rm -rf ~/.opensoul
opensoul onboard --install-daemon

Related Pages

• Getting Started — Quick start
• Troubleshooting — Detailed issue resolution
• Roadmap — What's coming next