The Smallstep Agent brings automated certificate management, device identity, and configuration management features to your endpoints.

This guide covers manual installation of the Smallstep Agent on:

• Linux
• macOS
• Windows

Use this guide if you want to install the agent via a software management tool separate from your MDM (eg Ansible, Munki), or if your MDM only supports limited software management workflows.

The agent will connect to the following Smallstep hosts:

• Your CA: <your-team>.ca.smallstep.com and subdomains
• Agent API: control.infra.smallstep.com
• Smallstep API: gateway.smallstep.com
• TPM Attestation CA: att.smallstep.com

• Supported operating systems:
  • Enterprise Linux (RHEL, CentOS Stream, Rocky Linux, Alma Linux, etc)
  • Ubuntu (Current Stable and LTS)
  • Debian (Current Releases)
  • Fedora (Current Releases)
• A TPM 2.0 module is required. Smallstep depends on TPMs to create a high-assurance device inventory.
• We support amd64 and arm64 architectures
• The following directories are used by default:
  • runtime state in /run/step-agent
  • configuration in /etc/step-agent
  • certificates in /var/lib/step-agent and in your configured locations

On a Linux system with bash and curl, run the following:

curl -fsSL https://packages.smallstep.com/scripts/smallstep-agent-install.sh | sudo env STEP_AGENT_TEAM=[your-team] bash

1. In the Terminal, add our package repository to your system:

   cat << EOF | sudo tee /etc/yum.repos.d/smallstep.repo
   [smallstep]
   name=Smallstep
   baseurl=https://packages.smallstep.com/stable/fedora/
   enabled=1
   repo_gpgcheck=0
   gpgcheck=1
   gpgkey=https://packages.smallstep.com/keys/smallstep-0x889B19391F774443.gpg
   EOF
   

2. Install the Smallstep agent:

   sudo dnf makecache && sudo dnf install -y step-agent-plugin
   

3. Check that it was installed correctly:

   step-agent-plugin version
   

   Output:

   🚀 step-agent-plugin/0.38.0 (linux/amd64)
      Release Date: 2024-10-10T14:55:48Z
   

1. In the Terminal, add our package repository to your system:

   cat << EOF | sudo tee /etc/yum.repos.d/smallstep.repo
   [smallstep]
   name=Smallstep
   baseurl=https://packages.smallstep.com/stable/el/
   enabled=1
   repo_gpgcheck=0
   gpgcheck=1
   gpgkey=https://packages.smallstep.com/keys/smallstep-0x889B19391F774443.gpg
   EOF
   

2. Install the Smallstep agent:

   sudo dnf makecache && sudo dnf install -y step-agent-plugin
   

3. Check that it was installed correctly:

   step-agent-plugin version
   

   Output:

   🚀 step-agent-plugin/0.38.0 (linux/amd64)
      Release Date: 2024-10-10T14:55:48Z
   

1. In the Terminal, install dependencies:

   sudo apt-get update && sudo apt-get install -y --no-install-recommends curl gpg ca-certificates
   

2. Add our package repository to your system:

   sudo curl -fsSL https://packages.smallstep.com/keys/apt/repo-signing-key.gpg -o /etc/apt/keyrings/smallstep.asc
   cat << EOF | sudo tee /etc/apt/sources.list.d/smallstep.sources
   Types: deb
   URIs: https://pkgs.infra.smallstep.com/stable/debian
   Suites: debs
   Components: main
   Signed-By: /etc/apt/keyrings/smallstep.asc
   EOF
   

3. Install the Smallstep agent:

   sudo apt-get update && sudo apt-get -y install step-agent-plugin
   

4. Check that it was installed correctly:

   step-agent-plugin version
   

   Output:

   🚀 step-agent-plugin/0.38.0 (linux/amd64)
      Release Date: 2024-10-10T14:55:48Z
   

1. In the Terminal, install dependencies:

   DEBIAN_FRONTEND=noninteractive
   sudo apt-get update && sudo apt-get install -y --no-install-recommends curl gpg ca-certificates
   

