Built-in Session Entrypoints

Xun ships four console scripts (declared under [project.scripts] in pyproject.toml), one for each session shape. They differ only in where the agent runs and how it interacts with you; the core execution logic is exactly the same.

[project.scripts]
xun  = "xun:main"
xuns = "xun:main_serve"
xunc = "xun:main_container"
xunx = "xun.supervisor:main"

The four entrypoints at a glance

Command	Shape	Process location	Interaction surface	Typical scenario
xun	Terminal session	current Python process	terminal REPL (>>>)	work with the agent in the current directory, editing code and writing docs
xuns	Web service	current Python process	browser chat UI + file panel	you need browser tools, file upload/download, switching between sessions
xunc	Container session	xuns inside a Docker container	browser (port mapped to the host)	you want an isolated environment, or the host has no Python environment
xunx	Multi-user shared service	host orchestrator + one container per user	browser (routed by username prefix)	one server gives each person their own persistent environment

Both xunc and xunx run xuns inside a container, so the four entrypoints really come down to two ways of running the agent (terminal, web) plus two deployment wrappers (single container, multi-user gateway).

flowchart LR
  XUN["xun"] --> P1["current process<br/>terminal REPL"]
  XUNS["xuns"] --> P2["current process<br/>browser UI"]
  XUNC["xunc"] --> P3["one container<br/>runs xuns inside"]
  XUNX["xunx"] --> P4["one container per user<br/>runs xuns inside"]

Parameters at a glance

xunxunsxuncxunx

Parameter	Default	Description
instruction (positional, optional)	empty	first instruction; required in non-interactive mode
--non-interactive	off	run a single turn then exit, suited to scripts and CI

See xun · terminal session.

Parameter	Default	Description
workdir (positional, optional)	empty	working directory shared by all sessions; if omitted, each session gets its own temporary directory
--host	localhost	listen address
--port	18960	listen port; 0 means a random port
--token	random	access token; an empty value means one is generated automatically
--base-path	empty	URL prefix (for reverse-proxy or sub-path deployments)
--manage-sessions / --no-manage-sessions	enabled	whether sessions may be created or deleted from the UI
--initial-agent / --no-initial-agent	enabled	whether an initial agent is created; when off, only the /docs/ site is served

See xuns · web service.

Parameter	Default	Description
mount (positional, optional)	nothing mounted	host directory bind-mounted as /workspace inside the container
--copy	off	copy that directory into /workspace instead of bind-mounting it
--image	xun	image to use
--name	xun-<first 8 hex chars of md5>	container name
--network	bridge	bridge or host
--port	18960	ports to publish, comma-separated; --port "" publishes none
--env	empty	NAME=VALUE for a direct assignment, or a wildcard to forward host variables
--exec	xuns . --host 0.0.0.0 (when mounted)	command run inside the container; an empty string uses the image's default CMD

See xunc · container session.

Subcommand	Parameters	Purpose
user-add	username	add a user and generate a random token
user-del	username	delete a user
user-list	—	list users, tokens, URL prefixes and the desired state (running / paused)
pause / resume	username	freeze/thaw that user's container with all state intact (takes effect on the next reconcile pass)
upgrade	username ... / --all	mark containers for rebuild (takes effect on the next reconcile pass)
serve	--host --port --port-range --image --env --interval	run the gateway and the reconciliation loop

See xunx · multi-user service.

Which one should I pick

flowchart TD
  Q1{"need the browser UI?"} -->|no| XUN["xun<br/>terminal session"]
  Q1 -->|yes| Q2{"need isolation?"}
  Q2 -->|no| XUNS["xuns<br/>local web service"]
  Q2 -->|yes| Q3{"shared by many users?"}
  Q3 -->|no| XUNC["xunc<br/>single container"]
  Q3 -->|yes| XUNX["xunx<br/>multi-user service"]

Mapping to the Python API

Entrypoint	Equivalent call
xun	setup_agent(name="agent", default_tools=True, default_commands=True, workdir=Path.cwd()) + interactive_session(agent, instruction)
xuns	web_session(workdir=..., host=..., port=..., token=..., base_path=..., manage_sessions=..., initial_agent=...)
xunc	runs xuns ... inside a container (see src/xun/entrypoint.py::main_container)
xunx	the xun.supervisor module: UserStore + DockerManager + Supervisor + Multiplexer

When embedding Xun in your own program you can skip these scripts entirely and use setup_agent or Agent directly; see the API guide.