Installation¶

Requirements¶

Python 3.12 or later (the source uses PEP 695 syntax)
An OpenAI-compatible model service endpoint
Playwright browsers for the default browser tool; Git for the apply_patch tool

Install from PyPI¶

pip install xun-agent

# The default browser tool depends on Playwright browsers
playwright install

# Model service configuration
export XUN_OPENAI_BASE_URL="https://api.example.com/v1"
export XUN_OPENAI_API_KEY="your-api-key"
export XUN_OPENAI_MODEL="your-model"

# Interactive session
xun

# Or the web service
xuns .

The model name may be left empty

When XUN_OPENAI_MODEL is not set, Agent.initialize() calls models.list(), takes the first available model, and prints a note. For the full meaning of every field, see Config Fields and Settings.

After installation, confirm the entrypoint commands and the version:

xun -h
xune            # lists extensions that declare a CLI; reports empty if there are none
python -c "from xun import xun_version; print(xun_version())"

Install from Source¶

The web frontend build is shipped with the package, so it must be compiled once before the build:

git clone https://github.com/MenxLi/xun.git
cd xun
make build-web      # equivalent to cd web && npm i && npm run build
pip install .

Frontend development mode (backend and Vite started together):

cd web
npm install
npm run dev         # http://127.0.0.1:5173

Build the Docker Image¶

xunc and xunx depend on the same image, which already includes Python, Node, Rust, ffmpeg, and the Playwright browsers.

make build-docker   # runs make build-web first, then docker build -t xun -f docker/Dockerfile .

Once the image is built, run in a sandbox:

xunc                # temporary workspace inside the container
xunc .              # bind-mount the current directory as /workspace
xunc --copy .       # copy it into /workspace instead
xunc --exec "xun"   # run the command-line entrypoint in the container instead of the web service

For the complete reference of arguments, the multi-user gateway, and environment forwarding, see Sandbox and Multi-user xunc / xunx.

Documentation Ships with the Package¶

The built site is copied into src/xun/assets/docs/, so the PyPI distribution carries bilingual documentation. Start xuns / xunc and open /docs/ to browse it. When no model service is configured, use:

xuns --no-initial-agent
# then open http://localhost:18960/docs/

To regenerate the site (requires Docker and the installed image), see README-BUILD-DOCS.md in the repository root.

Configuration File Location¶

Configuration is read from $XUN_HOME/config.json; when XUN_HOME is unset the path is ./.xun/config.json. Extensions, extension data, and session archives live under the same directory:

$XUN_HOME/
├── config.json          # agent configuration
├── extensions/          # extension source files, see the plugin development guide
├── extension_data/      # private data directory for each extension
├── skills/              # skill packages for the Skills extension
├── conversation/        # session archives for /save and /load
└── x/                   # xunx user database

For field-level details, see Config Fields and Settings.