xbot — Self-hosted AI Agent with a first-class Web UI

Browser · Feishu · Terminal — one agent, one config, your server

简体中文  ·  Documentation  ·  Changelog

---

What is xbot?

xbot is a self-hosted AI agent you run on your own server and drive from the browser. It uses tools — Shell, file I/O, web search, scheduled tasks, sub-agents, plugins — to get real work done, and your data never leaves your server.

The Web UI is the primary surface: sessions and live streaming, file preview, git diffs, a built-in terminal, plugin panels, and a model picker — all in the browser. Feishu / terminal channels connect the same agent to wherever your team already works, sharing one LLM configuration.

	xbot	Terminal-only agents
Primary UI	Web browser (+ Feishu · CLI)	Terminal only
Team LLM	Admin configures once, everyone uses	Each user brings their own key
Self-hosted	✅ Your data stays on your server	✅
Plugin system	Web views, panels, tools, hooks, channel plugins	Limited
SubAgents + Group Chat	Delegate, parallelize, debate	SubAgents only
Feishu tools	Docs, Bitable, Drive, interactive cards	❌

Quick start

1. Install (one command)

# Linux / macOS
curl -fsSL https://raw.githubusercontent.com/ai-pivot/xbot/master/scripts/install.sh | bash

# Windows (PowerShell)
irm https://raw.githubusercontent.com/ai-pivot/xbot/master/scripts/install.ps1 | iex

🇨🇳 Users behind the GFW (no VPN needed)

curl -fsSL https://ghfast.top/https://raw.githubusercontent.com/ai-pivot/xbot/master/scripts/install-cn.sh | bash

The script auto-detects a working CDN mirror and proxies all GitHub downloads. You can also set GH_MIRROR=ghfast.top manually.

One command installs everything: binary + Web UI + every built-in plugin, with the web channel already enabled.

Component	Where
CLI + server binary	~/.local/bin/xbot-cli
Web UI + built-in plugins + channel activation	$XBOT_HOME (done by xbot-cli setup)

Already installed? Re-run xbot-cli setup to repair, or xbot-cli setup --check to diagnose.

Or: paste this into your AI agent and let it do the install

Install and start xbot on this machine:
1. curl -fsSL https://raw.githubusercontent.com/ai-pivot/xbot/master/scripts/install.sh | bash
2. xbot-cli setup --check        # exit code 0 means a complete install
3. nohup xbot-cli serve >/tmp/xbot.log 2>&1 &
4. curl -s -o /dev/null -w '%{http_code}' http://127.0.0.1:8082   # must print 200
If anything fails, read https://ai-pivot.github.io/xbot/installation/ (Troubleshooting).

There are exactly 5 optional flags (MODE / PORT / XBOT_HOME / INSTALL_PATH / CHANNEL); everything else lives in Install & configure.

2. Start the server

xbot-cli serve

That's it — the installer already enabled the web channel. Want it to survive reboots? Reinstall with the service mode: MODE=server-client bash install.sh (writes and starts the systemd --user unit xbot-server; see the installation guide).

3. Open the Web UI and configure

Browse to http://localhost:8082:

1. Create account — the first registration becomes the operator account (no invite code needed on a fresh install).
2. Add your LLM — gear icon (bottom-right) → LLM → add a subscription: provider, base URL (https://…/v1), API key, then pick a model.
3. Start chatting — create a session in the left sidebar and type below.

Web UI at a glance

Feature	Where
Activity Bar	48 px icon rail on the far left — click an icon to switch the sidebar (sessions / files / search / tasks / terminal / stats / plugins / skills / git)
Sessions	Left sidebar; “+ New Session”, search, star, right-click for rename / fork / delete
Live progress	Per-iteration streaming with tool cards, reasoning, token/s and TTFT
Composer	Markdown + images + file attachments, Ctrl+Enter to send, @ file mentions
Model picker	Composer → “Choose model and thinking mode”; per-session model + thinking level
File preview	Click a file in the explorer → syntax-highlighted preview, images, Mermaid
Git panel	Built-in (plugin xbot.git-fancy) — branch, diff, commit details
Terminal	Full PTY in a tab (local or remote runner)
Plugins	Manage panel + plugin-provided views, widgets, info-bar items
Mobile	Responsive layout with a bottom nav and touch-friendly targets

Built-in plugins

Shipped with every release and installed by xbot-cli setup:

Plugin	Type	What it does
xbot.genui	channel + tool	Generative UI — the model emits TSX that renders as a live interactive panel in the browser (display_html tool)
xbot.git-fancy	tool + web views	Git status panel, per-file diffs and commit details rendered in the editor area
xbot.ambience	UI	Wallpapers, glass effects, an animated desk-pet and particle overlays for the web UI

Plugin activation: a channel plugin also needs channels.<name>.enabled = true in config.json — xbot-cli setup writes it automatically (and never overwrites an explicit false).

See the plugin docs for the full manifest / permission / web-view reference.

Channels

Every channel drives the same agent and shares the same LLM configuration.

Web (primary)

{ "web": { "enable": true, "port": 8082 } }

Feishu

Create an app on the Feishu Open Platform, then:

{
  "feishu": {
    "enabled": true,
    "app_id": "cli_xxx",
    "app_secret": "xxx"
  }
}

Required permissions: im:message, im:message.receive_v1, im:message:send_as_bot, contact:user.base:readonly

Other channels

See the Channels documentation.

Built-in tools

The agent can call these tools in conversation:

Category	Tools
Execution	Shell (foreground → promote to background), Cd
Files	Read, FileCreate, FileReplace, Grep, Glob, DownloadFile
Web	Fetch, WebSearch
Vision	view_image (multimodal image input)
Sessions	CreateChat, SubAgent, SendMessage
Context	context_edit, offload_recall, recall_masked
Scheduling	Cron, TodoWrite, TodoList
Config	config, tui_control
Collaboration	Worktree, EventTrigger
Tasks	task_status, task_kill, task_wait, task_read
Other	AskUser, ChatHistory, ManageTools, Skill, Feishu tools

Extensibility

• Skills — Markdown capability packs in ~/.xbot/skills/
• SubAgents — role-based child agents (explore, code-reviewer, …); custom roles in ~/.xbot/agents/
• Group chat — multi-agent moderated discussion (meeting mode)
• MCP — global and per-session MCP servers (stdio + HTTP), pooled across sessions
• Hooks — command / script handlers on tool and lifecycle events

Documentation

Getting started	Install → first conversation
Installation	Every install path, offline & mirrors
Configuration	config.json reference
Plugins	Manifest, permissions, web views
Channels	Web · Feishu · CLI
FAQ	Common questions

License

MIT