xunc · 容器会话

在 Docker 容器里运行 xuns，宿主只负责创建容器、转发环境变量并把输出接回终端。

git clone https://github.com/MenxLi/xun.git
cd xun
make build-docker      # 先构建前端，再 docker build -t xun -f docker/Dockerfile .

xunc                   # 沙箱：容器内的临时工作区
xunc .                 # 把当前目录绑定为容器内 /workspace
xunc --copy .          # 把当前目录复制进 /workspace（不回写宿主）

参数

参数	形式	默认	说明
mount	位置参数，可选	不挂载	绑定为容器内 /workspace 的宿主目录（会先 resolve()）
--copy	开关	False	改为把该目录复制进 /workspace；未给 mount 时报错
--image	字符串	xun	使用的镜像
--name	字符串	xun-<md5前8位>	容器名；默认哈希取自 mount 路径（未挂载时取镜像名）
--network	bridge / host	bridge	bridge 会发布 --port 端口；host 共享宿主网络命名空间（macOS 上是 Docker VM 的，宿主浏览器打不开）
--port	字符串列表	18960	需要发布到宿主的端口，支持逗号分隔或多次传入；--port "" 表示不发布任何端口
--env	字符串列表	空	逗号分隔：NAME=VALUE 直接赋值；不含 = 的 token 作为通配符从宿主转发
--exec	字符串	见下	容器内执行的命令；空串表示使用镜像默认 CMD

--exec 未指定时：给了 mount 用 xuns . --host 0.0.0.0（位置参数 . 即 /workspace，会话工作区就是挂载点），否则用 xuns '' --host '0.0.0.0'（每个会话一个临时工作区）。

工作目录的三种形态

写法	容器内 /workspace	数据去向
xunc	镜像自带的空目录	容器销毁即消失
xunc .	绑定挂载（读写）	直接落在宿主目录，可回写
xunc --copy .	复制副本	容器内的修改不会回传宿主

只要给了 mount，容器的 working_dir 也会被设为 /workspace，因此容器内智能体的当前目录与挂载点始终一致。

环境变量转发

XUN_* 与 _XUN_* 总是转发进容器，无需显式声明。--env 在此基础上追加：

xunc . --env "XUN_AUTO_CONFIRM=true,_XUN_DEFAULT_MAX_ITER=384,HTTPS_PROXY"

• NAME=VALUE：直接赋值
• 裸 NAME 或 MY_*：按 fnmatch 从宿主环境转发
• XUN_HOME 不可覆盖（镜像内固定为 /.xun），强行赋值会打印告警并忽略

xun home 的复制

容器创建时会把宿主的 xun home（$XUN_HOME，未设置时为宿主当前目录下的 .xun/）复制进容器 /.xun，只取 config.json 与 extensions/（HOME_COPY_INCLUDE）——会话历史与 x/（xunx 的用户库）不会被带走。这就是为什么容器里也能读到同一份密钥占位符与扩展。

生命周期与输出

容器以 auto_remove=True、stdin_open、tty 创建，working_dir=/workspace（挂载时）。xunc 把宿主 stdin 转发进容器、把容器输出回显到宿主；Ctrl+C 之后容器被强制移除。因此浏览器里看到的 URL 是容器内 xuns 打印的：

Agents are available at the following URLs:
http://0.0.0.0:18960/chat/?session=%2F&token=...   (aka http://localhost:18960/chat/?...)

bridge 模式下宿主端口与容器端口相同（默认发布 18960），所以照抄 localhost:18960 那一条即可；--port "" 时没有可访问端口，适合纯 --exec 的一次性任务，例如本仓库生成文档的用法：

xunc . \
    --env "XUN_AUTO_CONFIRM=true,_XUN_DEFAULT_MAX_ITER=384" \
    --exec "xun --non-interactive '请按照docs/AGENTS.md的要求制作文档'" \
    --name "xun-doc" \
    --port ""

仓库的 Makefile 把这种一次性用法固化成了两条命令：make doc（首次制作双语文档）与 make doc-update（按源码最近的变动更新文档）。两者都只传 --env "XUN_AUTO_CONFIRM=true"（不像上面的示例还转发了 _XUN_DEFAULT_MAX_ITER），只有 --exec 提示词不同。

容器即用即删

xunc 的容器在退出后自动删除，容器内的临时工作区、已保存会话都会丢失。需要留存数据请使用绑定挂载（xunc .），或改用持久化的 xunx。