2. Add our package repository to your system:

   sudo curl -fsSL https://packages.smallstep.com/keys/apt/repo-signing-key.gpg -o /etc/apt/keyrings/smallstep.asc
   cat << EOF | sudo tee /etc/apt/sources.list.d/smallstep.sources
   Types: deb
   URIs: https://packages.smallstep.com/stable/debian
   Suites: debs
   Components: main
   Signed-By: /etc/apt/keyrings/smallstep.asc
   EOF
   

3. Install the Smallstep agent

   sudo apt-get update && sudo apt-get -y install step-agent-plugin openssl-tpm2-engine
   

4. Check that it was installed correctly

   step-agent-plugin version
   

   Output:

   🚀 step-agent-plugin/0.38.0 (linux/amd64)
      Release Date: 2024-10-10T14:55:48Z
   

Users can configure the agent and register their Linux device with your Smallstep team by running:

sudo step-agent-plugin register [team name]

By default, self-registration is not trust-on-first-use (TOFU). Devices must be approved by an admin before they can be used.

Alternatively, you can pre-register all of your team's devices:

1. Register and approve your devices via API. The devices you add via API will be pre-approved.

2. Then, on your endpoints, update the /etc/step-agent/agent.yaml config file with your Smallstep team name and Smallstep Agent CA fingerprint.

   team: "myteamname"
   fingerprint: "40523785c1d1d11EXAMPLE017b660d52a5fa5f2cb94cf0e1a9e9209dbea0826"
   

   • Your team ID (team slug). This is the value after /app/ in your Smallstep console URL.
   • Your agent CA fingerprint. Find this value in your console:
     • In the Smallstep console, select Authorities
     • Select the Smallstep Agents authority
     • Use the sha256 Root fingerprint displayed on this page

Finally, enable and start the agent:

sudo systemctl daemon-reload
sudo systemctl enable --now step-agent

If you get any errors, check the agent’s status:

sudo systemctl status step-agent.service

The Smallstep agent stores the certificate on the filesystem alongside a TPM TSS2-formatted file, which is a reference to a TPM-bound key. So, any software that integrates with OpenSSL's tpm2-openssl provider, or with the underlying libtpm2-tss, can use the TPM-bound key for TLS handshakes or other purposes.

Because PKCS#11 is a common integration point, the Smallstep agent also provides a PKCS#11 server for use with software like NetworkManager, wpa_supplicant, or web browsers. The PKCS#11 server is exposed as a UNIX socket at $XDG_RUNTIME_DIR/step-agent/step-agent-pkcs11.sock.

For this example, we’re using Ubuntu 24.04. The location of p11-kit-client.so may vary.

Let’s make client certificates and keys from the agent available to Google Chrome via PKCS#11 tokens. We will use modutil and an NSS database. Google Chrome defaults to storing an NSS database in ~/.pki/nssdb, so we can leverage that.

To use Smallstep certificates in Chrome, run:

modutil -dbdir ~/.pki/nssdb -add step-agent \
        -libfile /usr/lib/x86_64-linux-gnu/pkcs11/p11-kit-client.so
export P11_KIT_SERVER_ADDRESS=unix:path=$XDG_RUNTIME_DIR/step-agent/step-agent-pkcs11.sock

Next, start Chrome from the command line.

In Chrome, you should now have access to certificates managed by Smallstep.

For regular usage, add P11_KIT_SERVER_ADDRESS to your environment more permanently. For example, you might add P11_KIT_SERVER_ADDRESS=unix:path=$XDG_RUNTIME_DIR/step-agent/step-agent-pkcs11.sock to your global /etc/environment file.

The agent produces a log file or journal entries in systemd, depending on how it is installed and run.

You can use tools like pkcs11-tool for troubleshooting PKCS#11 support:

pkcs11-tool --module /usr/lib/x86_64-linux-gnu/pkcs11/p11-kit-client.so \
         --list-slots

See the p11-kit documentation for more details.

To uninstall the Smallstep Agent from a Linux system:

1. Remove the agent package:

   For Fedora/RHEL/Enterprise Linux:

   sudo dnf remove step-agent-plugin
   

   For Debian/Ubuntu:

   sudo apt-get remove step-agent-plugin
   

