> ## Documentation Index
> Fetch the complete documentation index at: https://docs.certgov.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Connector Agent

> Install and configure the certforge-connector agent for automated certificate delivery to nginx, Apache, and other local services.

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](https://github.com/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](/guides/issuance-profiles))
* An [Application record](/guides/applications) for the hostname
* An [App Connector record](/guides/app-connector) 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:

```bash theme={null}
# 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:

```bash theme={null}
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

```bash theme={null}
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
```

<Note>
  The API key needs the **`connector`** scope, not the `mcp` scope. Create a dedicated key in Settings → API Keys.
</Note>

***

## Step 3 — Create the systemd service

```bash theme={null}
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

```bash theme={null}
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

```bash theme={null}
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](/guides/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`.                                                                   |