sbot — Self-hosted AI Agent Server

English | 中文

Open-source, self-hosted AI agent framework. Modular by design: models, memory, tools, and channels are independent building blocks you mix and match to assemble agents — run on your own server with multi-channel integrations, MCP tool support, and a built-in web UI, no vendor lock-in.

---

Quick Start

npm

# Install
npm install -g @qingfeng346/sbot

# Start (foreground), then open http://localhost:5500
sbot

# Start in the background (survives terminal close)
sbot -d

# Start on a specific port (when 5500 is taken; -p and -d can be combined)
sbot -p 3000
sbot -d -p 3000

# Save the port only, do not start
sbot port 3000

Full command reference:

Command	Description
sbot	Start the service (foreground)
sbot -d / --daemon	Start in the background (survives terminal close)
sbot -p <port> / --port	Start on the given port, e.g. sbot -p 3000
sbot port <port>	Save the port without starting
sbot stop	Stop the running service
sbot status	Show running state, port, auto-start, version, config directory
sbot -v / --version	Show version and check for updates
sbot startup enable	Enable launch at boot
sbot startup disable	Disable launch at boot
sbot startup status	Check auto-start status

Permission error on macOS (EACCES)?

If npm install -g fails with EACCES: permission denied, don't fix it with sudo — it leads to tangled file ownership later. The clean fix is to point npm at a directory inside your home folder, so global installs never touch system paths.

One-liner (recommended, auto-detects zsh / bash — paste the whole block into your terminal):

mkdir -p ~/.npm-global && \
npm config set prefix '~/.npm-global' && \
RC_FILE=$([ "${SHELL##*/}" = "bash" ] && echo ~/.bash_profile || echo ~/.zshrc) && \
grep -q '.npm-global/bin' "$RC_FILE" 2>/dev/null || echo 'export PATH=~/.npm-global/bin:$PATH' >> "$RC_FILE" && \
source "$RC_FILE" && \
echo "✓ Done. You can now run: npm install -g @qingfeng346/sbot"

Manual steps (if you want to understand each step):

# 1. Create a user-level global directory
mkdir ~/.npm-global

# 2. Point npm to it (so global installs go here instead of system paths)
npm config set prefix '~/.npm-global'

# 3. Add it to your PATH so the shell can find global commands
#    zsh (default on macOS):
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.zshrc && source ~/.zshrc
#    bash:
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bash_profile && source ~/.bash_profile

Then re-run npm install -g @qingfeng346/sbot.

Docker

docker pull qingfeng346/sbot
docker run -d \
  -p 5500:5500 \
  -v ~/.sbot:/root/.sbot \
  --name sbot \
  qingfeng346/sbot
# Open http://localhost:5500

Configuration and data are persisted in ~/.sbot on the host.

Docker Compose

For long-running deployments where you want pinned versions and one-command upgrades. Create docker-compose.yml:

services:
  sbot:
    image: qingfeng346/sbot
    container_name: sbot
    ports:
      - "5500:5500"
    volumes:
      - ~/.sbot:/root/.sbot
    environment:
      - TZ=Asia/Shanghai
      - LOG_LEVEL=INFO
    restart: unless-stopped

Common commands:

docker compose up -d            # start in background
docker compose logs -f          # follow logs
docker compose down             # stop & remove container (data stays in ~/.sbot)
docker compose pull && docker compose up -d   # upgrade to latest image

---

Features

