Standalone Node Setup

A built-in client starts on the server host by default. To run scanning tasks across multiple servers, connect additional client nodes to the main server.

Choose a deployment method:

Method	Best for	Notes
Docker (recommended)	Hosts with Docker installed	One command, containerized isolation, easy upgrades
Binary	Lightweight VPS, intranet jump boxes, ARM devices — anywhere Docker is impractical	Static binary, one-click script or manual install

Prerequisite: Retrieve the Secret

Client nodes need a secret to register with the main server. Copy it from the server's deploy directory:

cd testnet-deploy
grep TESTNET_CLIENT_SECRET .env

---

Method 1: Docker (Recommended)

Run the following on any standalone host with Docker. The docker.sock mount lets the probe launch containerized scanning tools; the work/data mounts ensure scan results and files exchange correctly between tool containers and the probe:

docker run -d \
  --name testnet-client \
  --restart always \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v ./client-data:/opt/testnet/client-data \
  -v ./client-work:/opt/testnet/client-work \
  -v /tmp:/tmp \
  -e TESTNET_SERVER_URL=https://your-server-ip:3100 \
  -e TESTNET_SERVER_TLS_ENABLED=true \
  -e TESTNET_SERVER_TLS_INSECURE_SKIP_VERIFY=true \
  -e TESTNET_CLIENT_SECRET=<secret-from-server> \
  -e TESTNET_NODE_NAME=node-guangzhou-01 \
  -e TESTNET_DATA_DIR=/opt/testnet/client-data \
  -e TESTNET_WORK_DIR=/opt/testnet/client-work \
  testnet0/testnet-client:latest

China Mirror Acceleration

When deploying from servers in mainland China, pull the client image directly from the Aliyun mirror: registry.cn-hangzhou.aliyuncs.com/testnet0/testnet-client:latest

---

Method 2: Binary (No Docker Required)

Option A: One-Click Script (Recommended)

The installation script supports both root and non-root users (non-root users automatically register a systemd --user service, achieving full autostart without root privileges).

