Installation

zqagent has two installation forms: the command-line tool (CLI) and the desktop app. This page covers CLI installation, upgrade, and uninstallation.

Don't want to use the command line? See the desktop app and download the installer to use it via the GUI.

Fastest: one-line installation (Linux / macOS)

curl -fsSL https://agent.cd-zq.com/install.sh | sh
# 服务器上建议用 root 执行，才能装成开机自启服务
curl -fsSL https://agent.cd-zq.com/install.sh | sudo sh

The script reads the official version manifest, downloads the single-file executable for the matching architecture, verifies the SHA-256, and installs it into PATH. No preinstalled Node is required. It installs to /usr/local/bin by default (when writable) or ~/.local/bin. It supports Linux (x64 / arm64) and macOS (Intel x64 / Apple Silicon arm64).

After installation, it automatically registers as a boot-start service (Linux systemd / macOS launchd; automatically restarts after crashes), and prints the current status and three usage methods:

Purpose	Method
GUI	Open http://127.0.0.1:8787 in a browser
CLI	zqagent (enter /connect to configure the model)
Remote management	Connect directly with a Hub account: zqagent link --hub https://hub.cd-zq.com --username <邮箱/手机号> --password '<密码>' (an enrollment code can also be used)

Machines with a terminal will be asked at the end of installation whether to enroll in Hub: simply enter the Hub-registered email/phone and password; the password is not echoed. For automation scenarios, you can include the account directly in the installation command (it is recommended to pass the password via an environment variable):

# 隐藏输入密码（不回显、不进 shell 历史）
read -rsp 'Hub 密码：' ZQAGENT_HUB_PASSWORD; echo
curl -fsSL https://agent.cd-zq.com/install.sh | sudo sh -s -- \
  --username you@example.com --password "$ZQAGENT_HUB_PASSWORD"

# 或使用一次性接入码（15 分钟有效）
curl -fsSL https://agent.cd-zq.com/install.sh | sudo sh -s -- --code <接入码>

If you do not want to enroll during installation, add --no-enroll; you can run zqagent link later to complete enrollment.

When run as non-root, or when there is no systemd in the container, service setup is skipped and a foreground startup command is provided; if you need pure CLI, add --no-service.

Can be run repeatedly: if already installed and up to date, it will not download again and only reports the current status (version, whether the service is running, whether the local address is accessible, whether Hub is enrolled, and the auto-update channel); if a new version is available, it upgrades automatically and restarts the service.

Common parameters (passed via sh -s --):

# 换端口 / 监听地址 / 数据目录
curl -fsSL https://agent.cd-zq.com/install.sh | sudo sh -s -- --port 9000 --host 0.0.0.0

# 装到自定义目录
curl -fsSL https://agent.cd-zq.com/install.sh | sh -s -- --bin-dir ~/bin

# 只装 CLI，不装开机自启服务
curl -fsSL https://agent.cd-zq.com/install.sh | sh -s -- --no-service

# 安装完成后用 Hub 账号接入（也可用 --code <接入码>）
read -rsp 'Hub 密码：' ZQAGENT_HUB_PASSWORD; echo
curl -fsSL https://agent.cd-zq.com/install.sh | sudo sh -s -- \
  --username you@example.com --password "$ZQAGENT_HUB_PASSWORD"

# 跳过安装尾声的接入询问
curl -fsSL https://agent.cd-zq.com/install.sh | sudo sh -s -- --no-enroll

# 已安装时强制重新下载覆盖
curl -fsSL https://agent.cd-zq.com/install.sh | sh -s -- --force

# 强制走 npm
curl -fsSL https://agent.cd-zq.com/install.sh | sh -s -- --npm

# 不上报匿名安装统计
curl -fsSL https://agent.cd-zq.com/install.sh | sh -s -- --no-telemetry

The one-line script targets macOS / Linux; for Windows, download the single-file exe directly (the target machine does not need Node), or install via the npm method below.

About installation telemetry: After a successful installation, an anonymous record is reported to our self-hosted telemetry service (version, platform, architecture, and installation method only) to understand actual usage on each platform. It contains no username, installation path, IP, or any personally identifiable information, and does not use cookies. If you do not want this, add --no-telemetry or set ZQAGENT_NO_TELEMETRY=1 to disable it completely.

macOS notes

