English | 简体中文

xopc

Turn goals into loops.
Keep what matters moving.
xopc is a self-hosted, local-first personal AI runtime connecting models, agents, durable state, workflows, automations, and every surface you use. You own the data, keys, and environment.

xopc.ai · GitHub · Documentation · Get started · Releases

Table of Contents

• What xopc is
• One runtime, four layers
• Get started
• Why xopc
• How xopc compares
• Where to chat
• Channels
• Extensions & skills
• Configuration
• Documentation
• FAQ
• Desktop app
• Contributing

---

What xopc is

xopc is not a wrapper around one model, and it is more than another chat UI. It is a self-hosted, local-first personal AI runtime that lets models, agents, data, and triggers work together in one environment.

Start with a local assistant using your own model keys. When the work becomes durable, add explicit projects and goals, capture inputs as notes, break complex work into observable workflows, and trigger follow-up with schedules or webhooks. Every surface connects to the same runtime instead of creating another isolated bot.

One runtime, four layers

Layer	What xopc provides	What it solves
Runtime & ownership	Self-hosted gateway, local state, BYOK, cloud and local models	You control data, cost, deployment, and availability
Durable state	Persistent sessions, projects, goals, notes, workspaces, and agent memory policy	Resume work without reconstructing it every time
Execution & initiative	Tools, skills, subagents, observable workflows, and scheduled/manual/webhook automations	Move from advice to execution, review, and follow-up
Access everywhere	CLI, TUI, web, desktop, iOS/Android, Telegram, WeChat, Feishu/Lark, and HTTP/SSE APIs	Use one system wherever the work happens

These pieces are composable rather than a fixed funnel: work on code in the terminal, dictate a note on mobile, inspect goals and failed runs from a project, generate a daily digest with an automation, then resume the same session from any surface.

See how the pieces form a resumable, triggerable, and inspectable loop in The Continuous Work Model.

---

Get started

Easiest start: PC desktop app

For most users, the PC desktop app is the easiest way to start: install the app, finish model setup in the UI, then chat in the built-in console. It starts the local gateway for you.

1. Download from GitHub Releases — macOS .dmg, Windows .exe, Linux .AppImage / .deb.
2. Open xopc and complete model setup.
3. Start chatting.

See PC Desktop app for install notes, build-from-source commands, and reserved screenshot/GIF/video file locations.

One-liner (30-second start — recommended)

Linux, macOS, WSL2, Termux

curl -fsSL https://xopc.ai/install.sh | bash

Windows (native, PowerShell)

Heads up: Native Windows runs xopc without WSL — CLI, gateway, TUI, and tools all work natively. Prefer WSL2? Use the bash one-liner above there too.

