Skip to main content

Installation Guide (Agent)

This guide covers installing the cert-ctrl device agent on your machines. If you’re looking for server setup, see other docs; this page focuses only on the agent used to pull, decrypt, and deploy certificates on devices.

Quick install​

Choose the installer script for your platform. use:

  • Linux/WSL/FreeBSD: install.sh (the script auto-detects FreeBSD and applies the right steps)
  • macOS: install-macos.sh
  • Windows (PowerShell): install.ps1

Linux/WSL installer (install.sh)​

curl -fsSL https://install.lets-script.com/install.sh | sudo bash
curl -fsSL https://install.lets-script.com/install.sh?force=1 | sudo bash

Or download first to review:

curl -fsSL https://install.lets-script.com/install.sh -o install.sh
cat install.sh   # review
sudo bash install.sh --force

What it does:

  • Downloads the latest agent for your system
  • Installs to /usr/local/bin (root required) and verifies
  • Optionally sets up a system service

Tested on Ubuntu, Debian, Rocky Linux, SUSE (SLE + openSUSE), Alpine, and other popular server distros. The installer automatically hooks into the platform’s native service manager (systemd when available, OpenRC on Alpine, rc.d on FreeBSD). We also run continuous smoke tests on Rocky, Alpine, and SUSE builds to catch regressions early.

Sandbox note (systemd)

  • The installer now accepts --writable-dirs=/path/one,/path/two so you can explicitly whitelist directories that the agent must write to. This is required because the unit we ship enables ProtectSystem=strict by default.
  • If you want the agent to run without the sandbox, add --no-sandbox when invoking install.sh. That flag drops ProtectSystem=strict, but we recommend keeping the sandbox whenever possible.

FreeBSD hosts (install.sh)​

FreeBSD uses the same install.sh entrypoint as Linux. The script inspects your environment and performs the BSD-specific steps automatically:

fetch -o install.sh https://install.lets-script.com/install.sh
sh install.sh

What it does when running on FreeBSD:

  • Installs the agent under /usr/local/bin and verifies required shared libraries
  • Drops /usr/local/etc/certctrl-agent.conf if it does not exist
  • Registers /usr/local/etc/rc.d/certctrl-agent so you can service certctrl-agent start|stop|restart

macOS installer (install-macos.sh)​

For a macOS-specific flow (sets up a LaunchDaemon):

curl -fsSL https://install.lets-script.com/install-macos.sh -o install-macos.sh
sudo bash install-macos.sh

After install, useful launchctl commands:

sudo launchctl print system/com.coderealm.certctrl
sudo launchctl kickstart -k system/com.coderealm.certctrl
sudo launchctl bootout system /Library/LaunchDaemons/com.coderealm.certctrl.plist

Windows (PowerShell)​

irm https://install.lets-script.com/install.ps1 | iex

Or download to review:

Invoke-WebRequest -Uri "https://install.lets-script.com/install.ps1" -OutFile install.ps1
Get-Content install.ps1
PowerShell -ExecutionPolicy Bypass -File .\install.ps1

What it does:

  • Downloads the agent to Program Files or user-local bin
  • Creates config directory under %APPDATA%\cert-ctrl
  • Optionally installs a Windows service

Sign in the agent (cert-ctrl login)​

After installation, authenticate the agent with your server account so it can register devices and pull assignments.

Environment variables you may want to set:

Then run login:

cert-ctrl login