Getting Started

Prerequisites

Requirement	Details
OS	Linux (x64/ARM64), macOS (Intel/Apple Silicon), Windows (x64/ARM64)
LLM API Key	OpenAI, Anthropic, DeepSeek, Groq, Gemini, or local Ollama/vLLM
Network	LLM API access (remote) or local GPU server (local mode)
Disk	~30MB (single static binary)

Installation

Option 1: One-line Install Script (Recommended)

Auto-detects your OS and architecture, downloads the appropriate binary, and installs it.

bash

# Auto-detects OS and architecture
curl -sSL https://guoqingbao.github.io/xbot/install.sh | bash

Tip

On Linux, the script offers deb package or binary install options. On macOS, it installs directly to /usr/local/bin.

Option 2: npm

bash

npm install -g @trusted-ai/xbot

Option 3: Cargo

bash

cargo install xbot

Option 4: Manual Deb Install

bash

wget https://github.com/guoqingbao/xbot/releases/latest/download/xbot-linux-x64.deb
sudo dpkg -i xbot-linux-x64.deb

Option 5: Build from Source

bash

git clone https://github.com/guoqingbao/xbot.git
cd xbot
cargo install --path .

Verify Installation

bash

xbot --help

Initialize Configuration

bash

xbot onboard

This creates:

Global config ~/.xbot/config.json — stores provider keys, model settings, channel config
Global workspace ~/.xbot/workspace — default persistent workspace directory
Interactive wizard guides you through configuring the default LLM provider and model

Configure LLM Providers

Use the interactive wizard or manually edit config.json:

bash

xbot config --provider

Example: OpenAI (Remote)

json

{
  "agents": {
    "defaults": {
      "model": "openai/gpt-4.1-mini",
      "provider": "openai"
    }
  },
  "providers": {
    "openai": { "apiKey": "sk-..." }
  }
}

Example: Ollama (Local)

bash

ollama serve
ollama pull qwen2.5-coder:7b

json

{
  "agents": {
    "defaults": {
      "model": "ollama/qwen2.5-coder:7b",
      "provider": "ollama"
    }
  },
  "providers": {
    "ollama": {
      "apiBase": "http://localhost:11434/v1"
    }
  }
}

Example: DeepSeek

json

{
  "agents": {
    "defaults": {
      "model": "deepseek/deepseek-chat",
      "provider": "deepseek"
    }
  },
  "providers": {
    "deepseek": { "apiKey": "sk-..." }
  }
}

Example: Hybrid Model Routing

Main task on remote frontier model, subagents on local model for parallel work:

json

{
  "agents": {
    "defaults": {
      "model": "openai/gpt-4.1",
      "provider": "openai"
    },
    "subagents": {
      "model": "qwen2.5-coder:7b",
      "provider": "local-vllm",
      "apiBase": "http://127.0.0.1:8001/v1"
    }
  }
}

Channel Setup

bash

xbot config --channel         # Interactive channel setup
xbot channels list            # List all available channels
xbot channels status          # Show enabled/disabled status
xbot channels setup slack     # Credential instructions for Slack

Channel Configuration Guide.

Tools Configuration

Configure shell execution, web search proxy, and MCP tool servers:

json

{
  "tools": {
    "exec": {
      "enable": true,
      "timeout": 120
    },
    "web": {
      "search": {
        "provider": "duckduckgo",
        "maxResults": 10
      }
    },
    "restrictToWorkspace": false
  }
}

CLI Mode

CLI mode is ideal for one-shot tasks and script integration.

bash

# Initialize project context (creates .xbot/ and XBOT.md)
xbot chat /init

# One-shot task
xbot chat "find bugs in this project"

# Use a specific model
xbot chat --model anthropic/claude-sonnet-4-20250514 "review my code"

# Use global workspace for general tasks
xbot chat --global "research quantum computing trends"

REPL Mode

Interactive TUI with streamed responses, persistent history, and model switching.

bash

xbot repl
xbot repl --workspace /path/to/project
xbot repl --global

Command	Description
`/help`	Show available commands
`/new` / `/clear`	Start new session
`/memorize <text>`	Store permanent memory
`/status`	View runtime status
`/stop`	Stop current task
`/model <name>`	Switch model
`/init`	Initialize project context

Backend Service

Starts the always-on AI assistant backend with configured channels. Includes Gateway HTTP server, heartbeat service, and cron scheduler.

bash

xbot run
xbot run --workspace /path/to/project

Default Endpoints

Gateway listens on 0.0.0.0:18790 by default. Health at /healthz, metrics at /metrics, admin UI at /admin.

Next Steps

📖

User Guide

Deep dive into all features and modes

📬

Channel Setup

Configure Slack, Telegram, and more

📡

API Reference

Complete CLI and Gateway API reference