Skip to content

Connector Management

Connector management features help you discover, initialize, and monitor connectors for your sites.

Overview

Connector management provides:

  • Discovery: Find connectors in your application
  • Initialization: Set up connectors automatically
  • Status Monitoring: Check connector health and connectivity
  • Configuration: Manage connector settings

Connector Discovery

Discover the connector type suggested for a website URL (e.g. WordPress, PHP, Node.js, Python).

Discovery follows safety rules for your site or app:

  • The requested discovery URL must match the registered site host.
  • Private/internal and metadata-style network destinations are blocked by default.
  • For rare troubleshooting, Patcherly support can allow a temporary network exception when you ask for it and describe what to verify.

From Dashboard

  1. When editing a saved site or app
  2. Open Edit on the site row
  3. Enter or confirm the site URL (e.g. https://yoursite.com) - it must match the host already registered for that site
  4. Click Discover next to the URL field
  5. The dashboard calls the API and may suggest a connector type; the Type dropdown is updated if a suggestion is found

Discover is not available while adding a new site - save it first, then edit and run Discover.

Connector Initialization

Set the connector type and optional server path for a site or app and get setup instructions (e.g. server path for WordPress).

From Dashboard

  1. Edit the site or app
  2. Open the website/app and click Edit (or edit it from the Sites page)
  3. In the Connector setup section, optionally enter Server path (e.g. /var/www/html)
  4. Click Save & get setup instructions
  5. The dashboard saves the connector type and server path and shows setup steps, including the OAuth pairing command (patcherly login) to run on the site server after the connector is installed

Connector Status

Monitor connector health and connectivity:

From Dashboard

  1. View Status
  2. Go to site page
  3. Check Connector Status section

  4. View connection status, last seen, and health

  5. Status Indicators

  6. Connected: Connector is active and communicating
  7. Disconnected: Connector is not responding

  8. Error: Connector has an error (check details)

  9. Reported version

  10. Each connector tells Patcherly which release it has installed on every check-in. The dashboard shows that reported version inline next to the connector path (for example (v1.x.y)).
  11. When the reported version is behind the latest Patcherly release and that release has been published for at least 24 hours (published_at from the latest-version API), a non-blocking "Connector is outdated" banner appears on the site or app with a one-click link to the installer guide. If published_at is missing, the banner stays hidden. Dismissing the banner hides it for the rest of the browser session; it reappears next session if the connector is still behind and still past the grace window.
  12. The latest released version (and published_at) comes from latest.json on the Patcherly downloads CDN and is cached for an hour on the API, so the banner stays accurate without putting extra load on every dashboard request.

Connector Types

Supported connector types:

  • WordPress: WordPress plugin connector
  • Python: Python application connector
  • Node.js: Node.js application connector
  • PHP: PHP application connector

Best Practices

  1. Regular Discovery: Periodically discover new connectors
  2. Monitor Status: Check connector status regularly
  3. Keep Updated: Update connectors to latest versions
  4. Set Site Roots: Configure PATCHERLY_TARGET_ROOTS to keep connector file operations inside approved folders
  5. Use path rules on the site or app: Under Sites, set monitoring exclusions for noise and patch exclusions for folders where automated changes must never run - see Path rules for sites
  6. Review Logs: Check connector logs for issues
  7. Test Connectivity: Verify connectors can reach the server

Troubleshooting

Connector Not Discovered

  • Check Installation: Verify connector is installed
  • Verify Path: Ensure base path is correct
  • Check Permissions: Connector files must be readable
  • Review Logs: Check discovery logs for errors

Initialization Failed

  • Check Configuration: Verify all required settings
  • Test Connectivity: Ensure connector can reach server
  • Review Logs: Check initialization logs
  • Verify Permissions: Connector must have write permissions for configuration

Connector Disconnected

  • Check Network: Verify network connectivity
  • Review Logs: Check connector logs for errors
  • Verify Credentials: Confirm ~/.patcherly/credentials.json (or /root/.patcherly/credentials.json if paired with sudo) exists and the OAuth token is still valid; if not, re-pair with patcherly login (package installs) or the connector's start.sh login (Linux/macOS) / start.ps1 login (Windows) / php patcherly_agent.php login (PHP direct)
  • Restart Connector: Try restarting the connector
  • Site was removed in the dashboard: If you (or another workspace admin) deleted the site from the Sites page, Patcherly immediately revokes the connector OAuth token tied to it. Refresh attempts return invalid_grant and the connector logs target removed (that log string is the API reason code). Recreate the site from the dashboard and re-pair the connector with patcherly login.
  • Workspace owner deleted the account: Account deletion also revokes every connector token issued under the workspace. Cancel the deletion within the grace window and re-pair affected connectors.

Auto-Reconnect (Sites)

A site can look Healthy (heard from recently) but still show Not apply-ready when Apply cannot reach a live connector session. Use Auto-Reconnect on the Sites row:

  • Brief outages and silence: Patcherly nudges the connector (and retries on a schedule) without wiping credentials - the row may show Reconnecting… while a retry is actively due or Auto-Reconnect is running (not for the whole wait between nudges).
  • Agent offline (stale or inactive presence, not never-paired): the connector has not checked in recently. This is distinct from Reconnecting…. Auto-Reconnect tries to restore a live session.
  • Re-auth required: for WordPress, the Sites control tooltip reads Open plugin to re-pair and opens plugin Home with patcherly_reconnect=1, which prompts Re-Connect Account (confirm) and starts pairing. For agents, Auto-Reconnect opens the device authorize page. Agents do not invent a code in the browser - SSH to the server where the connector runs and run patcherly login --api-base … with the same API host as this dashboard (api.patcherly.com in production, apidev.patcherly.com on Render DEV). Paste the printed user code, then Approve. The authorize page shows that regular login command.
  • Pair site remains for never-paired WordPress sites; it is not shown alongside Auto-Reconnect for re-auth.

Force Disconnect from the Dashboard

Sometimes the connector cannot signal its disconnect - the plugin was uninstalled without clicking Disconnect, the server is offline, WP-Cron is stopped, or the OAuth refresh chain has already failed. Prefer Auto-Reconnect first when the row shows Not apply-ready, Reconnecting…, or Re-auth required. Use Unplug (Force Disconnect) when you need to clear pairing immediately so the site is selectable for a fresh Connect / device login (presence may otherwise stay healthy/stale until the 7-day clock ages out).

To force the disconnect immediately:

  1. Go to Sites in the dashboard.
  2. Find the site row. When presence is healthy / stale, or a reconnect phase is active, the row shows Auto-Reconnect (when Apply needs attention) plus an Unplug icon. Never-paired inactive rows show Connect / Pair site instead.
  3. Click Unplug, confirm in the modal.
  4. The row flips to inactive on the next refresh, the OAuth token family is revoked (any still-running connector will 401 on its next signed call), reconnect state is cleared (no connector_issue email), and the connect plug icon comes back so you can re-pair from the same row or /authorize/device.

The site itself is kept - only the OAuth pairing is undone. Settings, log paths, and error history all survive. Workspace admins can force-disconnect sites in their workspace from the Sites page.

Connector cell: Pair site (WordPress never-paired only)

For WordPress sites that have never been paired (inactive, reconnect phase none, not apply-ready), the Connector cell shows Pair site - a deep-link to wp-admin Patcherly settings so you can click Connect with Patcherly.

Once a pairing exists and Apply needs attention, use the row Auto-Reconnect control instead (soft-hold / server retry / re-auth). There is no separate stale-only Reconnect deep-link competing with Auto-Reconnect.

Non-WordPress connectors have no wp-admin equivalent - on your server, run patcherly login (or the matching start.sh / start.ps1 / php patcherly_agent.php login) over SSH, or use Auto-Reconnect from Sites for guided device authorization.