Docker 镜像

拉取或构建 nevoflux/agent 镜像——构建参数、运行模式、镜像环境变量，以及实时观看（VNC/noVNC）。

拉取官方镜像

自 v0.3.13 起，每次发布都会把 nevoflux/agent 推送到 Docker Hub，并同时构建 amd64 与 arm64，因此 Apple Silicon 或 Graviton 宿主拉到的是原生镜像：

docker pull nevoflux/agent:0.3.16     # 指定某个发行版
docker pull nevoflux/agent:latest     # 最新已发布的版本

每个已发布的标签都把一个 browser 发行版与随其一同发布的 agent 二进制配成一对，并且只在该发行版正式公开之后才推送——因此只要标签存在，就一定对应一个你能下载到的发行版。

生产环境请固定版本。 下次发布时 latest 会在你脚下发生变化，而 0.3.16 不会。

自行构建

只有在需要定制构建时才用得上——额外内置 pack、指定 agent/browser 的配对，或使用未发布的二进制。镜像由 agent 仓库的 deploy/headless/ 目录构建，会从 GitHub 下载官方预编译发行版——无需本地编译：

docker build -t nevoflux/agent:custom deploy/headless      # amd64 或 arm64

构建参数

参数	默认值	含义
`AGENT_VERSION`	`latest`	agent 发行版标签——带前导 `v`（如 `v0.3.16`）。
`BROWSER_VERSION`	`latest`	browser 发行版标签——不带前导 `v`（如 `0.3.16`）。
`TARGETARCH`	宿主架构	`amd64` → `x86_64` 资产，`arm64` → `aarch64`。由 `docker buildx --platform` 设定。
`PACK_REPOS`	空	空格分隔、要打包内置的 pack（见内置 packs）。
`INSTALL_GBRAIN`	`1`	安装并启用 GBrain 知识库（设为 `0` 则完全跳过）。
`GBRAIN_PIN`	`github:garrytan/gbrain#<pin>`	固定 GBrain 版本。
`LLM_PROVIDER`	`anthropic`	写入镜像内置 `[llm]` 配置的服务商（见下文）。

为可复现构建固定版本。 latest 可能把较新的 agent 与较新的 browser 配在一起， 不可复现。请同时固定两者：
docker build -t nevoflux/agent:0.3.16-custom \
  --build-arg AGENT_VERSION=v0.3.16 --build-arg BROWSER_VERSION=0.3.16 \
  deploy/headless

构建时会用 checksums-sha256.txt 对 agent 压缩包做校验和验证。

多架构

TARGETARCH 选择下载 x86_64 / aarch64。在 arm64 宿主上——或使用 docker buildx build --platform linux/arm64——它会自动拉取 arm 构建。

从本地（未发布）二进制构建 —— `Dockerfile.local`

要测试本地构建或未发布的守护进程/浏览器改动（尚未进入发行版的特性），把四个产物暂存到 deploy/headless/，再构建基于 COPY 的变体：

# 暂存到 deploy/headless/：dist/nevoflux/（浏览器打包目录树）、
# nevoflux-agent（构建好的守护进程）、libonnxruntime.so（v1.24.x）、models/fastembed/
docker build -f deploy/headless/Dockerfile.local -t nevoflux/agent:local deploy/headless

在 Compose 中设置 build.dockerfile: Dockerfile.local。

镜像内置了什么

GBrain（知识库）—— 默认开启

当 INSTALL_GBRAIN=1（默认）时，构建过程会：

安装 bun 并将 bun add <GBRAIN_PIN> 装到 ~/.nevoflux/brain-tool，并创建 brain 目录 ~/.gbrain；
写入 ~/.config/nevoflux/config.toml，包含 [knowledge_base.brain] enabled = true 和 [llm] provider = <LLM_PROVIDER>。

GBrain 的 LLM 调用会经由进程内网关路由到该服务商，因此无需单独的 GBrain 密钥——运行时只需该服务商的 *_API_KEY（如 ANTHROPIC_API_KEY）。

# 默认：gbrain 开启，服务商 anthropic（运行时需要 ANTHROPIC_API_KEY）
docker build -t nevoflux/agent:latest deploy/headless

