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
• Apple Silicon M1 or later
• The agent must be installed for a single user

• Supported operating systems:
  • Enterprise Linux (RHEL, CentOS Stream, Rocky Linux, Alma Linux, etc)
  • Ubuntu (Current Stable and LTS)
  • Debian (Current Releases)
  • Fedora (Current Releases)
  • NixOS
• 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.

On Windows and Linux, the agent supports multi-user environments, with a couple caveats: There's currently a 1:1 mapping in our backend between users and devices. This works well on shared systems. It only becomes a problem if user-based properties need to be included in credentials issued by the agent. Also, on Linux, a TPM access broker (eg. tpm2-abrmd) is needed when multiple processes are using the TPM.

• 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
• Telemetry: tel.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
   

3. Check that it was installed correctly:

   step-agent version
   

   Output:

   step-agent/0.67.3 (linux/amd64)
   Release Date: 2026-05-19 17:16 UTC
   

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
   

3. Check that it was installed correctly:

   step-agent version
   

   Output:

   step-agent/0.67.3 (linux/amd64)
   Release Date: 2026-05-19 17:16 UTC
   

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
   

4. Check that it was installed correctly:

   step-agent version
   

   Output:

   step-agent/0.67.3 (linux/amd64)
   Release Date: 2026-05-19 17:16 UTC
   

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
   

4. Check that it was installed correctly

   step-agent version
   

   Output:

   step-agent/0.67.3 (linux/amd64)
   Release Date: 2026-05-19 17:16 UTC
   

The step-agent package is in nixpkgs, on the nixos-unstable channel. NixOS has no services.step-agent module yet, so the system user, systemd service, and PKCS#11 wiring that the Debian and RPM packages install are declared in your own configuration instead.

1. If you track a stable NixOS channel, add an overlay so that pkgs.step-agent resolves. Skip this step on nixos-unstable.

   nixpkgs.overlays = [
     (final: prev: {
       inherit
         (import (builtins.fetchTarball "https://github.com/NixOS/nixpkgs/archive/nixos-unstable.tar.gz") {
           system = prev.stdenv.hostPlatform.system;
           config.allowUnfreePredicate = pkg: prev.lib.getName pkg == "step-agent";
         })
         step-agent
         ;
     })
   ];
   

2. Download step-agent.nix, place it alongside your configuration.nix, and add ./step-agent.nix to your imports list. The .nix file declares the step-agent system user, the systemd service and its restart path unit, the polkit rules the agent needs, and the p11-kit module that publishes our PKCS#11 server.

   curl -fsSLO https://files.smallstep.com/step-agent.nix
   

3. Rebuild your system:

   sudo nixos-rebuild switch
   

4. Register the device with your team:

   sudo step-agent register [team name]
   

   Registration writes agent.yaml into /etc/step-agent, which systemd creates and keeps writable through ConfigurationDirectory=. Do not manage agent.yaml with environment.etc: that produces a read-only symlink into the Nix store, and the service refuses to start.

5. Check that it was installed correctly:

   step-agent version
   

   Output:

   step-agent/0.67.3 (linux/amd64)
   Release Date: 2026-05-19 15:50 UTC
   

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

sudo step-agent 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
sudo systemctl enable --now step-agent-restart.path

On NixOS, nixos-rebuild switch enables and starts both units, so skip this step.

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

sudo systemctl status step-agent.service

Keys managed by the Smallstep agent are bound to the device's TPM and cannot be exported. To let other software use those keys for TLS handshakes and other purposes, the agent runs a PKCS#11 server, exposed as a UNIX socket at /run/step-agent/step-agent-pkcs11.sock.

PKCS#11 is the supported integration point for software like NetworkManager, wpa_supplicant, VPN clients, and web browsers.

The Linux packages register the agent as a PKCS#11 module for you, by installing /etc/pkcs11/modules/step-agent.module. Software that discovers modules through p11-kit picks up the agent's keys with no further configuration.

NSS-based applications, such as Google Chrome and Firefox, don't read p11-kit module configuration. For those, register the module manually, as shown below.

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, first point the p11-kit client library at the agent's running PKCS#11 socket, then register it with modutil:

export P11_KIT_SERVER_ADDRESS=unix:path=/run/step-agent/step-agent-pkcs11.sock

modutil -dbdir ~/.pki/nssdb -add step-agent \
        -libfile /usr/lib/x86_64-linux-gnu/pkcs11/p11-kit-client.so

On NixOS, p11-kit-client.so lives in the Nix store rather than under /usr/lib. Point modutil at it with -libfile $(nix eval --raw nixpkgs#p11-kit)/lib/pkcs11/p11-kit-client.so.

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=/run/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
   

   For Debian/Ubuntu:

   sudo apt-get remove step-agent
   

   For NixOS: remove ./step-agent.nix from your imports list, then run sudo nixos-rebuild switch.

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\SmallstepAgent\'
.\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.