Zoneploy Server Agent

The Zoneploy Server Agent is the runtime component installed on each managed VPS. It exposes a private HTTP API used by Platform to:

• deploy and control containers
• deploy and control Docker Compose stacks
• stream metrics and logs
• expose server-level add-on operations
• run server preflight checks

Install model

The base agent install is responsible for:

• Docker availability
• the zoneploy Docker network
• Traefik for Zoneploy-managed routing
• the systemd service for the agent

Infrastructure add-ons are validated separately through server capabilities and add-on requirements. For example, custom-domains-edge can only be installed when the target server meets its own runtime requirements.

Commands

Status

Print a compact status summary for the local agent runtime, including add-on states:

zoneploy-agent-status

Print the same status report as JSON:

zoneploy-agent-status --json

Disable ANSI colors in the human-readable output:

zoneploy-agent-status --no-color

The status report includes:

• detected zoneploy-agent* services and their active state
• safe environment values such as SERVER_ID, PLATFORM_URL, AGENT_PORT, and HTTPS_ENABLED
• Docker installed / daemon running status
• Traefik status
• registered server-level add-ons and their current state
• direct journalctl commands for the detected services

Debug snapshot

Print a high-signal report of the local Zoneploy runtime:

zoneploy-agent-debug

Print the same report as JSON:

zoneploy-agent-debug --json

Filter stack output by stack id, compose project, or service name:

zoneploy-agent-debug --stack eefe305e

The debug snapshot includes:

• detected Zoneploy agent services
• safe environment values such as SERVER_ID, PLATFORM_URL, AGENT_PORT, and HTTPS_ENABLED
• Docker and Docker Compose versions
• Traefik status, ports, probe target, and dynamic files
• Zoneploy-managed standalone containers
• Zoneploy-managed stacks
• local host probes against Traefik
• routing warnings such as missing labels or missing override application

Server audit

Run a local audit of the installed agent runtime and host security posture:

zoneploy-agent-audit

Print the same audit report as JSON:

zoneploy-agent-audit --json

Disable ANSI colors in the human-readable output:

zoneploy-agent-audit --no-color

The audit report includes:

• host OS, package manager, root context, and systemd readiness
• detected zoneploy-agent* services and required environment variables
• Docker daemon, Compose v2, Docker socket, and zoneploy network checks
• Docker Snap detection, which is unsupported for managed installs
• Traefik container, static config, dynamic config directory, and stale route checks
• SSH, password authentication, root login, firewall, and fail2ban checks
• registered server-level add-ons and their health status

Server preflight

Run the same server preflight used by Platform before provisioning:

zoneploy-agent-preflight

Print the preflight report as JSON:

zoneploy-agent-preflight --json

The preflight report includes:

• platform and distro detection
• package manager detection
• firewall backend detection
• elevated access detection (root, sudo, or none)
• Docker installed and Docker running checks
• Docker Snap detection
• capability summary
• occupied ports and listeners
• structured conflicts with severity and codes

Cross-distro smoke coverage

The repository includes a reusable smoke runner for the shell-based preflight:

bash infra/agent/smoke-preflight.sh

GitHub Actions also runs this smoke test in a distro matrix for:

• Ubuntu 24.04
• Ubuntu 22.04
• Ubuntu 20.04
• Ubuntu 18.04 (legacy best-effort)
• Debian 12
• Debian 11
• Debian 10 (legacy best-effort)
• Fedora 40 (legacy best-effort)
• Rocky Linux 9
• CentOS Stream 9
• CentOS Stream 8 (legacy best-effort)

This matrix validates shell compatibility, package manager detection, JSON output shape, and occupied-port conflict reporting. It does not replace full VM coverage for systemd, service installation, or firewall integration.

Logs

Show the last 100 journal lines for the production service:

journalctl -u zoneploy-agent -n 100 --no-pager

Follow the service logs live:

journalctl -u zoneploy-agent -f

If the server was provisioned with a non-production environment name, the service name becomes:

zoneploy-agent-<environment>

Examples:

journalctl -u zoneploy-agent-development -n 100 --no-pager
journalctl -u zoneploy-agent-development -f

systemd

Check service status:

systemctl status zoneploy-agent

Restart the agent:

systemctl restart zoneploy-agent

API notes

The agent HTTP API is private and authenticated with the server-specific agent token. Platform talks to the agent over http://<server-ip>:<agent-port>/agent/v1/....

Public troubleshooting should prefer:

• zoneploy-agent-status
• zoneploy-agent-status --json
• zoneploy-agent-audit --json
• zoneploy-agent-preflight --json
• zoneploy-agent-debug --json
• journalctl -u zoneploy-agent -n 100 --no-pager

These outputs are intentionally structured so they can be pasted into support or debugging sessions with minimal extra context.