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. Agent status (colored dot next to the site name) - see Agent status on Sites below

6. Reported version

7. Each connector tells Patcherly which release it has installed on every check-in. The Sites page shows that reported version on the expanded site row (for example Connector: Node · v1.x.y).
8. When the reported version is behind the latest release for that connector type (WordPress, PHP, Node.js, or Python) and that type's release has been published for at least 24 hours (published_at_by_type from the latest-version API), the expanded site row shows a dismissible banner. For archive-layout Node/Python/PHP (universal installer), the primary actions are Update now (one click) and optional Auto-update; copy installer / registry commands stay as a manual fallback. WordPress and non-archive installs keep manual upgrade links only. See Upgrading an existing connector.
9. If that type's published_at is missing, the nag stays hidden. Dismissing a per-site 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.
10. Per-type latest versions (and publish dates) come from the downloads CDN and are cached for an hour on the API.

Connector Types¶

Supported connector types:

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

Agent status on Sites¶

The colored dot next to each site name shows whether Patcherly has heard from that connector recently. Hover the dot for the exact label.

Other badges on the row are separate:

A soft red row background means the site is disabled in Patcherly. That is not the same as the agent status dot.

Logout vs uninstall (Python / Node / PHP)¶

patcherly uninstall
# optional:
#   patcherly uninstall --keep-backups
#   patcherly uninstall --remove-backups

WordPress: use Deactivate / Delete in Plugins. See Deactivation vs uninstall.

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 Site paths
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_cli.php login (PHP zip install)
• 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 https://api.patcherly.com (or the API host your workspace uses). 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_cli.php login) over SSH, or use Auto-Reconnect from Sites for guided device authorization.

Related Features¶

• Installing a Connector - How to install connectors
• Adding Your First Site - Setting up your sites
• Context Collection - Context collection features