Connector Agent - CertForge

The certforge-connector agent is an open-source binary that runs on your server as a systemd service. It polls CertForge for pending certificate jobs, receives delivered certificates, writes them to configured file paths, and runs a reload command (e.g., systemctl reload nginx). GitHub: CertForge-LLC/certforge-connector

How it works

[CertForge cloud] ←── poll every 60s ──── [certforge-connector on nginx host]
                                                    │
                                         writes certs to disk
                                                    │
                               runs reload_cmd (systemctl reload nginx)

The agent is stateless and requires no inbound firewall rules. It polls CertForge using a long-poll connection. CertForge pushes pending jobs when they are ready; the agent writes the cert and reports completion.

Prerequisites

A CertForge account with at least one CA configured (see Issuance Profiles)
An Application record for the hostname
An App Connector record created in CertForge (can be pre-created before the agent is installed)
TCP access from the agent host to app.certgov.app:443 (outbound only)

Step 1 — Download the agent binary

In CertForge: Integrations → Connector Agents → Download Select your architecture (amd64 or arm64). Copy the binary to the server:

# Example: download amd64 binary
scp certforge-connector-linux-amd64 user@your-server:/tmp/

# Install
sudo mv /tmp/certforge-connector-linux-amd64 /usr/local/bin/certforge-connector
sudo chmod +x /usr/local/bin/certforge-connector

Alternatively, download directly on the server:

curl -sLo /tmp/certforge-connector \
  https://github.com/CertForge-LLC/certforge-connector/releases/latest/download/certforge-connector-linux-amd64
sudo mv /tmp/certforge-connector /usr/local/bin/certforge-connector
sudo chmod +x /usr/local/bin/certforge-connector

Step 2 — Create the configuration file

sudo mkdir -p /etc/certforge
sudo tee /etc/certforge/connector.yaml <<EOF
# CertForge Connector Agent configuration

# API key with connector scope (Settings → API Keys → Add Key)
api_key: "<your-api-key>"

# CertForge endpoint
endpoint: "https://app.certgov.app"

# Connector scope: "app" for App Connectors, "device" for Device Connectors
scope: "app"

# Log level: info, debug
log_level: "info"
EOF

sudo chmod 600 /etc/certforge/connector.yaml

The API key needs the connector scope, not the mcp scope. Create a dedicated key in Settings → API Keys.

Step 3 — Create the systemd service

sudo tee /etc/systemd/system/certforge-connector.service <<EOF
[Unit]
Description=CertForge Connector Agent
After=network.target
Wants=network-online.target

[Service]
Type=simple
ExecStart=/usr/local/bin/certforge-connector --config /etc/certforge/connector.yaml
Restart=always
RestartSec=10
User=certforge
Group=certforge

# Allow cert delivery to nginx paths
ReadWritePaths=/etc/nginx/ssl
ReadWritePaths=/etc/ssl

[Install]
WantedBy=multi-user.target
EOF

Step 4 — Create a service user

sudo useradd --system --no-create-home --shell /bin/false certforge

# Grant ownership of cert delivery directories
sudo mkdir -p /etc/nginx/ssl
sudo chown certforge:certforge /etc/nginx/ssl
sudo chmod 750 /etc/nginx/ssl

# Allow certforge to reload nginx (adjust to your reload command)
echo "certforge ALL=(ALL) NOPASSWD: /bin/systemctl reload nginx" | \
  sudo tee /etc/sudoers.d/certforge-nginx

Step 5 — Start the agent

sudo systemctl daemon-reload
sudo systemctl enable --now certforge-connector

# Check status
sudo systemctl status certforge-connector

# Follow logs
sudo journalctl -u certforge-connector -f

The agent appears in Integrations → Connector Agents in CertForge within 60 seconds of starting. It shows an online status and its hostname, architecture, and version.

Step 6 — Create an App Connector record

Once the agent is online, create an App Connector record in CertForge to tie the domain to this agent and define where certificates are written. You can also pre-create the App Connector before installing the agent — CertForge stores it in pending state until an agent comes online and picks it up.

Verify

"Check if the connector agent for fun.example.com is online"
→ list_connectors(kind="app")

"Run end-to-end check for fun.example.com"
→ check_domain(domain="fun.example.com")

All coverage sections should show found. The App Connector status moves from pending_csr → active after the first successful certificate delivery.

Troubleshooting

Symptom	Check
Agent not appearing in UI	Check `journalctl -u certforge-connector` for connection errors. Verify API key and endpoint.
Cert not written to disk	Check the `cert_path` and `key_path` on the App Connector. Verify the `certforge` user has write access.
nginx not reloading	Check `reload_cmd` on the App Connector. Run the command manually as the `certforge` user to test permissions.
Agent shows offline	Check outbound TCP to `app.certgov.app:443`.

​How it works

​Prerequisites

​Step 1 — Download the agent binary

​Step 2 — Create the configuration file

​Step 3 — Create the systemd service

​Step 4 — Create a service user

​Step 5 — Start the agent

​Step 6 — Create an App Connector record

​Verify

​Troubleshooting

How it works

Prerequisites

Step 1 — Download the agent binary

Step 2 — Create the configuration file

Step 3 — Create the systemd service

Step 4 — Create a service user

Step 5 — Start the agent

Step 6 — Create an App Connector record

Verify

Troubleshooting