• Chip architecture: Intel (macos-x64) and Apple Silicon (macos-arm64) each download the corresponding artifact.
• Boot start: Installing as root registers a LaunchDaemon (/Library/LaunchDaemons/com.zqagent.node.plist, starts at boot); installing as a regular user registers a LaunchAgent (~/Library/LaunchAgents/, starts after login). The plist has KeepAlive, so if the process exits, launchd immediately restarts it.
• Automatic updates: Same as Linux—the service silently downloads and verifies the signature against the manifest, replaces the binary when idle and exits, and launchd starts the new version; zqagent update --status shows the managed status and last check time.
• Uninstall: sudo sh -s -- uninstall. It also cleans up the system-level Daemon and the Agent of the user who invoked sudo; the data directory and binary are retained, and repeated execution does not error.
• Single instance: When reinstalling as root, the user's LaunchAgent is removed first to avoid the system-level and user-level instances competing for the same port.

Default data directory: for regular users, ~/Library/Application Support/zqagent; when installed as root, /var/root/Library/Application Support/zqagent.

The single-file artifacts for both macOS architectures are released with each version, so no preinstalled Node is required during installation. If a manifest is missing the artifact for the current architecture, the script automatically falls back to npm (requires Node ≥ 18.17); if the npm global directory is not writable, it installs to ~/.local and shows a prompt.

Automatically switch ports when the port is in use

The default port 8787 is often already occupied by another service on development machines. The installation script checks the port before registering the service; if occupied, it increments one by one (8788, 8789...), prints each attempt, and generates the service configuration with the final port:

→ 检查端口 8787 是否可用 ...
! 端口 8787 已被其它进程占用
→ 尝试端口 8788 ...
! 已自动改用端口 8788（原定 8787 被占用）
  本地控制台：http://127.0.0.1:8788

The node process itself has the same protection: if the port is still occupied when the service starts, it automatically switches to the next available port and explains this in the log. The actual port is written to the server-port file in the data directory, and both the installation script and zqagent update --status report the address based on it.

If the port is occupied by this node itself (the service is already running), the script reuses that port and does not start another instance. To fix the port, use --port <端口>; if 20 consecutive ports starting from the initial port are all occupied, it reports an error and exits.

Windows single-file (no Node installation required)

The Windows artifact is a single zqagent.exe; the target machine does not need Node/npm.

System requirements: Windows 10 / Server 2016 or later (64-bit x64 or ARM64 only). Windows 7, 8, 8.1 and Server 2008 R2 / 2012 cannot run it—the missing system APIs cannot be resolved by installing the C++ runtime; see Supported Windows versions for details.

1. Download the artifact matching your architecture (the target machine does not need Node/npm):

   Architecture	Applicable to	Download
   x64	Most Windows systems	zqagent-windows-x64

   The filename includes the version number and build time; links automatically point to the current release version as the site is built. For the full manifest, see https://agent.cd-zq.com/downloads/zqagent/stable.json (binaries.windows-x64.url). Windows ARM64 currently has no artifact; use the x64 version (Windows will run it under emulation).

2. Place it in any directory (for example %LOCALAPPDATA%\zqagent\) and open PowerShell or cmd to run:

   .\zqagent-windows-x64-v<版本>-<构建时间>.exe

   After the first launch, enter /connect to configure the model and you can start using it.

3. To run zqagent directly: add that directory to the user PATH ("System Properties → Environment Variables"), and rename the file to zqagent.exe. Command-line method (setx truncates an overly long PATH):

   setx PATH "%PATH%;%LOCALAPPDATA%\zqagent"

Run it persistently as a remotely manageable node:

zqagent.exe serve --port 8787 --data-dir "%APPDATA%\zqagent"

To start at boot, create a "Run at logon" task with Task Scheduler: set the program to the absolute path of the exe, and the arguments to serve --port 8787 --data-dir "%APPDATA%\zqagent".