# Basic install (server URL and secret are required)
bash <(curl -fsSL https://cnb.cool/testnet0/testnet-public/-/git/raw/main/install-client.sh) \
  -s https://your-server-ip:3100 \
  -k <secret-from-server> \
  -n node-beijing-01

# Self-signed certificate scenario (skip TLS verification)
bash <(curl -fsSL https://cnb.cool/testnet0/testnet-public/-/git/raw/main/install-client.sh) \
  -s https://your-server-ip:3100 \
  -k <secret-from-server> \
  --no-tls-verify

# Download and extract only, without registering a systemd service
bash <(curl -fsSL https://cnb.cool/testnet0/testnet-public/-/git/raw/main/install-client.sh) \
  -s https://your-server-ip:3100 \
  -k <secret-from-server> \
  --no-systemd

Automated Script Features

install-client.sh automatically handles:

1. Permission Adaptation: Root installs to /opt/testnet/client with a system service; regular users install to ~/testnet-client with a systemd --user service (using loginctl enable-linger to keep running across SSH logouts).
2. Environment Detection: Detects amd64 / arm64, downloading the latest pre-built static binary and template from CNB or GitHub Releases.
3. Docker Privilege Check: Inspects Docker Socket access and provides docker group permission guidance if needed.

Common Service Management Commands

After installation, the global command testnet-client-ctl is automatically registered (or run install-client.sh directly from the install directory):

testnet-client-ctl status              # Check node service status
testnet-client-ctl restart             # Restart client daemon
testnet-client-ctl stop                # Stop client daemon
testnet-client-ctl start               # Start client daemon
testnet-client-ctl logs                # Tail real-time logs
testnet-client-ctl update              # Seamless in-place binary upgrade
testnet-client-ctl uninstall --purge   # Clean uninstall and purge cache

# Or run with explicit script path (e.g., /opt/testnet/client or ~/testnet-client)
bash /opt/testnet/client/install-client.sh status

Option B: Manual Installation

Step 1: Download the archive for your architecture

Architecture	Download (CNB, China)	Download (GitHub)
amd64 (x86_64)	testnet-client-linux-amd64.tar.gz	GitHub Releases
arm64 (AArch64)	testnet-client-linux-arm64.tar.gz	GitHub Releases

# Auto-detect architecture and download (CNB mirror)
ARCH=$(uname -m | sed 's/x86_64/amd64/;s/aarch64/arm64/')
VERSION="v3.0.4"
curl -fsSL "https://cnb.cool/testnet0/testnet-public/-/releases/download/${VERSION}/testnet-client-linux-${ARCH}.tar.gz" \
  -o testnet-client.tar.gz

# Extract
tar -xzf testnet-client.tar.gz
chmod +x testnet-client

Step 2: Create the config file

The archive ships with a configs/config.yaml template — edit the key fields:

server:
  url: "https://your-server-ip:3100"     # Server address
  secret: "<secret-from-server>"          # TESTNET_CLIENT_SECRET
  tls:
    enabled: true                         # true for HTTPS
    insecure_skip_verify: true            # true for self-signed certificates

node:
  name: "node-beijing-01"                 # Node name shown in the console

task:
  max_concurrent: 5                       # Max concurrent tasks

Step 3: Run the client

# Foreground (for testing)
./testnet-client --config configs/config.yaml

# Background (nohup)
nohup ./testnet-client --config configs/config.yaml > /var/log/testnet-client.log 2>&1 &

# Or configure via environment variables without touching config.yaml
TESTNET_SERVER_URL=https://your-server-ip:3100 \
TESTNET_CLIENT_SECRET=<secret> \
TESTNET_NODE_NAME=node-beijing-01 \
./testnet-client

Step 4 (optional): Register a systemd service for auto-start

# Move the binary into the system directory
sudo mkdir -p /opt/testnet/client/configs
sudo mv testnet-client /opt/testnet/client/
sudo mv configs/config.yaml /opt/testnet/client/configs/

# Create the systemd unit
sudo tee /etc/systemd/system/testnet-client.service > /dev/null <<'EOF'
[Unit]
Description=TestNet Scanning Client Node
After=network-online.target docker.service
Wants=network-online.target

[Service]
Type=simple
ExecStart=/opt/testnet/client/testnet-client --config /opt/testnet/client/configs/config.yaml
WorkingDirectory=/opt/testnet/client
Restart=on-failure
RestartSec=10
LimitNOFILE=65536

[Install]
WantedBy=multi-user.target
EOF

# Enable and start
sudo systemctl daemon-reload
sudo systemctl enable --now testnet-client

# Status and logs
sudo systemctl status testnet-client
sudo journalctl -u testnet-client -f

---

Verify the Node Is Online

Log in to the console and open "Scan Nodes" → "Node Pool" — the newly joined node appears in real time with its online status and concurrency limit.

Via Script (Recommended)

# In-place upgrade
bash install-client.sh update

# Complete uninstall (including services, directory, and optional cache purge)
bash install-client.sh uninstall --purge

Manual Method

Upgrade:

# System service
sudo systemctl stop testnet-client
# Overwrite /opt/testnet/client/testnet-client
sudo systemctl start testnet-client

# User service
systemctl --user stop testnet-client
# Overwrite ~/testnet-client/testnet-client
systemctl --user start testnet-client

Uninstall:

# System service
sudo systemctl disable --now testnet-client
sudo rm -f /etc/systemd/system/testnet-client.service
sudo systemctl daemon-reload
sudo rm -rf /opt/testnet/client

# User service
systemctl --user disable --now testnet-client
rm -f ~/.config/systemd/user/testnet-client.service
systemctl --user daemon-reload
rm -rf ~/testnet-client

---

Related Documentation

• Node Management — node pool status, heartbeat, and the client environment variable reference
• Node Security — probe sandbox and security mechanisms
• Upgrades & Maintenance — server upgrades and data backup