• Modular composition — Models, memory, tools, channels, and skills are independent building blocks you mix and match to assemble agents
• One-command deployment — npm install -g or docker run, native cross-platform with no extra system dependencies
• Full Web UI management — All configuration done in the browser, no manual file editing required
• Multiple LLM providers — OpenAI, Anthropic Claude, Google Gemini, Ollama, and any OpenAI-compatible API (Azure OpenAI, Groq, Mistral, DeepSeek, etc.); automatic retry with exponential backoff on transient failures
• Multi-agent orchestration — Single, ReAct (recursive task decomposition), and Generative (multimodal) modes; agents can be nested and composed
• ACP agent support — Agent Client Protocol integration with persistent and transient agent modes
• Knowledge base — Built-in wiki system with hybrid keyword + semantic search, referenced by agents during conversations
• Long-term memory — Vector-embedding semantic search for persistent context recall (OpenAI, Google, Ollama, Cohere, VoyageAI)
• Conversation compaction — Automatic conversation summarization when token usage exceeds threshold, preserving continuity while reducing consumption
• Insight system — Per-agent silent post-turn extractor that distills user preferences and lessons learned into reusable Markdown notes; auto-marks notes stale and archives them based on usage
• Heartbeat — Configurable periodic self-activation lets agents run scheduled prompts proactively across any channel
• MCP tools — Standard MCP protocol (stdio/SSE), connect to any MCP tool ecosystem; per-agent and global servers with auto-restart
• Multiple channels — Web UI, CLI, Lark/Feishu, Slack, WeCom, WeChat, OneBot (QQ), XiaoAI, REST API, WebSocket
• Built-in tools — Shell execution, file system, archive operations, media file read, Python/PowerShell inline execution, web fetch/download, cron scheduler, todo
• Skills — Installable prompt modules with remote install from Clawhub, skills.sh, and skillhub.cn
• Agent Store — Browse and install pre-packaged agents (model + prompt + tools + skills + MCP servers) from configurable sources
• Token usage tracking — Per-model consumption statistics, model response caching with hit/miss metrics
• Unattended-session safety — Configurable approval and ask timeouts on channels for autonomous operation
• Flexible config — Global and per-session overrides from a single settings.json; customizable prompts with hot reload

---

Usage Guide

Open http://localhost:5500 after starting sbot. Follow these steps:

1. Add a Model — sidebar → Models → New

Fill in provider, API key, base URL, and model name. Supported providers: OpenAI, Anthropic, Google Gemini, Ollama, and any OpenAI-compatible endpoint (Azure OpenAI, Groq, Mistral, DeepSeek, etc.).

---

2. Create a Saver — sidebar → Savers → New

Choose a backend for storing conversation history:

Backend	Description
File	JSON files per conversation thread (recommended)
SQLite	Local SQLite database
Memory	Cleared after conversation ends, no persistence, suitable for one-off conversations or Q&A assistants

---

3. Create an Agent — sidebar → Agents → New

Choose a mode:

• Single — select a model, write a system prompt, optionally attach MCP tools and skills
• ReAct — select a think model, then add sub-agents (each with an id and description for task dispatch). The think model decomposes tasks and dispatches sub-tasks recursively; each sub-agent has read-only access to shared memory
• Generative — select a multimodal model for mixed text and image content generation

→ MCP Tools · Skills

---

4. Start chatting — choose your entry point

• Session — sidebar → Chat → New Session, select agent + saver + memory; optionally configure a working directory
• Channel (IM) — sidebar → Channels → New → Channel Setup; optionally configure a working directory

---

5. (Optional) Enable Wiki Knowledge Base — sidebar → Wiki → New

Built-in knowledge base. Create pages manually (title + content + tags). Assign wikis to a session or channel; agents can search, read, write, and update pages via built-in tools. An optional embedding model enables semantic search alongside keyword matching.

Field	Description
Name	Wiki identifier
Embedding	Optional — enables semantic search; without it, falls back to keyword search

---

6. (Optional) Enable Memory — sidebar → Memories → New

A vector store the agent can write to and search via tool calls. Requires an embedding model first (sidebar → Embeddings → New), then assign the memory to a session or channel. Entries are time-decay weighted on retrieval and de-duplicated on insert.

Field	Description
Name	Memory identifier
Embedding	Embedding model for semantic search (OpenAI, Google, Ollama, Cohere, VoyageAI)

---

7. (Optional) Enable Insight on an agent — Agent edit page → Insight section

Insight is a silent post-turn extractor that runs after every conversation turn and distills durable knowledge — user preferences, project facts, lessons learned — into reusable Markdown notes (SKILL.md files under ~/.sbot/insights/). Relevant insights are auto-injected back into the system prompt on subsequent turns via hybrid keyword + semantic search.

Field	Description
Scope	Disabled / Per Agent (shared across all sessions of this agent) / Per Session (isolated per thread)
Extraction Model	Model used to run the post-turn extraction (typically a cheap, fast model)
Extraction Prompt	Prompt file from ~/.sbot/prompts/insight/extractor/ controlling what is extracted

The extractor can create, patch, or delete insights based on conversation evolution. Stale notes (default 30 days unused) are marked, and unused notes (default 90 days) are auto-archived.

---

8. (Optional) Install pre-packaged agents — sidebar → Agent Store

Browse and install agents from configurable registries. Each package bundles model selection, system prompt, skills, and MCP server configuration in one click. Add custom registry URLs in Settings.

---

Add MCP Tools

Sidebar → MCP → New

Add a server:

• stdio — command + args (e.g. npx -y some-mcp-package)
• sse — remote URL + optional headers

