Skip to main content

Agent Updates

The PatchCTL agent includes a self-update mechanism to ensure you always have the latest features and security fixes.

How Updates Work​

  1. On each heartbeat, the agent reports its current version
  2. The API compares this with the target version for your fleet
  3. If an update is available, the API includes the download URL in the response
  4. The agent downloads and verifies the new binary
  5. The agent restarts itself with the new version
┌─────────────┐         ┌─────────────┐
│    Agent    │         │     API     │
│   v1.0.12   │────────►│             │
└─────────────┘         │  "Update    │
                        │  available: │
┌─────────────┐         │   v1.0.13"  │
│    Agent    │◄────────│             │
│   v1.0.13   │         └─────────────┘
└─────────────┘

Update Notifications​

When an update is available, you'll see:

  • Dashboard banner - Notification on the Overview page
  • Server status - "Update available" indicator
  • Agent logs - Update download and installation messages

Automatic Updates​

By default, agents update automatically when a new version is released. The update process:

  1. Downloads new binary to temporary location
  2. Verifies SHA256 checksum
  3. Replaces current binary
  4. Restarts via systemd
Zero Downtime

Updates typically complete in under 30 seconds with minimal interruption.

Manual Updates​

Check Current Version​

# Via agent command
/opt/patchctl/bin/patchctl-agent --version

# Via systemd
sudo journalctl -u patchctl | grep "version"

Force Update Check​

Restart the agent to trigger an immediate update check:

sudo systemctl restart patchctl

Manual Binary Update​

If automatic updates fail, you can update manually:

# Stop the agent
sudo systemctl stop patchctl

# Download new binary (choose your distro variant)
sudo curl -fsSL -o /opt/patchctl/bin/patchctl-agent \
  https://downloads.patchctl.com/latest/patchctl-agent-linux-amd64

# Make executable
sudo chmod +x /opt/patchctl/bin/patchctl-agent

# Start the agent
sudo systemctl start patchctl

Version Information​

Viewing Version in Dashboard​

  1. Go to Servers
  2. Click on a server
  3. View Agent Version in the details panel

Version History​

Recent agent versions and their changes are listed in the release notes on the dashboard.

Update Failures​

Common Causes​

  1. Network issues - Can't download new binary
  2. Disk space - Insufficient space for download
  3. Permissions - Can't write to /opt/patchctl/bin/
  4. Checksum mismatch - Download corrupted

Troubleshooting​

Check agent logs for update errors:

sudo journalctl -u patchctl | grep -i "update"

Common error messages:

ErrorSolution
"Download failed"Check network connectivity
"Checksum mismatch"Retry update, check for proxy issues
"Permission denied"Verify agent runs as root
"No space left"Free disk space

Rollback​

If an update causes issues:

# Stop the agent
sudo systemctl stop patchctl

# Download previous version (replace VERSION)
sudo curl -fsSL -o /opt/patchctl/bin/patchctl-agent \
  https://downloads.patchctl.com/v1.0.12/patchctl-agent-linux-amd64

# Make executable
sudo chmod +x /opt/patchctl/bin/patchctl-agent

# Start the agent
sudo systemctl start patchctl

Disabling Automatic Updates​

Not Recommended

Disabling automatic updates may leave you vulnerable to security issues.

To disable automatic updates, contact support to configure your fleet settings.