Install & configure

# 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

That is the whole install: binary + Web UI + every built-in plugin (genui / git-fancy / ambience), with the web channel already enabled. Nothing else to install, and no config file to edit first.

xbot-cli serve          # then open http://localhost:8082

In the browser: create an account → gear icon → LLM → base URL / API key / pick a model → start chatting.

Note

The first account on a fresh install needs no invite code and becomes the admin.

Paste this into your AI agent (Claude Code / Codex / Cursor …) — it installs and verifies on its own:

Install and start xbot on this machine:

1. Install: curl -fsSL https://raw.githubusercontent.com/ai-pivot/xbot/master/scripts/install.sh | bash
2. Verify:  xbot-cli setup --check        # exit code 0 means the install is complete
3. Start:   nohup xbot-cli serve >/tmp/xbot.log 2>&1 &
4. Confirm: curl -s -o /dev/null -w '%{http_code}' http://127.0.0.1:8082   # must print 200

If any step fails, read the Troubleshooting section below — do not skip the
check and claim it worked.

For an agent that wants to read up front, there is a dedicated executable guide (assertable steps, headless LLM setup, troubleshooting table):

Tip

Agent install guide (executable) — https://ai-pivot.github.io/xbot/agent-install/

install.sh’s header comments carry the same pointer, and the script prints the doc URL as its last output — so the “paste this into your agent” flow always tells the agent what to read next.

Notes for the agent:

• install.sh is idempotent — re-running it never clobbers existing settings (existing values always win).
• setup --check is the single source of truth for a complete install: exit code 0 means all checks passed.
• serve runs in the foreground; background it yourself (nohup / systemd / tmux).
• After install ~/.xbot/config.json already has the web + plugin settings. Do not hand-edit llm.* — LLM settings live in the database; use the web settings panel or the xbot-cli commands instead.

Environment-variable prefixes — put them before the command, e.g. MODE=server-client PORT=9000 bash install.sh:

Behind the GFW, use the mirror (GH_MIRROR is set automatically by the mirror script):

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

Everything else — LLM subscriptions, channels (Feishu / QQ / Web / CLI), sandbox and runners, memory, hooks, logging, plugins — lives in Configuration.

xbot-cli --version        # version
xbot-cli setup --check    # completeness check: exit code 0 = OK

# Is the web server up? (add --noproxy '*' if a local proxy intercepts curl)
curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:8082     # expect 200

# server-client mode service status
systemctl --user status xbot-server     # Linux
launchctl list | grep xbot              # macOS

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

Re-running the installer is the upgrade path: the binary is replaced, config.json and the database are left untouched.

systemctl --user disable --now xbot-server   # server-client mode
rm -f ~/.local/bin/xbot-cli
rm -rf ~/.xbot                                # data dir — includes the database

git clone https://github.com/ai-pivot/xbot.git && cd xbot
make setup      # build CLI + Web UI + built-in plugins, install into ~/.xbot, activate channels

Requires Go 1.26+; make setup additionally needs Node.js (web frontend build).

• Configuration — full config.json, LLM subscriptions, model tiers
• Getting started — your first conversation after install
• Channels — Feishu / QQ / Web / CLI setup
• Plugins — plugin system and built-in plugins