Skip to content

Interactive Entry xun / xuns

Installing Xun provides five console commands, all declared under [project.scripts] in pyproject.toml:

Command Entrypoint function Form Use case
xun xun:main terminal session interactive work in the current directory
xuns xun:main_serve web service browser UI, file panel, multiple sessions
xunc xun:main_container container session put xuns / xun inside a Docker sandbox
xunx xun.supervisor:main multi-user gateway many user containers behind one port
xune xun.extension:main_extension extension CLI run the command line an extension ships, directly

xun and xuns share the same session implementation and differ only in the display layer: the former uses the console Display, the latter WebDisplay.

xun: terminal session

xun                                        # enter the interactive loop, working directory is the current one
xun "write hello.py as hello world"         # start with an initial instruction
xun --non-interactive "answer in one sentence: 1+1=?"  # single run, print the result, then exit
Argument Type Default Description
instruction positional "" first instruction when the session starts
--non-interactive flag off exit after a single run instead of entering the interactive loop

Input

  • Text typed directly is a user message; /name arguments is a session command.
  • Write image attachments as [image:path or URL], several at a time: >>> [image:cat.png image:https://example.com/dog.png] compare these two images (requires vision in model.capabilities; otherwise the agent reports an error instead of silently ignoring them.)
  • Input line editing comes from prompt_toolkit: Up searches history, / completes slash commands, @ completes file paths.
  • A confirmation prompt can pop up mid-input; once you answer, the original input is restored unchanged.
  • Ctrl+C interrupts the current execution; /exit leaves the session, /long enters multi-line input mode.

Built-in session commands

/help lists the commands actually registered for the current entrypoint. Commands are registered in three groups.

Common commands (all entrypoints)

Command Purpose
/help list registered commands
/tools list registered tools
/history show the history
/tokens show token usage of the current session
/config show the configuration; /config model.name=my-model changes it (not persisted)
/compact [toolcall] compact the session; with toolcall only tool results are reclaimed
/continue continue execution
/retry resend the last message
/revise [new content] without arguments, deletes the last user message and waits for new input; with arguments, replaces it
/clear [all] clear the session history; all also removes temporary files
/yolo toggle global automatic confirmation
/extensions list extensions and their status

Workspace read/write commands (registered only on interactive entrypoints that carry built-in tools: xun, xuns)

Command Purpose
/save / /load latest\|<number> save and load session archives (experimental)
/render <file> render the current session history into a standalone HTML file and save it
/handoff package the current session into a zip handoff bundle and inject a takeover prompt

Policy commands (registered only when built-in tools are loaded)

/policy manages write permissions and the command allowlist for built-in tools. The subcommands are cmd_allowlist, cmd_allowlist_add <command>, and cmd_allowlist_remove <command>, plus the three matching path_allowlist* variants. These allowlists are runtime state and are never written to the configuration file.

Confirmation for commands and file writes

Dangerous commands are rejected outright and never reach confirmation; everything else is decided item by item from the command-line structure, and each verdict carries a brief reason. See Tool Setup for details.

xuns: web service

xuns                    # temporary workspace, one per session
xuns .                  # fixed workspace, shared by all sessions
Argument Type Default Description
workdir positional none workspace directory; if omitted, each session uses its own temporary directory
--host str localhost listen address
--port int 18960 port; 0 means the system assigns one
--token str random access token; by default a 24-byte urlsafe token is generated
--base-path str "" URL prefix, for mounting under a reverse-proxy subpath
--manage-sessions / --no-manage-sessions flag on whether creating / deleting sessions is allowed in the UI
--initial-agent / --no-initial-agent flag on whether an initial agent is created at startup

After startup the terminal prints an access URL that includes the token, in the form http://localhost:18960/chat/?session=/&token=…; once the browser opens it, the token is written to a cookie and the copy in the address bar is cleared by a single 303 redirect.

Routes

Path Content Token required
/chat/ web frontend (Vue single-page application) yes
/session/<mount>/… backend endpoints and WebSocket for that session's display layer yes
/api/sessions session list and create / delete / rename yes
/docs/ bilingual documentation shipped with the package no (GET / HEAD only)
/srv/<random key>/… temporarily hosted site from the working directory, expires after 1 hour by default the random key is part of the URL
/login token login page no

So if you only want to read the documentation, no model configuration is needed at all: run xuns --no-initial-agent, then open /docs/.

Sessions and agents

A session is one mount point plus one WebDisplay; each keeps its own event buffer, pending prompts, and file policy. A single display layer can bind several agents, switched with the drop-down at the top of the page. With xuns <directory> all sessions share one working directory; when the argument is omitted, each session gets its own temporary directory, which is cleaned up when the session is deleted. For mounting from inside a program, see Mounting WebDisplay.

Project instructions

The agent reads AGENTS.md from the working directory and loads it as a separate section of the system prompt. To turn this off, set load_project_instructions: false.