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

The agent runs as a background service on all platforms. Smallstep also has an optional desktop UI for transparency and troubleshooting, offered as a separate package.

This guide covers installation of the Smallstep Agent on:

• Linux
• macOS
• Windows

Running into trouble? See the Smallstep Agent troubleshooting guide.

• Windows 10 or later (Windows Home editions are not supported)
• Trusted Platform Module (TPM 2.0)
• Architectures: amd64, arm64

• macOS 13 (Ventura) or later
• Secure Enclave
• The agent must be installed for a single user (multi-user deployments are not yet supported)

• Supported operating systems:
  • Enterprise Linux (RHEL, CentOS Stream, Rocky Linux, Alma Linux, etc)
  • Ubuntu (Current Stable and LTS)
  • Debian (Current Releases)
  • Fedora (Current Releases)
• systemd-based service manager
• A TPM 2.0 module is required. Smallstep depends on TPMs to create a high-assurance device inventory.
• p11-kit, tpm-tss2
• Architectures: amd64, arm64

All platforms require an internet connection for normal operation.

• Administrator privileges — the Smallstep Agent requires privilege escalation to be able to communicate with the TPM.

• Location permission — only required if the agent will manage Wi-Fi network configurations.
• Keychain access — the agent uses the macOS keychain to store both keys and certificates it manages.
• Network Extension entitlement — the Smallstep Agent requests the Network Extension entitlement so that it can manage VPN connections.

• TPM read/write permission — the Smallstep Agent communicates to the TPM from user-space using tpm-tss2, and the running user must have read/write permissions to the TPM resource manager (typically /dev/tpmrm0).

The agent connects 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

See releases.smallstep.com for all release history of the Smallstep Agent, Smallstep Desktop app, and more.

Here are URLs that always point at the latest stable release of the agent:

macOS

• step-agent_latest.pkg

Windows

• step-agent_amd64_latest.msi
• step-agent_arm64_latest.msi

Linux

• step-agent_amd64_latest.deb
• step-agent_arm64_latest.deb
• step-agent_x86_64_latest.rpm
• step-agent_aarch64_latest.rpm
• step-agent_amd64_latest.pkg.tar.zst
• step-agent_arm64_latest.pkg.tar.zst

Smallstep also offers Debian and RPM package repositories.

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://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
   

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. As a result, 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.

If PKCS#11 isn't working as expected, see PKCS#11 troubleshooting.

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
   

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 <team-id>
   rm /Library/LaunchAgents/com.smallstep.launchd.Agent.plist
   

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

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
   

Install the agent via Winget:

winget install Smallstep.step-agent

To upgrade, run winget upgrade Smallstep.step-agent. To uninstall, run winget uninstall Smallstep.step-agent.

1. Download the agent installer:

   • For most systems: step-agent_amd64_latest.msi
   • For ARM64 systems: step-agent_arm64_latest.msi

2. Install the agent silently:

   msiexec.exe /i "path\to\step-agent_amd64_latest.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, run the following PowerShell:

& cmd /c "$(((Get-ItemProperty HKLM:\Software\Microsoft\Windows\CurrentVersion\Uninstall\* | Where-Object { $_.DisplayName -like "*Smallstep Agent*" }).UninstallString -replace '/I', '/X')) /quiet"

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