updated_at	January 06, 2026
title	Deploy the Agent
html_title	Deploy the Smallstep Agent
description	Distribute and configure Smallstep Agent on Linux, macOS, and Windows. For organizations without MDM or using script-based deployment.

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

Introduction

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.

Using an MDM? See: - [Connect Jamf Pro to Smallstep](../tutorials/connect-jamf-pro-to-smallstep.mdx) (macOS) - [Connect Intune to Smallstep](../tutorials/connect-intune-to-smallstep.mdx) (Windows) - [Connect Workspace ONE to Smallstep](../tutorials/connect-workspace-one-to-smallstep.mdx) (Windows)

Network Access

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

Linux Installation

System Requirements

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

Quick Install

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

Manual Install

Fedora

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

Install the Smallstep agent:

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

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

Enterprise Linux (RHEL, CentOS Stream, Rocky Linux, Alma Linux, etc)

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

Install the Smallstep agent:

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

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

Debian

In the Terminal, install dependencies:

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

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

Install the Smallstep agent:

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

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

Ubuntu

In the Terminal, install dependencies:

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

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

Install the Smallstep agent

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

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

Registering and approving endpoints

Self-registration

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.

Pre-registration via API

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

Register and approve your devices via API. The devices you add via API will be pre-approved.
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

Start the agent

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

OpenSSL and PKCS#11 Support

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.

Example usage: Google Chrome

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.

Troubleshooting

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.

Uninstall

To uninstall the Smallstep Agent from a Linux system:

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
```

Optionally, remove configuration and certificate files:

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

macOS Installation

System Requirements

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

Manual Install

Download the latest package from packages.smallstep.com
Install the package on your endpoint (double-click the .pkg file, or use the built-in installer command)

Registering the Agent

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).

Confirmation

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.

Uninstall

To uninstall the Smallstep Agent from a macOS system:

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

Remove the application directory:
```
rm -rf /Applications/SmallstepAgent.app
```

Remove the package receipt:

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

Windows Installation

System Requirements

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

Manual Install

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

Install the agent silently:

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

Registering the Agent

Using the Smallstep API

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

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.

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

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

Approve the device in the Smallstep console
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.

Confirmation

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"

Uninstall

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.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Introduction

Network Access

Linux Installation

System Requirements

Quick Install

Manual Install

Fedora

Enterprise Linux (RHEL, CentOS Stream, Rocky Linux, Alma Linux, etc)

Debian

Ubuntu

Registering and approving endpoints

Self-registration

Pre-registration via API

Start the agent

OpenSSL and PKCS#11 Support

Example usage: Google Chrome

Troubleshooting

Uninstall

macOS Installation

System Requirements

Manual Install

Registering the Agent

Confirmation

Uninstall

Windows Installation

System Requirements

Manual Install

Registering the Agent

Using the Smallstep API

Confirmation

Uninstall

FilesExpand file tree

smallstep-agent.mdx

Latest commit

History

smallstep-agent.mdx

File metadata and controls

Introduction

Network Access

Linux Installation

System Requirements

Quick Install

Manual Install

Fedora

Enterprise Linux (RHEL, CentOS Stream, Rocky Linux, Alma Linux, etc)

Debian

Ubuntu

Registering and approving endpoints

Self-registration

Pre-registration via API

Start the agent

OpenSSL and PKCS#11 Support

Example usage: Google Chrome

Troubleshooting

Uninstall

macOS Installation

System Requirements

Manual Install

Registering the Agent

Confirmation

Uninstall

Windows Installation

System Requirements

Manual Install

Registering the Agent

Using the Smallstep API

Confirmation

Uninstall