The Smallstep Agent

Smallstep ensures that access to financial data, code repositories, PII, and other sensitive resources is only possible from trusted devices.

The Smallstep Agent offers a uniform experience for device identity across macOS, Windows, and Linux, and is foundational to Smallstep's high-assurance device attestation workflow, automating the enrollment and delivery of client certificates, and configuring the components that depend on them.

The agent runs as a background service on all platforms. On macOS and Windows, the agent includes an optional desktop app that provides visibility into the agent's status and aids in troubleshooting.

The Smallstep Agent operates differently for Linux. For Linux specific instructions, see Smallstep Agent for Linux.

On macOS and Windows, the Smallstep Agent includes an optional desktop app UI for transparency and troubleshooting. The agent runs as a background service on all platforms.

Installers for macOS, Windows and Linux can be also be downloaded from GitHub releases. Releases are signed with, and can be verified, by cosign.

• Windows 10 or later (Windows Home editions are not supported.)
• Trusted Platform Module (TPM 2.0)

• Flatpak, or Debian 12+, Ubuntu 22.04+, Fedora 38+
• systemd-based service manager
• Trusted Platform Module (TPM 2.0)
• p11-kit
• tpm-tss2

• macOS 13 (Ventura) or later
• Secure Enclave

All platforms require an internet connection for normal operation.

• Administrator privileges - the Smallstep Agent requires privilege escalation to be able to communicate to the TPM

• Location permission - to enable management of Wifi networks, the Smallstep Agent needs location permission
• Keychain access - the Smallstep 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 Smallstep 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

On all platforms, the Smallstep Agent creates and manages a directory on the filesystem in a well-known location for management of keys and certificates. However, it does not access any other file on a device except the one it creates.

• On macOS: $HOME/Library/Application Support/Smallstep
• On Windows: %LOCALAPPDATA%/Smallstep
• On Linux: $XDG_RUNTIME_DIR/step-agent and $XDG_CONFIG_HOME/step-agent

The Smallstep Agent collects and reports some data from the host device as part of its normal operation. These are:

• Device Identifiers from TPM-enabled platforms
• Device/Computer Name
• Device/Computer Hostname
• Chipset Architecture
• Operating System Version
• WAN IP Address