# 换服务商、固定版本或禁用：
docker build \
  --build-arg LLM_PROVIDER=openai \      # 然后运行时设置 OPENAI_API_KEY
  --build-arg GBRAIN_PIN=github:garrytan/gbrain#<sha> \
  --build-arg INSTALL_GBRAIN=0 \         # 完全跳过 gbrain
  -t nevoflux/agent:latest deploy/headless

如果你挂载自己的 config.toml，请保留 [knowledge_base.brain] enabled = true 以及可用的 [llm] 服务商，否则 GBrain 不会启动。没有可用服务商时，浏览器任务与 brain 存储仍可工作，但 GBrain 的 LLM 综合（brain_think）不会。

内置 packs

pack 安装走守护进程的 RPC（没有离线安装器），因此 pack 会在构建时克隆进镜像，并在守护进程启动后于启动时安装。即便数据目录是临时的（tmpfs）也可用——每次启动都会从内置克隆重新应用 pack。

docker build -t nevoflux/agent:latest \
  --build-arg PACK_REPOS="owner/pack-repo https://github.com/x/y.git" \
  deploy/headless
# 克隆到 /opt/packs/<name>；守护进程开始监听后，entrypoint 运行 `pack install`。

PACK_REPOS 以空格分隔——可写 GitHub owner/repo 简写或完整 git URL。为空则不安装任何 pack。pack 格式参见 Packs。

运行 —— 服务模式（已加固）

docker run --rm -p 8080:8080 \
  --read-only --tmpfs /tmp --tmpfs /var/nevoflux/data \
  --tmpfs /home/nevo/.gbrain --tmpfs /home/nevo/.cache \
  --cap-drop ALL --security-opt no-new-privileges \
  --pids-limit 512 --memory 4g --cpus 2 \
  -v "$PWD/out:/work" \
  -v nevoflux-base-profiles:/base-profiles:ro \
  -e ANTHROPIC_API_KEY="$ANTHROPIC_API_KEY" \
  nevoflux/agent:latest

/work 是镜像的工作目录，也是声明的卷。注意任务结果（result.json、debug-bundle/、产物）写在 NEVOFLUX_PROFILE_WORK 下的任务工作区中，而镜像让它保持默认值 /tmp/nevoflux-profiles——见任务 API → 状态与结果。
base-profiles（只读）存放预先登录的模板配置，按任务克隆。
容器以只读运行；守护进程只写入上面的 tmpfs 挂载。
自 v0.3.14 起，镜像也把 /var/nevoflux/data 声明为 VOLUME（远程控制端需要它持久化）。对任务服务请继续像上面那样把它挂为 tmpfs——否则 docker run 会为它创建一个匿名卷。

默认命令为 --daemon --headless --http-addr 0.0.0.0:8080。这一个端口同时提供任务 API 以及 OpenAI（Chat Completions、Responses、模型列表）、Anthropic Messages 与 A2A 端点 ——除非设置 NEVOFLUX_A2A_TOKEN（且它只覆盖 A2A 路由），这些都无需认证。只在所有调用方都可信的地方发布它。要加上 MCP、ACP、管理 API 或专用端口，请覆盖命令——见任务 API → 接口与端口。

浏览器引擎

自 v0.3.15 起，linux/amd64 发行版二进制——因而 amd64 镜像——内置了一个进程内浏览器引擎（nevoflux-skiff），并默认使用它：浏览器工具先在守护进程内提供，只有当该引擎做不到所要求的事情时，任务才会升级到真正的无头浏览器。linux/arm64 二进制没有内置它，始终使用真正的浏览器。

NEVOFLUX_BROWSER_BACKEND 可显式选择：

值	引擎
未设置 / `auto`	先进程内引擎，必要时升级到真实浏览器（amd64 默认）
`browser`（或 `nevoflux`）	真正的无头浏览器，不尝试进程内引擎
`extension`	浏览器扩展路径，即 v0.3.15 之前的行为（arm64 默认）
`skiff`	只用进程内引擎——它做不到的就失败（用于衡量覆盖面）

