smallstep · joshdrake · Jul 27, 2026
@@ -1,5 +1,5 @@
 ---
-updated_at: June 9, 2026
+updated_at: July 27, 2026
 title: Install the Smallstep Agent
 html_title: Install the Smallstep Agent on macOS, Windows, and Linux
 description: Install, configure, and deploy the Smallstep Agent on macOS, Windows, and Linux endpoints. Includes manual install, MDM integration, system requirements, and network endpoints.
@@ -267,7 +267,7 @@ curl -fsSL https://packages.smallstep.com/scripts/smallstep-agent-install.sh | s
 3. Install the Smallstep agent
 
     ```bash
-    sudo apt-get update && sudo apt-get -y install step-agent openssl-tpm2-engine
+    sudo apt-get update && sudo apt-get -y install step-agent
     ```
 
 4. Check that it was installed correctly
@@ -333,13 +333,19 @@ If you get any errors, check the agent’s status:
 sudo systemctl status step-agent.service
 ```
 
-### OpenSSL and PKCS#11 support
+### PKCS#11 support
+
+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 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.
+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.
+
+<Alert severity="info">
+  Module registration requires Smallstep agent v0.67.4 or later.
+</Alert>
 
-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`. 
+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.
 
 #### Example usage: Google Chrome
 
@@ -352,14 +358,14 @@ 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
+export P11_KIT_SERVER_ADDRESS=unix:path=/run/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.
+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](./troubleshooting-agent.mdx#pkcs11-not-working-linuxmacos).
 

@@ -1,5 +1,5 @@
 ---
-updated_at: February 03, 2026
+updated_at: July 27, 2026
 title: Troubleshooting Guide
 html_title: Smallstep Troubleshooting Guide
 description: Troubleshoot Smallstep Device Identity issues. Diagnose platform, MDM, and endpoint problems with step-by-step guidance.
@@ -313,7 +313,7 @@ Each check validates a specific aspect of the agent's functionality. A **PASS**
 **Troubleshooting steps:**
 1. Verify the PKCS#11 socket exists:
    ```bash
-   ls -l $XDG_RUNTIME_DIR/step-agent/step-agent-pkcs11.sock
+   ls -l /run/step-agent/step-agent-pkcs11.sock
    ```
 2. Check the environment variable:
    ```bash
@@ -323,7 +323,7 @@ Each check validates a specific aspect of the agent's functionality. A **PASS**
    ```bash
    pkcs11-tool --module /usr/lib/x86_64-linux-gnu/pkcs11/p11-kit-client.so --list-slots
    ```
-4. See [PKCS#11 Support](./smallstep-agent.mdx#openssl-and-pkcs11-support) for configuration details
+4. See [PKCS#11 Support](./smallstep-agent.mdx#pkcs11-support) for configuration details
 
 #### Advanced doctor options
 
@@ -479,11 +479,11 @@ The location of `p11-kit-client.so` may vary by distribution.
 1. Verify PKCS#11 socket exists and is accessible
 2. Set environment variable correctly:
    ```bash
-   export P11_KIT_SERVER_ADDRESS=unix:path=$XDG_RUNTIME_DIR/step-agent/step-agent-pkcs11.sock
+   export P11_KIT_SERVER_ADDRESS=unix:path=/run/step-agent/step-agent-pkcs11.sock
    ```
 3. Install p11-kit if not present
 4. Test with `pkcs11-tool --list-slots`
-5. See [PKCS#11 configuration guide](./smallstep-agent.mdx#openssl-and-pkcs11-support)
+5. See [PKCS#11 configuration guide](./smallstep-agent.mdx#pkcs11-support)
 6. See the [p11-kit documentation](https://p11-glue.github.io/p11-glue/p11-kit/manual/) for general PKCS#11 reference
 
 #### Cannot access a resource (wi-fi, VPN, web app)