Supports global servers shared across all agents and per-agent overrides. Servers auto-restart on failure. Then open an agent → MCP tab to attach the servers you want it to use.

---

Manage Skills

Sidebar → Skills

Skill files (Markdown) are stored in ~/.sbot/skills/. Search and install from remote hubs (Clawhub, skills.sh, skillhub.cn) on the Skills page, or drop files manually. In an agent → Skills tab, select specific skills to load, or leave empty to load all.

---

Customize Prompts

Sidebar → Prompts

View and edit any built-in prompt (system prompts, agent prompts, tool descriptions, etc.). Saved overrides are stored in ~/.sbot/prompts/ and take precedence over the defaults, effective immediately without restart. Supports {varName} placeholders substituted at runtime.

---

Heartbeat (Proactive Activation)

Sidebar → Heartbeat

Configure periodic prompts that wake an agent on a fixed interval — useful for monitoring, daily summaries, or scheduled outreach. Each heartbeat targets a specific channel or session and runs a prompt template. Combine with the Scheduler tool for one-off tasks.

---

Channel Setup

In Channels → New, select the type and fill in the credentials, then assign agent + saver + memory. Every user/group chat is isolated automatically.

Type	Required fields
Lark / Feishu	App ID, App Secret
Slack	Bot Token (xoxb-...), App Token (xapp-...)
WeCom	Bot ID, Secret
WeChat	QR code login (credentials auto-populated)

Setting up Lark / Feishu:

1. Create a bot app in the Feishu Developer Console (or Lark Developer Console for international)
2. Enable Bot capability
3. Grant the following permissions under Permissions & Scopes (or use Batch Import with the JSON below):

Permission	Description
im:message:send_as_bot	Send messages as bot
im:message.p2p_msg:readonly	Receive direct messages
im:message.group_at_msg:readonly	Receive group @bot messages
im:message.group_msg	Receive all group messages
im:message:readonly	Read message content
im:chat:readonly	Read chat/group info
im:resource	Read files and images in messages
contact:user.base:readonly	Read basic user info
contact:contact.base:readonly	Read basic contact info

Batch import JSON

{
  "scopes": {
    "tenant": [
      "contact:contact.base:readonly",
      "contact:user.base:readonly",
      "im:chat:readonly",
      "im:message.group_at_msg:readonly",
      "im:message.group_msg",
      "im:message.p2p_msg:readonly",
      "im:message:readonly",
      "im:message:send_as_bot",
      "im:resource"
    ],
    "user": []
  }
}

1. Under Events & Callbacks, set the subscription mode to Long Connection
2. In Web UI → Channels, create a Lark channel and fill in App ID and App Secret

Supports event deduplication, interactive cards, per-user context isolation, and file/image send and receive.

Setting up WeCom:

1. Create an AI app in the WeCom Admin Console and obtain the Bot ID and Secret
2. In Web UI → Channels, create a WeCom channel and fill in Bot ID and Secret

Connects via WebSocket for real-time messaging, with file and image support.

Setting up WeChat:

1. In Web UI → Channels, create a WeChat channel
2. Click QR login and scan the code with WeChat to authenticate
3. Credentials are saved automatically once authenticated, and the channel goes live immediately

WeChat integration connects via the iLink Bot API, with file and image support.

---

Built-in Tools

Command Execution

• Shell commands and scripts
• Inline Python and PowerShell execution
• File-referenced script execution
• Configurable timeout per command

File System

• Read, write, edit files
• Search with regex (grep)
• Find files by pattern (glob)
• Directory listing, create, remove, move, copy
• Read media files (images, etc.)
• Optional read-only mode per agent

Archive

• Compress and extract archive files
• List archive contents
• Read files directly from within archives

Web

• Fetch URLs and convert HTML to clean Markdown
• Download files from the web

Scheduler

• Standard 6-field cron expressions (second minute hour day month weekday), persisted across restarts
• Tasks can target a channel user, a web session, or a working directory
• Optional max run count with auto-cleanup
• Manageable via the Web UI or by asking the agent directly

Todo

• Agents can create, complete, and query todo tasks
• Web UI provides a Todo management page

Ask

• Agents can pause mid-task and ask the user structured questions
• Supported question types: single-select, multi-select, text input
• Works across Web UI and Lark; the agent resumes automatically after the user responds

---

Keywords

ai agent self-hosted llm server open source mcp acp model context protocol multi-agent react agent openai claude anthropic gemini ollama chatbot lark feishu onebot qq long-term memory vector search typescript node.js