Bỏ qua để đến nội dung
MZPanel MZPanel
Agent binary (mzagent) The on-VPS Go daemon — installed by the one-liner, run by systemd. Ops reference: service control, config, and subcommands.
CtrlK

Agent binary (mzagent)

Nội dung này hiện chưa có sẵn bằng ngôn ngữ của bạn.

mzagent is the single static Go binary MZPanel installs on your VPS. It runs as a background systemd service, holds one outbound WebSocket to the control plane, and executes every operation natively in its own embedded engine. This page is the ops reference for the daemon — how it’s run, where its config lives, and the subcommands you might touch.

Service control

Section titled “Service control”

The install one-liner (see Install the agent) drops the binary and enables mzagent.service. You don’t normally invoke it by hand — systemd starts it on boot and restarts it on crash. To check on it:

Terminal window
systemctl status mzagent        # is it running?
systemctl restart mzagent       # restart the daemon (e.g. after self-update)
journalctl -u mzagent -f        # follow live logs
journalctl -u mzagent --since "1 hour ago"

The daemon loop is mzagent run: it loads the config, dials wss://ws.mzpanel.com:443 with the saved agent token, sends hello, then heartbeats every 30 s with a CPU/RAM/disk snapshot. On disconnect it reconnects with exponential backoff (1 s → 60 s).

Config & state

Section titled “Config & state”
PathWhat it is
/etc/mzagent/config.jsonThe agent’s identity — server_id, long-lived agent_token, api_url, ws_url. Mode 0600, root-owned. Written by mzagent register, read by mzagent run.
/etc/mzagent/keys/agent_key.jwkThe sealed-credential keypair. The public JWK is published to the control plane so the browser can encrypt backup-destination secrets to this box; the private key never leaves the VPS.
/etc/mzThe on-VPS registry — the source of truth for sites, jobs, and other on-box state — read and written by the native engine.

The control plane never stores your VPS state; it reads and writes through the agent. Deleting config.json de-identifies the agent (it can no longer connect until you re-register).

Subcommands

Section titled “Subcommands”

mzagent exposes a small set of operational subcommands. The ones you might touch:

SubcommandPurpose
mzagent register --api <url> --token <install-token> [--name <name>]Exchange a one-time install token (from the Add server wizard) for a long-lived agent token, then write /etc/mzagent/config.json. Run by the install one-liner.
mzagent runStart the daemon loop — dial WSS, hello, heartbeat. This is what mzagent.service runs.
mzagent self-update --url <https> --sha256 <hex> [--restart]Download, verify (SHA-256 + Ed25519 signature), sanity-run, and atomically swap the running binary; optionally restart. The manual counterpart to the control-plane-pushed update.
mzagent versionPrint version, commit and build date.
Terminal window
mzagent version
mzagent self-update --url <https-asset> --sha256 <hex> --restart

Internal entrypoints

Section titled “Internal entrypoints”

The binary also carries a few entrypoints that are implementation details, not a user-facing CLI — you’ll see them referenced in cron/systemd files but rarely type them:

  • mzagent x <domain> <action> … — run one native engine command (the same handler the WebSocket command path uses). The box’s own self-heal jobs call this so they run natively and survive a control-plane outage.
  • mzagent cron-exec <slug> [--keep N] -- <cmd> — the run-logger wrapper written into every managed crontab line; runs <cmd>, streams output, and keeps the newest N run logs so the panel can show last-run/exit.
  • mzagent engine <kind> — print a read-collector’s JSON for debugging.
  • mzagent commands [<domain>] — the machine-readable command catalog (for AI/MCP/RAG).

How it works

Section titled “How it works”

On startup, mzagent run runs a few one-time, idempotent self-heal steps before connecting:

  • Rewrites any lingering mz invocations in agent-managed cron/systemd files to point at mzagent, and removes the retired Bash mz tree once nothing references it.
  • Reinstalls the box-wide WP-Cron dispatcher cron if WordPress sites exist but the entry went missing.
  • (Re)creates the friendly mz → mzagent symlink so the CLI is always present.

Recurring on-box maintenance — the WP-Cron dispatcher, PhpMyAdmin sweep, Cloudflare token refresh, and the backup timer — runs from system cron / systemd timers that invoke mzagent x … or mzagent cron-exec …. These are deliberately independent of the WebSocket session, so scheduled work keeps running even when the control plane is unreachable. The agent also caps its own memory (soft limit ≈ half of RAM) so a spike can’t OOM-kill it on a 1 GB VPS.

Gotchas & troubleshooting

Section titled “Gotchas & troubleshooting”
  • Agent shows offline in the dashboard. Check systemctl status mzagent and journalctl -u mzagent -f. The only network requirement is outbound HTTPS:443 — no inbound ports. A missing or corrupt /etc/mzagent/config.json means it can’t identify itself; re-register from the Add server wizard.
  • Don’t hand-edit config.json. It’s written atomically at 0600. Edit it only to fix a wrong api_url/ws_url, then systemctl restart mzagent.
  • self-update swaps the binary but doesn’t reload it unless you pass --restart — otherwise run systemctl restart mzagent to load the new build.
  • mzagent x / cron-exec are internal. Prefer the mz CLI or the dashboard for real work; these exist for the box’s self-heal jobs, not day-to-day use.
  • There is a customer-facing CLI. Earlier builds shelled out to a separate Bash mz script, which has been retired; today mz is this same binary under a different name. See The mz CLI.
Section titled “Related”