2. Optionally, remove configuration and certificate files:

   sudo rm -rf /etc/step-agent /var/lib/step-agent /run/step-agent
   

• macOS 10.15 (Catalina) or later
• The agent must be installed for a single user (multi-user deployments are not yet supported)
• Installation location: /Applications/SmallstepAgent.app

1. Download the latest package from packages.smallstep.com

2. Install the package on your endpoint (double-click the .pkg file, or use the built-in installer command)

Your agent needs to enroll with your team. To self-enroll a device, run:

/Applications/SmallstepAgent.app/Contents/MacOS/SmallstepAgent register <team-id>

Replace <team-id> with your Team ID from the Smallstep UI (found in Settings → Team).

There's two ways to confirm installation on a macOS endpoint:

• In the Smallstep UI, go to the device's profile page. In the Device Registration section, you'll see an Enrolled At timestamp.
• On the device itself, run /Applications/SmallstepAgent.app/Contents/MacOS/SmallstepAgent version to see that the agent is installed. And, in System Settings, check Login Items to confirm that there is a Smallstep Agent entry.

To uninstall the Smallstep Agent from a macOS system:

1. Run the following to uninstall the launch agent and remove runtime state:

   /Applications/SmallstepAgent.app/Contents/MacOS/SmallstepAgent svc uninstall
   /Applications/SmallstepAgent.app/Contents/MacOS/SmallstepAgent reset
   rm /Library/LaunchAgents/com.smallstep.launchd.Agent.plist
   

2. Remove the application directory:

   rm -rf /Applications/SmallstepAgent.app
   

3. Remove the package receipt:

   if pkgutil --packages | grep -q com.smallstep.Agent; then
       pkgutil --forget com.smallstep.Agent
   fi
   

• Windows 10 (Anniversary Edition) or later
• Windows Home is not supported
• A TPM 2.0 module is required
• We support amd64 and arm64 architectures

1. Download the agent installer from the Smallstep releases page:

   • For most systems: step-agent-plugin_amd64_<version>.msi
   • For ARM64 systems: step-agent-plugin_arm64_<version>.msi

2. Install the agent silently:

   msiexec.exe /i "path\to\step-agent-plugin_amd64.msi" /quiet
   

Before you begin, create an API token with at least all “device” scopes (put-device, patch-device, etc.)

1. On the device, configure the agent for enrollment:

New-Item -Path "HKLM:\Software\Policies\Smallstep"
Set-ItemProperty -Path "HKLM:\Software\Policies\Smallstep" -Name "TeamSlug" -Value "<team-slug>"
Set-ItemProperty -Path "HKLM:\Software\Policies\Smallstep" -Name "CAFingerprint" -Value "<agents-ca-fingerprint>"

Replace <team-slug> and <agents-ca-fingerprint> with your Smallstep team ID and the CA fingerprint of your Smallstep Agents CA.

2. On the device, navigate to the agent installation directory and obtain the device's TPM fingerprint:

cd 'C:\Program Files\Smallstep\SmallstepApp\'
.\smallstep-agent.exe tpm --fingerprint

3. Register the device's TPM using Add Device and the following request body:

{
  "os": "Windows",
  "ownership": "company",
  "permanentIdentifier": "<tpm-ek-fingerprint>",
  "user": {
    "email": "<user-binding-email>"
  }
}

4. Approve the device in the Smallstep console

5. Restart the device OR manually ensure the Smallstep Agent Windows service is started

After installation and configuration, the agent will automatically register with your Smallstep team. You can verify registration in the Smallstep UI by checking the device's profile page for an Enrolled At timestamp in the Device Registration section.

To confirm the agent is installed and running on Windows:

• In the Smallstep UI, go to the device's profile page. In the Device Registration section, you'll see an Enrolled At timestamp.
• On Windows, check that the agent service is running in the Services control panel, or run: sc query "Smallstep Agent"

To uninstall the Smallstep Agent from a Windows system:

msiexec /x "{EDB2FA84-917D-4156-AA1A-4BC5BB10C682}" /quiet

Alternatively, uninstall via the Windows "Add or Remove Programs" settings.