Installing a Connector¶

Connectors are lightweight agents that monitor your applications and send errors to Patcherly. Each connector is specific to your application's technology stack. For what connectors do, backups, and security at a high level, read Connectors overview first. Downloads: patcherly.com/connectors.

Easiest: Universal Installer (one command, auto-pairs)¶

Connectors authenticate via OAuth 2.0 Device Authorization Grant. No keys to copy - the dashboard issues a short user code that you confirm in a browser.

Run one of the commands below on the site server. The installer downloads the right agent for your stack and automatically launches the pairing flow at the end:

The script auto-detects Node.js, Python, or PHP and installs the matching connector. When pairing starts, the CLI prints a verification_uri and a short user_code - open the URL in any browser, sign in to your Patcherly dashboard, select the site or app, and confirm the code. Credentials are saved to ~/.patcherly/credentials.json (or /root/.patcherly/ when run as root) and monitoring starts automatically.

[!TIP] Want to install without auto-pairing? Useful for image baking, CI, or unattended provisioning. On Linux/macOS pass SKIP_LOGIN=1 after sudo (so the var survives sudo's env-stripping) - curl -sSL ... | sudo SKIP_LOGIN=1 bash. On Windows set $env:SKIP_LOGIN = '1' before irm | iex. Then pair manually later - see Pair manually (or re-pair) below.

Windows CMD / locked-down execution policy? If your environment blocks direct .ps1 execution (corporate Group Policy, etc.), run this single line from a CMD prompt instead - it pipes the installer through PowerShell with a one-time execution-policy bypass scoped to that invocation only:

powershell -NoProfile -ExecutionPolicy Bypass -Command "irm 'https://api.patcherly.com/v1/public/install.ps1' | iex"

Install paths and overrides¶

Defaults are chosen to match each platform's conventions; override with the INSTALL_DIR environment variable.

Example with overrides - note that env vars must come after sudo, not before curl. sudo strips most environment variables from its child process by default, so INSTALL_DIR=... curl ... | sudo bash would silently fall back to the defaults. The correct form is:

curl -sSL https://api.patcherly.com/install | \
  sudo INSTALL_DIR=/srv/patcherly CONNECTOR_TYPE=python SKIP_LOGIN=1 bash

The installer prints the exact path on success (Node.js connector installed to /opt/patcherly-connector), so you don't have to remember it.

Pair manually (or re-pair)¶

If you used SKIP_LOGIN=1, or just need to issue a fresh OAuth token, run the pairing command from your install path:

On Linux, prefix with sudo if the installer enabled the patcherly-connector systemd service (default on systems with systemctl) - credentials must land in /root/.patcherly/credentials.json for the root-run service to read them. On Windows, no admin elevation is needed; the default install path is user-writable.

Upgrading an existing connector¶

When Sites shows an outdated connector notice, use stack-specific actions there (copy buttons), or re-run the installer with SKIP_LOGIN=1 so pairing is not launched again. OAuth credentials stay under ~/.patcherly/ (or /root/.patcherly/); the installer still overwrites install-dir .env with SERVER_URL only.

Node / Python / PHP (universal installer layout) - force type and skip login, then restart:

curl -sSL https://api.patcherly.com/install | sudo CONNECTOR_TYPE=nodejs SKIP_LOGIN=1 bash
systemctl restart patcherly-connector

$env:CONNECTOR_TYPE='nodejs'; $env:SKIP_LOGIN='1'
irm "https://api.patcherly.com/v1/public/install.ps1" -OutFile install.ps1; .\install.ps1
# Stop the running agent process, then:
& "$env:USERPROFILE\patcherly-connector\start.ps1"

(Replace nodejs with python or php as needed.)

Registry installs - upgrade the package, then restart your process:

WordPress - update from Plugins on WordPress.org, or download patcherly.zip and use Plugins → Add New → Upload Plugin. See Plugin updates.

Remote Update now / Auto-update (archive installs only) - after a universal-installer install, Sites can request an in-place package swap for Node / Python / PHP (verified with CDN sha256_by_type). This is off by default. Registry installs (npm / pip / Composer) keep the upgrade commands above; WordPress never uses remote replace. Optional host override PATCHERLY_CONNECTOR_AUTO_UPDATE=1 is wiped when the installer rewrites .env - prefer the Sites toggle for durable opt-in. Updates are skipped while Protection mode or Pause site is active.

WordPress (2 steps)¶

1. In WordPress admin: Plugins → Add New → upload or install the Patcherly Connector plugin.
2. Open Patcherly Connector in the menu, then click Pair connector - the plugin runs the same OAuth flow on your behalf (no API key to paste).

Available connectors¶

Manual setup¶

If you prefer to install the connector package manually (e.g. pip install patcherly-connector / npm install @patcherly/nodejs-connector), run patcherly login after installation to complete the OAuth pairing step. The credentials are written to ~/.patcherly/credentials.json; no API key environment variable is needed.

WordPress installs from the WordPress.org plugin directory - see WordPress connector.

Installation Guides¶

Choose the connector for your technology:

• WordPress Connector Installation
• Node.js Connector Installation
• Python Connector Installation
• PHP Connector Installation

After Installation¶

Once your connector is installed and configured:

1. Check connection status in your dashboard
2. Test the connection by triggering a test error (if available)
3. Monitor for errors - the connector will automatically detect and report errors

Troubleshooting¶

Connector Not Connecting¶

• Verify OAuth credentials are present: cat ~/.patcherly/credentials.json (or /root/.patcherly/credentials.json if you paired with sudo)
• Re-pair if credentials are missing or expired: run start.sh login (Linux/macOS) or start.ps1 login (Windows) from your installer's INSTALL_DIR - match the elevation you used the first time so credentials land in the same home
• Ensure your firewall allows outbound HTTPS to api.patcherly.com
• Check connector logs for connection errors

Installing an older connector version¶

[!NOTE] This section is about downgrading the connector itself (the agent that runs on your server), not about rolling back a bad patch on a specific error. For patch rollback - restoring files after a fix went wrong - see Rollback.

If a connector release causes issues, you can pin the agent code to an older version. Note: the universal installer script itself (api.patcherly.com/install) is always the latest - only the agent payload (the .zip / .tar.gz files) can be version-pinned. This works for most downgrades within the same minor (e.g. v1.x.y → v1.x.z); cross-minor downgrades occasionally need the manual flow if the installer's expectations of the agent layout have changed.

• Override the download CDN with ARTIFACT_BASE: pass the env var to sudo (must come after sudo, not before curl - see the override note above). The latest installer logic still runs, but it downloads connector archives from your base URL instead of the default CDN:

curl -sSL https://api.patcherly.com/install | sudo \
  ARTIFACT_BASE=https://download.patcherly.com/connectors \
  bash

After installing, pair as usual - see Step 2 above for the platform-specific pairing command.

• Pin a specific connector version (recommended for downgrades): use your package manager, for example npm install @patcherly/[email protected], pip install patcherly-connector==X.Y.Z, or composer global require patcherly/php-connector:X.Y.Z, then run patcherly login. This is the recommended path for cross-minor downgrades because the public CDN archives always reflect the latest release.

• Manual download (latest archives only): download a named archive - nodejs-connector.tar.gz, python-connector.tar.gz, php-connector.zip, or patcherly.zip - and follow the per-language install guide.

No Errors Detected¶

• Verify the connector is running
• Check that error detection is enabled
• Ensure your application is generating errors
• Review connector configuration

Security¶

• Credentials are OAuth tokens - stored in ~/.patcherly/credentials.json (or /root/.patcherly/ when paired with sudo); never commit this file to version control
• Re-pair to rotate - run start.sh login / start.ps1 login from INSTALL_DIR (or patcherly login for package installs) to issue a fresh token; the old one is automatically revoked
• Use HTTPS - all connector traffic uses HTTPS to api.patcherly.com

Next Steps¶

• Understand how errors work
• Learn about the approval workflow
• Understand auto-apply (when Patcherly applies a fix without your click)