Remote Control Overview

Run zqagent on your computer or server, then remotely dispatch tasks from your phone or QQ: The AI executes on the server side, and progress, approval requests, and results are sent back to you in real time. This is suitable when you do not want to stay in front of your computer, or when you want the AI to handle things for you at any time.

Use the official cloud (recommended)

Don't want to set up a broker yourself? Use the deployed cloud directly:

1. Open ZQAgent User Center, register, and log in;

2. Create a node under Node Management and generate a one-time enrollment code (valid for 15 minutes);

3. On the target device, run one command to connect (choose one based on your setup; credentials are automatically persisted to disk, with no manual transfer required):

   Existing node (hot attach, no restart)

   zqagent link --hub https://hub.cd-zq.com --code <接入码>

   Connect on startup (source / bare metal)

   HUB_URL=https://hub.cd-zq.com HUB_ENROLL_CODE=<接入码> pnpm run server

   Docker

   docker run -d -p 8787:8787 -v zqagent-data:/data \
     -e HUB_URL=https://hub.cd-zq.com -e HUB_ENROLL_CODE=<接入码> \
     ghcr.io/<owner>/zqagent-server

   Desktop app: In the top bar of the console, click "Connect to Cloud" and paste the Hub address + enrollment code.

4. Credentials are automatically written to {DATA_DIR}/fleet.json, and no enrollment code is needed on subsequent restarts; once the node is online, you can view its status, projects, and events in the User Center or Node Console (browser / phone), and perform full session operations such as submitting tasks, approvals, and interruptions.

The node only needs an outbound connection to the gateway (wss://, usually over 443). No public inbound access or open ports are required.

• The enrollment code is one-time and short-lived; the same node ID will not be repeatedly enrolled by another node management instance (prevents preemptive registration).
• When self-hosting a Hub, the gateway address issued to nodes is determined by HUB_GATEWAY_URL on the Hub side.

CLI-only machines: run persistently as a node

A machine with only the CLI installed (no source code required) can also run persistently as a manageable node:

zqagent serve                                                      # 仅本机使用
zqagent serve --hub https://hub.cd-zq.com --enroll-code <接入码>    # 启动即接入

For background persistence (nohup / pm2 / systemd), data directories, online verification, etc., see Start Node.

Quick Start

Start the service in the project directory (source method, equivalent to zqagent serve from an installed CLI):

pnpm run server   # 默认端口 8787，首次启动自动创建演示租户 demo（apiKey 随机生成并打印在日志中）

The startup log prints demo tenant information:

zqagent server 监听 http://localhost:8787
数据目录: ./data
已创建演示租户: id=demo apiKey=zk_xxxx（随机生成） model=gpt-4o-mini

For detailed configuration, see Server Configuration.

Do you need a public network?

Conclusion: The server itself does not need a public IP. All "remote interactions" use outbound connections through third-party relays:

Capability	Server action	Relay	Requires public inbound?
Remote control	Connect to gateway (outbound wss)	Public Rust gateway	No
QQ bot	Connect to Tencent gateway (outbound)	Tencent QQ Open Platform	No
Email / Bark / ServerChan / Webhook notifications	Active POST (outbound)	SMTP / various push services	No

There is only one case that requires a public network (or intranet tunneling): when you want external parties to directly access the REST API. See Server Configuration for details.

Related documentation

• Start Node: Install the CLI, run a persistent service node, and connect to the User Center
• Node Console: Manage nodes, sessions, and usage in the browser/desktop
• Server Configuration: Startup, environment variables, cloud access, and public network solutions
• QQ Bot: QQ official bot integration + email notifications
• Remote Access: Mobile pairing connection
• REST API: For integration development reference