WP Hoster Agent

The WP Hoster Agent is a custom WordPress plugin installed on each site. It exposes a token-authenticated REST API used for health data and remote actions (flush cache, run cron, etc.). The panel uses the health endpoint during healthchecks to avoid relying solely on WP-CLI.

File paths

Path	Purpose
`provisioning/wordpress/wphoster-agent/`	Plugin root (source; rsynced to each site)
`provisioning/wordpress/wphoster-agent/wphoster-agent.php`	Main plugin file, registers REST routes
`provisioning/wordpress/wphoster-agent/includes/class-rest-controller.php`	REST controller: health + actions
`app/Services/WordPress/WphosterAgentInstaller.php`	Installs plugin and writes token to wp-config

Installation

WphosterAgentInstaller::install() rsyncs the plugin into {site_root}/wp-content/plugins/wphoster-agent, runs wp plugin activate wphoster-agent, generates a 64-char token, and appends to wp-config.php:

WPHOSTER_AGENT_TOKEN — Secret for X-WPHoster-Token header
WPHOSTER_WP_CLI_PATH — Path to WP-CLI (for verify-checksums in plugin)

Token is stored in site.metadata['agent_token'] so the panel can call the health endpoint.

REST endpoints

Method / Path	Purpose
`GET /wp-json/wphoster/v1/health`	Returns PHP version, memory, WP version, active theme, plugins/themes list, db_size_bytes, disk_usage_bytes, core_checksum_status
`POST /wp-json/wphoster/v1/actions`	Body: `action` = `flush_cache` \| `run_cron` \| `clear_transients` \| `verify_checksums`

Authentication

All routes use permission_callback that checks X-WPHoster-Token header against WPHOSTER_AGENT_TOKEN (constant-time comparison). Missing or invalid token returns 401.

Health response structure (excerpt)

{
  "php_version": "8.2.x",
  "memory_limit": 268435456,
  "memory_usage": 12345678,
  "wp_version": "6.x",
  "active_theme": "Theme Name",
  "active_plugins_count": 5,
  "db_size_bytes": 1234567,
  "disk_usage_bytes": 12345678,
  "agent_version": "1.0.0",
  "plugins": [...],
  "themes": [...],
  "core_checksum_status": "ok" | "modified"
}

Config

Key	Purpose
`wphoster.agent.enabled`	Whether to install agent on provision/clone
`wphoster.agent.path`	Absolute path to plugin source (default: `base_path('provisioning/wordpress/wphoster-agent')`)