• Windows has no systemd / launchd, so the single-file build does not enable automatic updates (after replacing itself, there is no service manager to start it). Upgrade method: stop the process → download the new exe and overwrite → restart.
• The artifact is not Authenticode-signed (injecting SEA would break node.exe's built-in signature), so SmartScreen may prompt on first run; re-sign with signtool before official distribution.
• The CLI has ripgrep built in; there is no need to install rg separately.

System requirements

Item	Requirement
Operating system	macOS / Linux / Windows. Windows requires 10 / Server 2016 or later (desktop app requires 10 1709+), see Supported Windows versions for details
Node.js	≥ 18.17 (required only for npm installation; the Linux / macOS / Windows single-file packages include the runtime)
Network	Able to access agent.cd-zq.com (single-file installation) or public npm registry.npmjs.org (npm installation)

Subcommands: manage an installed node

install.sh is also a management tool. In addition to installation, it supports the status / logs / restart / rollback / print-config subcommands (add sudo when needed):

sudo sh -s -- status        # 版本、服务、本地地址、远程接入、自动更新
sudo sh -s -- logs          # 跟踪节点日志
sudo sh -s -- restart       # 重启服务
sudo sh -s -- rollback      # 回滚到上次自动更新前的版本
sudo sh -s -- print-config  # 只打印将使用的配置，不执行任何动作
sudo sh -s -- uninstall     # 卸载服务（数据目录与二进制保留）

When executing via a pipe, place the subcommand after sh -s --:

curl -fsSL https://agent.cd-zq.com/install.sh | sudo sh -s -- status

If the script has already been downloaded, pass it directly as an argument: sudo sh install.sh status.

The installation script will:

1. Read the latest version from the official manifest and download the corresponding binary by platform/architecture
2. Verify SHA-256 and the version number
3. Automatically obtain the signature verification public key (you can also specify it explicitly with --pubkey)
4. Install to /usr/local/bin/zqagent (or ~/.local/bin)
5. Set up as a service: systemd on Linux, launchd on macOS

So a single command is enough; there is no need to manually find the public key.

Install with configuration (port, data directory)

curl -fsSLO https://agent.cd-zq.com/install.sh
sudo sh install.sh --port 8787 --data-dir /srv/zqagent

Specify the public key yourself (optional)

If --pubkey is not passed, the script automatically obtains it from $BASE_URL/update-public.b64. This file comes from the same source as the update manifest, so this default trust model relies on the site's HTTPS and domain not being compromised. For stronger assurance, save an out-of-band copy of the public key and pass it explicitly during installation:

sudo sh install.sh --pubkey "$(cat /path/to/update-public.b64)"

An explicitly provided public key takes precedence, and the script will not overwrite it over the network; an invalid format causes an immediate error and exit.

Parameter	Description	Default
--port <n>	Listening port	8787
--host <addr>	Listening address	127.0.0.1
--data-dir <dir>	Data directory	Linux ~/.zqagent_data; macOS ~/Library/Application Support/zqagent (logs follow the data directory)
--pubkey <key>	Public key for automatic update signature verification	Automatically obtained from $BASE_URL/update-public.b64
--service-name <n>	systemd unit name	zqagent
--label <name>	launchd job name	com.zqagent.node
--channel <name>	Update channel	stable
--version <x.y.z>	Specify version	Latest version in the manifest
--no-service	Install only the binary	—

Windows: use the desktop app; inside WSL, you can install using the Linux method above.

Installing on a remote server

You don't need to log in to the server first; you can push the installation from your local machine over SSH. The server only needs curl and sudo, and does not need Node/npm—the downloaded single-file binary includes the runtime.

ssh deploy@your-server \
  'curl -fsSL https://agent.cd-zq.com/install.sh | sudo sh'

When you need a custom port or data directory, download first and then execute (parameters cannot be passed through a pipe):

ssh deploy@your-server '
  curl -fsSLO https://agent.cd-zq.com/install.sh &&
  sudo sh install.sh --port 8787 --data-dir /srv/zqagent
'

After installation, the same install.sh status|logs|restart|rollback subcommands are available, and subsequent upgrades are completed automatically by the node according to the manifest (see the next section).

The install-node.sh address published before the merge (/downloads/zqagent/install-node.sh) will continue to serve a synchronized copy of the same content, so existing scripts do not need to be modified; new scripts should use install.sh consistently.

Upgrading a single-file installation

A node installed from a single file updates automatically: it silently downloads new versions, and when no tasks are running, replaces itself and restarts. See Starting a Node · Automatic Updates.

To check manually:

zqagent update --check     # 是否有新版本
zqagent update --status    # 当前版本、通道、上次检查

Package registry

The @zqagent series of packages is published on public npm (https://registry.npmjs.org/). No registration or account application is required; you can install directly using npm's default registry.

If your local machine uses a domestic mirror as the default npm registry (such as registry.npmmirror.com), installation still works—the mirror syncs automatically after release; neither requires configuring a separate scope for @zqagent.

npm installation (developers / existing Node users)

Suitable for scenarios where you need to use zqagent on a development machine at any time; it is not managed by automatic updates, and upgrades are handled via npm.

# 使用本机默认源（推荐）
npm i -g @zqagent/core

# 或临时指定公共 npm
npm i -g @zqagent/core --registry=https://registry.npmjs.org/

Version channels

Public npm currently publishes only stable versions (the latest tag):

Channel	Installation command	Description
Stable (default)	npm i -g @zqagent/core@latest	Updates latest on every release; suitable for daily use

If no version is specified, it is equivalent to @latest. The @dev test channel mentioned in earlier documentation is not yet available; npm i -g @zqagent/core@dev will report that no version is found—do not use it.

Verify the installation

zqagent link --help       # macOS / Linux（已加入 PATH）

.\zqagent-windows-x64-v<版本>-<构建时间>.exe link --help    :: Windows 单文件（未加入 PATH）

Then run zqagent directly to enter the interactive CLI, enter /connect to configure the model, and you can begin. See Quick Start for details.

Upgrade and uninstall

Windows single-file

:: 升级：先停止正在运行的 serve，再用新 exe 覆盖旧文件
:: （文件名保持不变，任务计划程序 / 快捷方式无需修改）
copy /Y zqagent-windows-x64.exe "%LOCALAPPDATA%\zqagent\zqagent.exe"

:: 卸载：停止进程后删除 exe 与数据目录
rmdir /S /Q "%LOCALAPPDATA%\zqagent"

Single-file installation (install.sh, macOS / Linux)

# 升级：重跑安装脚本即可；已是最新则只报告状态
curl -fsSL https://agent.cd-zq.com/install.sh | sudo sh

# 卸载服务（数据目录与二进制保留）
curl -fsSL https://agent.cd-zq.com/install.sh | sudo sh -s -- uninstall

# 彻底清理（Linux；数据默认在运行用户的家目录）
sudo rm -rf ~/.zqagent_data /usr/local/bin/zqagent

# 彻底清理（macOS；普通用户安装时数据目录在 ~/Library/Application Support/zqagent）
sudo rm -rf "/var/root/Library/Application Support/zqagent" /usr/local/bin/zqagent

Both installation and uninstallation can be run repeatedly: rerunning when already installed does not download again, it only reports the current status; running uninstall when no service is installed does not error. Reinstalling after uninstallation reuses the retained binary and data directory, and the enrolled Hub credentials and model configuration remain.

npm installation

# 升级到最新稳定版
npm i -g @zqagent/core@latest

# 卸载
npm uninstall -g @zqagent/core

Upgrading only replaces the program itself and does not touch your model configuration or session data (configuration is in ~/.config/zqagent/, and sessions and project data are in their respective data directories; see Starting a Node).

FAQ

zqagent: command not found? The global bin directory is not in PATH. Check and add it to PATH:

For the Windows single-file, run it with the full path or .\zqagent.exe; for how to add it to PATH, see Windows single-file.

npm prefix -g        # 输出 npm 全局前缀，bin 在其中（Windows 为同目录）
echo 'export PATH="$(npm prefix -g)/bin:$PATH"' >> ~/.zshrc   # macOS/Linux

Installation reports an EACCES permission error? This means the npm global directory is owned by root. Do not use sudo npm i -g; use a version manager (nvm/fnm) or change the npm global prefix to a user directory:

npm config set prefix ~/.npm-global
echo 'export PATH="$HOME/.npm-global/bin:$PATH"' >> ~/.zshrc

Installation is very slow or times out? Make sure you can access https://registry.npmjs.org/ (or your configured mirror); on a corporate intranet, you can configure an HTTP proxy:

npm config set proxy http://<host>:<port>
npm config set https-proxy http://<host>:<port>

Do I need to reconfigure when switching machines?~/.npmrc and ~/.config/zqagent/ are both under the user directory, so when switching machines you need to reconfigure the package registry; the model API key can be reconnected via /connect.

Next steps

• Quick Start: Connect a model and complete your first task
• Starting a Node: Run zqagent persistently as a remotely manageable node
• Node Console: Manage nodes, sessions, and usage via the graphical interface