当前构建无法满足的值（例如在 arm64 上设 skiff）或拼写错误，会记录一条错误并回落到 extension。进程内引擎的实际影响：由它处理的任务不会启动浏览器，因此在 VNC 上没有东西可看；MCP 也会在没有会话模式的情况下列出 browser_* 工具。若需要两种架构行为一致，请设置 NEVOFLUX_BROWSER_BACKEND=browser。

实时观看（VNC / noVNC）

设置 NEVOFLUX_VNC=1（并提供密码文件）即可实时观看运行。届时镜像会运行 x11vnc （:5900 上的原始 VNC）以及 websockify（在 :6080 上提供 noVNC）：

docker run --rm -p 8080:8080 -p 6080:6080 -p 5900:5900 \
  -e NEVOFLUX_VNC=1 -e NEVOFLUX_VNC_PASSWD=/etc/nevoflux/vncpasswd \
  -e ANTHROPIC_API_KEY="$ANTHROPIC_API_KEY" \
  nevoflux/agent:latest
# 在任意浏览器中观看：http://localhost:6080/vnc.html
# 或用原生 VNC 客户端：localhost:5900

环境变量	作用
`NEVOFLUX_VNC`	`1` 启用原始 VNC（`:5900`）+ noVNC（`:6080`）。默认关闭。
`NEVOFLUX_VNC_PASSWD`	VNC 密码文件路径（默认 `/etc/nevoflux/vncpasswd`）。
`NEVOFLUX_VNC_VIEWONLY`	`1` = 仅观看、不可输入——这样不会干扰自动化。

生产环境请关闭 VNC。 原始 VNC / noVNC 端口是一个远程控制面。仅可在带认证的 HTTPS 代理或 SSH 隧道之后暴露。

镜像环境变量

以下已烘焙进镜像（你很少需要改动）：

环境变量	值	用途
`NEVOFLUX_DATA_DIR`	`/var/nevoflux/data`	守护进程锁 / 端口 / 数据库（挂为 tmpfs）。
`NEVOFLUX_BROWSER_BIN`	`/opt/nevoflux/nevoflux`	内置浏览器二进制。
`NEVOFLUX_BASE_PROFILES`	`/base-profiles`	读取 base 登录配置的位置。
`DISPLAY`	`:99`	Xvfb 虚拟显示。
`HOME`	`/home/nevo`	非 root 家目录（GBrain 与缓存都在此）。
`HF_HUB_OFFLINE`	`1`	向量嵌入离线运行（模型已内置）。
`MOZ_DISABLE_CONTENT_SANDBOX`	`1`	容器内浏览器所需。

可以自行设置的运行时开关：

环境变量	作用
`NEVOFLUX_BRAIN_ENABLED`	（v0.3.14）设为 `0` / `false` / `no` 可在不重新构建的情况下为该容器关闭 GBrain：entrypoint 跳过 brain 初始化（否则启动时可能最多等待 40 秒），守护进程不启动 `gbrain serve`，也不向 agent 提供 brain 工具。`1` / `true` / `yes` 强制开启；未设置则遵循 `config.toml`。
`NEVOFLUX_CONFIG`	（v0.3.16）用来替代 `~/.config/nevoflux/config.toml` 的 `config.toml` 路径——例如挂载在 `/etc/nevoflux/config.toml` 的只读文件。空值视为未设置。
`NEVOFLUX_PROFILE_WORK`	每任务配置克隆与任务工作区的位置（默认 `/tmp/nevoflux-profiles`）。
`NEVOFLUX_BROWSER_BACKEND`	浏览器引擎——见上文。

启动顺序

entrypoint（在 tini 之下）依次运行：dbus → Xvfb →（可选 VNC）→ GBrain 初始化（NEVOFLUX_BRAIN_ENABLED 关闭时跳过）→ 守护进程。在守护进程模式下，它会先后台启动守护进程，待其开始监听后安装内置 pack，然后交接控制权（转发 SIGTERM/SIGINT 以干净关闭）。非守护进程调用（如 config、pack）则直接运行。

Docker 镜像

本页目录