iex (irm https://xopc.ai/install.ps1)

The installer detects your OS, installs Node.js ≥ 22 when needed, and installs @xopcai/xopc. China mirror: add --cn (bash) or -Cn (PowerShell), or pass --registry https://registry.npmmirror.com.

Then chat immediately:

xopc onboard --quick
xopc                    # opens the local TUI

npm (already have Node.js 22+)

npm install -g @xopcai/xopc

Or with pnpm: pnpm add -g @xopcai/xopc · China mirror: npm install -g @xopcai/xopc --registry=https://registry.npmmirror.com

More commands

xopc agent -i                               # interactive CLI
xopc agent -m "Summarize the last 5 commits"  # one-shot
xopc gateway                                # web server + React console
xopc gateway service install                # OS service

From source (installer or pnpm workspace):

# installer — clone, build, and add ~/.local/bin/xopc wrapper
curl -fsSL https://xopc.ai/install.sh | bash -s -- --install-method git

# or manual checkout
git clone https://github.com/xopcai/xopc.git && cd xopc
corepack enable && pnpm install && pnpm run build
pnpm exec xopc onboard

Windows git install: & ([scriptblock]::Create((irm https://xopc.ai/install.ps1))) -InstallMethod git

Requirements: Node.js ≥ 22 (the one-liner handles this). Use pnpm when hacking from a git clone. More install options on xopc.ai and Getting started.

---

Why xopc

• 🧠 Durable state, not one context window — Sessions, projects, goals, notes, workspaces, and run history have explicit ownership and can be resumed.
• 🏠 Runs in your environment — Config and local state live under ~/.xopc/ by default; you choose deployment, backups, and remote access.
• 🔑 Bring your own keys — OpenAI, Anthropic, Google, DeepSeek, Ollama, LM Studio, vLLM, and 20+ providers. Mix cloud and local models.
• ⚙️ Executes and triggers work — Tools and workflows perform tasks; scheduled, manual, and webhook automations run agents or workflows later.
• 📡 One runtime, many surfaces — Desktop, terminal, web, mobile, and messengers share agents, sessions, and project state.
• 🧩 Explicit capability boundaries — Each agent can have its own identity, model roles, workspace, tool policy, skills, memory, and boundaries, then grow through extensions.

How xopc compares

xopc is not another chat UI. It is the local-first system layer for people who want one assistant to remember goals, keep state, run automations, and stay reachable across surfaces.

Product	Best at	Why use xopc too
Codex	Software development in terminal, IDE, and cloud tasks	xopc is broader than repo work: long-running goals, BYOK/local models, scheduled loops, gateway APIs, desktop/web/mobile, and messengers share one local state.
Claude Code	Project-level coding: codebase navigation, edits, tests, git workflows	xopc is a personal AI runtime for coding and long-running work; it coordinates models, channels, skills, workflows, and automations outside one codebase.
Qoder / QoderWork	Agentic coding platform plus local-first office work companion	xopc is open-source and hackable, with explicit local state under ~/.xopc/, configurable providers, self-hosted gateway, and extension points.
WorkBuddy	Office deliverables such as reports, decks, spreadsheets, research, and data analysis	xopc is for users who want to own the runtime: bring your own keys, mix local/cloud models, wire channels, and keep long-term project context locally.

Choose xopc when you want a self-hosted, long-term AI assistant that is not locked to one vendor, one IDE, one chat surface, or one task type. See the full comparison in Comparison.

---

Where to chat

Surface	How	Best for
PC Desktop	GitHub Releases	Easiest start: native app + embedded gateway console
TUI	xopc or xopc tui (remote: xopc tui --url …)	Full keyboard, streaming, fastest terminal path
CLI	xopc agent -i / xopc agent -m "…"	Scripts and minimal TTY
Web	xopc gateway → open console URL	Chat, settings, logs in the browser
Mobile	mobile app + QR gateway pairing (mobile app, remote access)	Chat, record notes, and capture ideas from iOS/Android while the agent keeps running on your computer
Messengers	channels.* + gateway	Telegram, WeChat, Feishu/Lark

---

Channels

Configure under channels.* in ~/.xopc/xopc.json. IM bots need a running gateway; WeChat login runs on the gateway host.

Channel	Config	Notes
Telegram	channels.telegram	Multi-account, streaming, policies
WeChat	channels.weixin	QR login on gateway host
Feishu / Lark	channels.feishu	Bot / webhook per docs

Full reference: Channels · Configuration.

---

Extensions & skills

xopc skills install <name>       # SKILL.md domains
xopc extensions install <pkg>    # tools, channels, UI panels
xopc extensions dev ./my-extension

Guides: Extensions · Skills. Gateway UI extensions: @xopcai/xopc/extension-ui-sdk (packages/extension-ui-sdk/).

---

Configuration

Default: ~/.xopc/xopc.json. A minimal skeleton:

{
  "providers": { "deepseek": "${DEEPSEEK_API_KEY}" },
  "agents": { "default": "main", "list": [{ "id": "main", "models": { "roles": { "deep": { "model": "deepseek/deepseek-v4-flash" } } } }] }
}

Full reference: Configuration. Add channels.* for IM, or browser tools (Playwright Chromium) when needed.

---

Documentation

Guide	Description
Getting started	Install, onboard, first chat
The Continuous Work Model	How state, execution, and triggers form resumable, inspectable work loops
Projects, Goals, and Notes	Organize long-running work with explicit objects instead of one huge transcript
Configuration	xopc.json reference
CLI	Commands and flags
Channels	Telegram, WeChat, Feishu
Architecture	How pieces fit together
Workflows	Fan-out subagents, board UI, scripts

Also: Tools · Mobile app · Voice · Remote access

---

FAQ

Is xopc a hosted service? — No. Everything runs on your machine under ~/.xopc/.

Do I need a paid cloud model? — No. Bring your own keys, or use local models (Ollama, LM Studio, vLLM).

What is the fastest way to try it? — Desktop app for GUI users, or xopc onboard --quick && xopc for terminal.

How is this different from another chat UI? — Chat is only one surface. xopc also manages agents, persistent sessions, projects/goals, notes, workspaces, workflows, automations, and multi-surface access.

Can I use it from my phone or messengers? — Yes. Pair the mobile app by QR code, or configure Telegram, WeChat, or Feishu/Lark via the gateway.

Have a question? — Ask on GitHub Discussions.

---

Security

Treat inbound IM messages as untrusted. Prefer pairing or allowlist for DMs. Keep gateway bind addresses and tokens private. See Security for details.

---

Contributing

pnpm install && pnpm run dev    # CLI via tsx
pnpm run dev:gateway            # dev gateway uses ~/.xopc-dev + info logs
pnpm run build && pnpm test && pnpm run lint

AGENTS.md · CONTRIBUTING.md

Issues: Bug report · Feature request · Q&A Discussions · Security advisory (not public issues)

Tech stack: TypeScript, Node.js ≥ 22, pnpm workspace. Built-in LLM layer via @earendil-works/pi-ai, React gateway console, Electron desktop.

Credits

• LLM layer: @earendil-works/pi-ai · Agent runtime: @earendil-works/pi-agent-core
• Inspired by openclaw/openclaw and NousResearch/hermes-agent

---

_{Made with care by xopcai · xopc.ai}