Getting Started

Install xopc, add at least one LLM provider key, then run the CLI or gateway. This page covers a first-time setup from scratch.

1. Prerequisites

Before you begin, ensure you have:

• Node.js: Version 22.0.0 or newer (node -v)
• pnpm: Recommended package manager (pnpm --version)

Note: This project uses pnpm. Do NOT use npm for package management.

2. Installation

Option 1: Install from npm (Recommended)

npm install -g @xopcai/xopc

Option 2: Build from source

git clone https://github.com/xopcai/xopc.git
cd xopc
pnpm install
pnpm run build

3. Configuration

Interactive Setup (Recommended)

Use the onboard wizard for guided setup:

xopc onboard
# or: pnpm run dev -- onboard

The wizard will guide you through:

1. Creating workspace directory (~/.xopc/workspace/)
2. Generating default config.json
3. Selecting an LLM provider and entering API key
4. Configuring messaging channels (Telegram)
5. Setting up Gateway WebUI

Quick Setup

For minimal setup without interactive prompts:

xopc setup

This creates basic config and workspace files only.

Manual Configuration

Edit ~/.xopc/xopc.json directly:

{
  "agents": {
    "defaults": {
      "model": "anthropic/claude-sonnet-4-5",
      "max_tokens": 8192,
      "temperature": 0.7
    }
  },
  "providers": {
    "anthropic": "${ANTHROPIC_API_KEY}"
  }
}

Tip: Use environment variables for API keys (e.g., ANTHROPIC_API_KEY).

4. First Interaction

Single Message Mode

Send a single message and get a response:

xopc agent -m "Explain what an LLM is in one sentence."
# or: pnpm run dev -- agent -m "Explain what an LLM is"

Interactive Mode

Start a continuous conversation:

xopc agent -i
# or: pnpm run dev -- agent -i

You'll see a You: prompt. Type messages and press Enter. Exit with Ctrl+C.

5. Running with Channels

Telegram Setup

1. Get Bot Token: Open Telegram, search @BotFather, send /newbot

2. Configure in ~/.xopc/xopc.json:

{
  "channels": {
    "telegram": {
      "enabled": true,
      "botToken": "YOUR_BOT_TOKEN",
      "dmPolicy": "allowlist",
      "allowFrom": [123456789]
    }
  }
}

3. Start Gateway:

xopc gateway
# or: pnpm run dev -- gateway

4. Chat: Open Telegram and message your bot

Web UI

Access the Web UI at http://localhost:18790 after starting the gateway.

6. What's Next?

Explore these guides to unlock more features:

Guide	Description
CLI Reference	All available commands
Configuration	Full config reference
Extensions	Extend functionality
Skills	Add domain-specific knowledge
Tools	Built-in tools reference
Channels	Multi-channel setup
Routing	Session keys and agent bindings
Models	LLM provider configuration

Troubleshooting

Common Issues

Issue	Solution
ERR_MODULE_NOT_FOUND	Run pnpm install
Cannot find module '@xopcai/...'	Run pnpm run build
Config not loading	Verify ~/.xopc/xopc.json is valid JSON
Bot not responding	Check TELEGRAM_BOT_TOKEN and bot status
API key errors	Verify environment variables are set

Getting Help

• Check Documentation for detailed guides
• Review AGENTS.md for development guide
• View logs: xopc gateway logs --follow