Getting Started

Use this page as the full map: what runs, setup modes, surfaces, and where to go next.

If you have not tried xopc yet, start with the PC Desktop app for the friendliest path, or First 5 Minutes for a terminal-first path — both cover the actual install commands step by step.

Your first run needs only model → agent → session. Add a Project / Goal when work must survive across sessions, Notes / Workspace for durable material, and a Workflow / Automation when execution repeats or fans out. See The Continuous Work Model for the complete model.

What xopc runs

xopc is one package with several surfaces:

Surface	Entry point	Requires gateway
CLI one-shot	xopc agent -m "..."	No
Interactive CLI	xopc agent -i	No
Local TUI	xopc or xopc tui	No
PC Desktop app	GitHub Releases	Bundled gateway
Gateway console	xopc gateway, then open the printed URL	Yes
Gateway TUI	xopc tui --gateway or xopc tui --url ...	Yes
Channels	Telegram, Weixin, Feishu/Lark configs under channels.*	Yes

Requirements

• Node.js 22 or newer for the CLI package.
• At least one model provider key, local model server, or configured OpenAI-compatible endpoint.
• pnpm only when building from this repository.

Setup modes

Goal	Command	Notes
Fast local trial	xopc onboard --quick	Model credentials only; skips gateway and channels
Guided first run	Web console onboarding or xopc onboard	Model first, optional personal profile, then chat
Create base files	xopc setup	Creates config/workspace skeleton only
Configure a model later	xopc providers set-key <provider> and xopc models set <provider>/<model>	See Configure your first model

Configuration is stored in ~/.xopc/xopc.json by default. Override it with XOPC_CONFIG or XOPC_CONFIG_PATH.

Choose the next surface

Need	Start here
Easiest first run	PC Desktop app
Fastest terminal first run	First 5 Minutes
Browser chat, settings, logs	Gateway
Telegram bot	Connect Telegram
Mobile access	Mobile app and Remote access
Another dedicated agent	Create a second agent
Gateway on another device	Expose the gateway safely
Broken setup	Diagnose setup issues

Core paths

Topic	Page
CLI commands	CLI
TUI behavior	Terminal UI
Configuration fields	Configuration and Configuration reference
Models and providers	Models
Channels	Channels
Tools	Tools
Skills	Skills
Extensions	Extensions
Session routing	Routing system
Projects, goals, and notes	Projects, Goals, and Notes

Development from source

git clone https://github.com/xopcai/xopc.git
cd xopc
pnpm install
pnpm run dev -- --help
pnpm run dev:init        # optional: create isolated ~/.xopc-dev state
pnpm run dev:gateway     # gateway from source using ~/.xopc-dev and info logs
pnpm run build

Use pnpm run dev:gateway -- --port 18791 (or another option after --) if your normal gateway is already using the default port.

Common checks:

pnpm test
pnpm run typecheck
pnpm run docs:build

Troubleshooting

Symptom	Check
Config does not load	xopc config validate
Model calls fail	xopc models status and provider credentials
Gateway does not respond	xopc gateway status and xopc gateway health
Channel does not reply	xopc channels show <channel> and gateway logs
Unknown local failure	xopc doctor, then xopc logs tail