Install the Ploy Connector on Linux

Install the Ploy Connector on Linux by downloading the release tarball, placing the binary in /usr/local/bin, creating a dedicated system user, and running it under systemd.

Prerequisites

• A Linux host (amd64 or arm64) running systemd — any current Debian, Ubuntu, RHEL, Rocky, or SUSE distribution.

• root or sudo access on the host.

• Outbound HTTPS (port 443) from the host to api.joinploy.com.

• Network reachability from the host to the systems you are connecting (for example, a Postgres server).

• A connector bearer key from the Ploy admin UI (format ploy_ct_…).

Download and extract

Download ploy-connector-<version>-linux-<arch>.tar.gz from the Ploy console and extract it:

tar -xzf ploy-connector-<version>-linux-amd64.tar.gz
cd ploy-connector-<version>

The archive contains the ploy-connector binary, an annotated example config, the systemd unit file, and this guide.

Install the binary

Move the binary to /usr/local/bin and confirm it runs:

sudo install -m 0755 ploy-connector /usr/local/bin/ploy-connector
ploy-connector version

Create a service account

Create a dedicated, login-less system user. systemd will own the state directory /var/lib/ploy-connector for this user automatically.

sudo useradd --system --no-create-home --shell /usr/sbin/nologin ploy-connector

Configure the connector

The connector reads /etc/ploy-connector/config.yaml by default.

1. Create the configuration directory:

   sudo install -d -m 0755 /etc/ploy-connector

2. Edit the config file:

   sudoedit /etc/ploy-connector/config.yaml

A minimal example that sources secrets by reference rather than writing them in the file:

backend:
  key: env://PLOY_CONNECTOR_KEY

integrations:
  prod-pg:
    type: postgres
    enabled_features: [scan, role_management]
    credentials:
      url: env://PLOY_PG_URL

Any string under credentials or backend.key supports these URI prefixes:

• file://path — read the value from a file

• env://VAR — read it from an environment variable

• literal://value — use the rest of the string verbatim

• no prefix — used as-is

Now place the actual secrets in a root-only environment file. systemd reads this before dropping to the service user:

sudo install -m 0600 /dev/null /etc/ploy-connector/connector.env
sudoedit /etc/ploy-connector/connector.env

PLOY_CONNECTOR_KEY=ploy_ct_xxxxxxxxxxxxxxxxxxxx
PLOY_PG_URL=postgres://ploy_ro:[email protected]:5432/app?sslmode=require

If you prefer to keep values directly in config.yaml, set chmod 600 on the file and skip the env file. The shipped unit treats connector.env as optional.

Install and start the service

sudo install -m 0644 ploy-connector.service /etc/systemd/system/ploy-connector.service
sudo systemctl daemon-reload
sudo systemctl enable --now ploy-connector

Check the service status:

systemctl status ploy-connector

Verify the installation

Check two places to confirm the connector is healthy:

1. In the Ploy admin UI, go to Integrations → Connectors. Within about 30 seconds the connector reports as online with a recent heartbeat.

2. Watch the journal. The connector logs to stdout, which systemd captures:

   journalctl -u ploy-connector -f

   A healthy startup shows connector starting, then manifest registered, followed by periodic scan completed lines.

For more detail, add --debug to ExecStart in the unit file and run daemon-reload.

Update the connector

Releases are drop-in binary replacements. Stop the service, install the new binary, and start it again:

sudo systemctl stop ploy-connector
sudo install -m 0755 ploy-connector /usr/local/bin/ploy-connector
sudo systemctl start ploy-connector

Config and state persist across upgrades.

Uninstall the connector

sudo systemctl disable --now ploy-connector
sudo rm /etc/systemd/system/ploy-connector.service
sudo systemctl daemon-reload

# Optionally remove the binary, config, and state:
sudo rm /usr/local/bin/ploy-connector
sudo rm -rf /etc/ploy-connector /var/lib/ploy-connector
sudo userdel ploy-connector

Proxy and internal CAs

The connector honours HTTP_PROXY, HTTPS_PROXY, and NO_PROXY (the user:pass@host form is supported). Set them by adding lines to /etc/ploy-connector/connector.env and restarting the service:

HTTPS_PROXY=http://proxy.internal:8080
NO_PROXY=.internal,10.0.0.0/8

For an internal CA, point tls.ca_bundle in config.yaml at a PEM file. Use tls.ca_bundle_append: true to add it to the system roots rather than replace them. There is no insecure_skip_verify.

Troubleshooting