One agent, many surfaces, one continuous task life.
Self-hosted AI agent runtime for cross-surface task continuity across chat apps, Control UI, Canvas, cron, and paired devices.
Start in a DM, hand off into the browser, keep commitments and event history visible, and let the same task continue running.

Overview • What's New • Quick Start • Configuration • Developer Workflow • Architecture • Troubleshooting • Docs

---

Overview

OpenSoul is a self-hosted AI agent runtime for cross-surface task continuity. It does more than mirror the same bot into many channels: one agent can start in WhatsApp, Telegram, Discord, Slack, or the Control UI, then keep the same task alive as work moves into Canvas, cron, subagents, and follow-up sessions.

It is a local-first control plane: channel adapters, task continuity state, model routing, memory, tools, and security boundaries all live in one runtime that you control. The project includes the gateway, Web Control UI, CLI/TUI workflows, and native clients.

What's New

Based on recent updates in CHANGELOG:

Latest product direction (2026-03-12)

• Cross-surface task continuity: introduced operational task state (tasks, task events, commitments) so one agent can keep the same work alive across direct chat, Control UI, Canvas, cron, and subagents.
• System-driven handoff: direct-chat work can now be handed off into a deep-linked Control UI session, with Canvas opening that same session context instead of branching into a separate workflow.
• Visible continuity UI: the Control UI chat page now exposes a right rail with task status, commitments, event timeline, and surface handoff track, so the feature is visible instead of purely architectural.
• Read-only task APIs: clients can inspect continuity state through tasks.list, tasks.get, tasks.events, and tasks.commitments.

Recent release highlights (0.2.4)

• Session transcript loading in the Control UI.
• Create Soulmate modal and better workspace management flows.
• More reliable WebSocket reconnect behavior after connection drops.
• Better onboarding flows, MiniMax support, and CLI developer defaults.

Quick Start

Prerequisites

• Node.js >= 22.12.0
• pnpm >= 10

Install from source

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

Configure for local development

# macOS / Linux
export OPENSOUL_SKIP_CHANNELS=1
export OPENSOUL_GATEWAY_TOKEN=dev-token
# Optional: set at least one model provider key
export OPENAI_API_KEY=your-api-key

Start locally

pnpm gateway:dev

Start locally on Windows (PowerShell)

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

See the flagship experience

After pnpm gateway:dev, open http://127.0.0.1:19001/ and use the Chat page. When a conversation turns into a real task, the right rail shows:

• current task status
• commitments and follow-ups
• event timeline
• surface handoff trail across direct chat, Control UI, Canvas, cron, and subagents

Install and run via CLI

npm install -g opensoul@latest
opensoul onboard
opensoul gateway run

For model keys and provider setup, see the Model Setup Guide. For end-to-end deploy steps, see the Beginner Deployment Guide.

Configuration

Put shared settings in .env or ~/.opensoul/.env:

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

• OPENSOUL_GATEWAY_TOKEN (or gateway.auth.token) is required for gateway startup.
• Use OPENSOUL_SKIP_CHANNELS=1 for local development unless channel credentials are already configured.
• Config supports JSON5, includes, and ${ENV} substitution. See Environment.

Developer Workflow

pnpm install
pnpm build
pnpm dev
pnpm gateway:dev
pnpm check
pnpm test

• After changing ui/, run pnpm ui:build and restart the gateway.
• pnpm check runs type-check, lint, and format checks.
• pnpm check:loc uses repository limits: --max 2000 --max-function 150.

Architecture

flowchart LR
  A["Channels / Channel Plugins"] --> B["Gateway"]
  B --> C["Agent Runtime (pi-ai)"]
  B --> D["Task Continuity Engine"]
  B --> E["Memory & Storage"]
  B --> F["Skills & Tools"]
  B --> G["Web Control UI"]
  D --> G
  B --> H["CLI / TUI"]
  B --> I["Native Apps"]

Loading

Core modules

Module	Path	Responsibility
Gateway	src/gateway	HTTP/WS server, orchestration, sidecars
Agent Runtime	src/agents	Session execution, tool injection, runtime integration
Task Continuity	src/continuity	Tasks, commitments, task events, handoff policy
Routing	src/routing	Message-to-agent/session resolution
Plugins & Channels	src/plugins, src/_, extensions/_	Plugin loading, channel adapters, protocol integrations
Memory	src/memory	Long-term memory and storage
UI & Apps	ui/, apps/	Web Control UI, continuity rail, and native clients

Repository layout

src/           Core gateway, runtime, routing, config, plugins
src/continuity Operational task state, events, commitments, handoff policy
extensions/    External channel/provider/hook plugins
ui/            Web Control UI assets and app
skills/        Built-in skills
docs/          User and reference documentation
apps/          Native clients
scripts/       Build, release, test, and tooling scripts

Tech stack

• Runtime: Node.js 22+, TypeScript 5.9, pnpm 10
• Web UI: Lit 3 + Vite
• API: Hono + Express
• Testing and quality: Vitest, Oxlint, Oxfmt

Testing

• Main entry: pnpm test
• Additional configs: vitest.config.ts, vitest.e2e.config.ts, vitest.gateway.config.ts, vitest.extensions.config.ts, vitest.live.config.ts
• Docker and e2e suites live under scripts/e2e/ and test:docker:*

Extension Development

• Place extensions under extensions/<name>/
• Use opensoul/plugin-sdk as the public API surface
• Do not import internal src/* modules from external extensions
• Typical packages include opensoul.plugin.json and index.ts

Troubleshooting

Symptom	Likely Cause	Fix
Gateway exits immediately	Missing gateway token	Set OPENSOUL_GATEWAY_TOKEN or gateway.auth.token
Gateway dev fails on channel startup	Missing external channel credentials	Use OPENSOUL_SKIP_CHANNELS=1 for local dev
Port conflict	Port already in use	Change gateway.port or run pnpm test:force cleanup
API keys not available in service run	Shell env not inherited	Put keys in ~/.opensoul/.env or enable env.shellEnv

Docs

• Getting Started
• Model Setup Guide
• Beginner Deployment Guide
• Gateway Configuration
• Channels
• Skills & Tools
• Reference Index
• Project Wiki

Contributing

• Contributing Guide
• Code of Conduct
• Maintainer: NJX-njx
• Contributors: GitHub Contributors

License

MIT License — see LICENSE for details. Built upon OpenClaw (MIT).

---

If OpenSoul helps you, please consider giving the project a ⭐ on GitHub.