WP SSH — Remote Management Bridge

A private, self-hosted WordPress plugin that lets you (or a trusted AI assistant like Claude) manage a site over an authenticated HTTPS endpoint instead of raw SSH / WP-CLI access.

This is not a public/multi-tenant tool. It is meant to be installed manually on sites you personally manage. Each install generates its own unique secret key and detects its own site automatically — nothing is shared across installs.

⚠️ Read this before installing. With write actions enabled, this plugin can write PHP files inside wp-content, run arbitrary SQL, and activate/deactivate plugins. Anyone who obtains your secret key has meaningful control over the site. Keep the key private, use HTTPS only, and turn on Read-only mode or an IP allowlist when you don't need full write access.

Why this exists

Managing WordPress sites normally means either giving out full SSH/cPanel credentials, or doing everything by hand through wp-admin. This plugin exposes a small, whitelisted set of actions over a single REST endpoint, so a script (or an AI assistant with an HTTP tool) can:

• Read diagnostics, options, posts, media, plugins, themes, orders
• Make scoped changes (update a post, set a product attribute, clear cache, edit a file inside wp-content) without needing shell access
• Do it all with logging, rate-limiting, confirm-tokens on destructive actions, and automatic backups

Installation

1. Download wp-ssh.zip (or clone this repo into wp-content/plugins/wp-ssh/).
2. In wp-admin: Plugins → Add New → Upload Plugin, upload the zip, Activate.
3. Go to Tools → WP SSH.
4. Copy the auto-generated Secret key.
5. Check Enable bridge, save settings.

That's it — the site is now reachable at:

POST https://yoursite.com/wp-json/wp-ssh/v1/execute

Authentication

Every request must include the secret key in a custom header:

X-WPSSH-Key: <your-secret-key>
Content-Type: application/json

Request body:

{
  "action": "site_info",
  "params": {}
}

Response:

{ "success": true, "data": { ... } }

or, on failure:

{ "code": "wp_ssh_bad_key", "message": "Invalid or missing secret key.", "data": { "status": 401 } }

Unauthenticated ping

GET /wp-json/wp-ssh/v1/ping returns { plugin, version, site, label } — useful to confirm the plugin is installed and to auto-detect which site you're talking to, without needing the key.

Security features

Example: curl

curl -X POST https://yoursite.com/wp-json/wp-ssh/v1/execute \
  -H "X-WPSSH-Key: YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{"action": "diagnostics", "params": {}}'

Available actions

Site & diagnostics

Options

Posts & content

Media

Plugins & themes

Files (scoped to wp-content/)

All file paths are resolved with realpath() and rejected if they escape wp-content — no ../ traversal outside it.

Database

WooCommerce

Elementor

Settings reference (Tools → WP SSH)

• Site label — friendly name returned in ping/site_info, handy when you manage several sites.
• Enable bridge — master on/off switch.
• Read-only mode — blocks every write action regardless of other settings.
• Allow write queries — required (in addition to confirm: true) for non-SELECT SQL via db_query.
• IP allowlist — one IP per line; empty = any IP (still requires the key).
• Health check emails — hourly self-check with an alert email if something looks wrong.
• Regenerate secret key — invalidates the old key immediately.

License

GPLv2 or later.