Installation¶

Requirements¶

Python 3.12 or newer (the code uses PEP 695 type-parameter syntax def f[T](...); TypeVar(default=...) falls back to typing_extensions on 3.12)
Linux / macOS (the bash tool is not registered on Windows, see Tool system)
An OpenAI-compatible model endpoint

Main runtime dependencies: openai, pydantic, aiohttp, fastapi, rich, jinja2, json-repair, markdown, pillow, playwright, docker, html-to-markdown, python-dotenv, puremagic, typing-extensions.

Install¶

pip install xun-agent

If you want to use the built-in browser tools, install the browser binaries once more:

playwright install          # or playwright install chromium

Installing from source¶

The web frontend assets and the documentation site are packaged into src/xun/assets/. When installing from source and you need the web UI, build the frontend first:

git clone https://github.com/MenxLi/xun.git
cd xun
make build-web      # cd web && npm i && npm run build, output written to src/xun/assets/web
pip install .

Makefile targets

Target	Purpose
`build-web`	build the Vue frontend into `src/xun/assets/web`
`build-docker`	run `build-web` first, then `docker build -t xun -f docker/Dockerfile .`
`doc`	inside a container, generate the bilingual documentation site into `site/` following `docs/AGENTS.md`
`doc-update`	the same command as `doc`, only the prompt asks to refresh and polish the existing documentation according to the most recent source changes
`doc-dist`	copy `site/` into `src/xun/assets/docs` so that `xuns` serves it at `/docs/` (if `site/index.html` does not exist it only prints a notice and skips)
`doc-clean`	delete `site/` and the packaged site directory `src/xun/assets/docs` (restoring its tracked files with `git checkout`), then delete `mkdocs.yml`; the sources under `docs/` are untouched
`test`	`uv run python -m unittest discover -s test -t . -v` (requires `uv`)

Building the Docker image¶

xunc and xunx use an image named xun:

make build-docker

The image is based on ubuntu:24.04 and preinstalls Playwright Chromium, Node, LibreOffice, the mkdocs toolchain and more. Two xun-related environment variables are fixed: XUN_HOME=/.xun (the host xun home is copied in when the container is created, taking only config.json and extensions) and _XUN_INFO_TOOL_OVERRIDE=1 (the image also sets locale, VIRTUAL_ENV, PATH and other variables it needs itself). The Dockerfile declares no ENTRYPOINT/CMD, so the image inherits ubuntu:24.04's /bin/bash; xunc passes the command to run explicitly.

Configuration¶

Xun reads its configuration from $XUN_HOME/config.json; when XUN_HOME is unset it is .xun/ under the current working directory (not ~/.xun). Write only the fields you want to change — missing fields fall back to the built-in defaults:

{
    "model": {
        "name": "my-model"
    }
}

The configuration supports ${XUN_...} placeholders whose values come from environment variables (so secrets can live in .env, which is loaded automatically via load_dotenv() when the configuration is read):

# .env
XUN_OPENAI_BASE_URL=https://api.example.com/v1
XUN_OPENAI_API_KEY=sk-...
XUN_OPENAI_MODEL=        # leave empty to use the first model reported by the server

Configuration field	Environment variable	When missing
`provider.openai_base_url`	`${XUN_OPENAI_BASE_URL}`	startup raises `RuntimeError`
`provider.openai_api_key`	`${XUN_OPENAI_API_KEY}`	startup raises `RuntimeError`
`model.name`	`${XUN_OPENAI_MODEL}`	falls back to an empty string → the model is detected automatically
`auto_confirm`	`${XUN_AUTO_CONFIRM}`	falls back to `false`

For the full field list, the merge rules and all environment variables, see Configuration.

Confirmation prompts and auto-confirm

By default, writing files and running commands that are not on the allow list require confirmation. In scripts or CI you can set XUN_AUTO_CONFIRM=true (or toggle it temporarily with the /yolo command). Auto-confirm never adds commands or paths to the allow list.

Verifying the installation¶

xun "Print the current directory and say hello"

Once you are in interactive mode:

>>> /config        # show the currently effective configuration
>>> /tools         # show the registered tools
>>> /extensions    # show extensions and their status
>>> /help          # show all commands

Non-interactive mode (single turn, suited to scripts and CI):

xun --non-interactive "Summarize README.md in one line"

Optional steps after installation¶

What you want to do	Reference
Change the model, tune temperature, set reasoning effort	Configuration
Add custom tools, hooks or commands	Extension system
Embed the agent into your own program	API guide
Deploy in a container, expose it to several people	xunc, xunx