[CON-287] Updated agent manual install docs & troubleshooting guide

manifest.json

@@ -70,9 +70,13 @@
               "path": "/platform/smallstep-app.mdx"
             },
             {
-              "title": "Deploy to Linux",
+              "title": "Deploy the Agent",
               "path": "/platform/smallstep-agent.mdx"
             },
+            {
+              "title": "Troubleshooting the Agent",
+              "path": "/platform/troubleshooting-agent.mdx"
+            },
             {
               "title": "Configure Browser Certificates",
               "path": "/tutorials/browser-certificate-setup-guide.mdx"

platform/enrollment-guide.mdx

@@ -1,5 +1,5 @@
 ---
-updated_at: November 11, 2025
+updated_at: January 05, 2026
 title: Device Enrollment Guide
 html_title: Device Enrollment Implementation Guide
 description: Step-by-step guide for device enrollment and inventory management. Set up secure certificate enrollment for all enterprise devices.
@@ -32,7 +32,7 @@ You can [manually invite users
 to join your Smallstep team](https://smallstep.com/app/?next=/users/invite),
 and they will be able to self-enroll devices
 using the [Smallstep Desktop App](./smallstep-app.mdx)
-or the [Smallstep Agent for Linux](./smallstep-agent.mdx).
+or the [Smallstep Agent](./smallstep-agent.mdx).
 
 By default, administrators
 must approve a new device
@@ -79,12 +79,27 @@ Devices added via API are automatically approved.
 but they will not be marked as high-assurance
 until Smallstep receives an attestation from the device.
 
-#### Example: I have a list of device identifiers
-
-For each device, use the [Add Device](https://gateway.smallstep.com/v2025-01-01/operations/PostDevices) endpoint to create a device.
+You'll need [an API token](https://smallstep.com/app/?next=/settings/api/tokens/add) with all “device” scopes (put-device, patch-device, etc.).
 
-Devices are automatically approved when added via API.
+Use the [Add Device](https://gateway.smallstep.com/v2025-01-01/operations/PostDevices) endpoint to create a device.
+- For Apple devices, the `permanentIdentifier` must be the device's 9-character serial number.
+- For TPM 2.0 devices, the `permanentIdentifier` must be the TPM Endorsement Key URI, in the format `urn:ek:sha256:ul3sYf6uQ6jVEXAMPLEXoAuHI10U8gTvEJ6bMj95LXI=`. (You can retrieve the EK URI by running `step agent tpm --fingerprint` on the device.)
+- To create and assign a user to a device, fill in the `user` fields.
 
 Once added,
-you'll see devices in the Smallstep console,
+the devices will be automatically approved.
+
+You can see the device using the [List Devices](https://gateway.smallstep.com/v2025-01-01/operations/ListDevices) endpoint:
+
+```bash
+set +o history
+echo "Authorization: Bearer [your API token]" > api_headers
+set -o history
+curl -sH @api_headers --request GET \
+  --url https://gateway.smallstep.com/api/devices \
+  --header 'Accept: application/json' \
+  --header 'x-smallstep-api-version: 2025-01-01' | jq
+```
+
+You'll also see new devices in the Smallstep console,
 under [Devices](https://smallstep.com/app/?next=/devices).

platform/smallstep-agent.mdx

@@ -1,19 +1,43 @@
 ---
-updated_at: November 06, 2025
-title: Smallstep Agent for Linux
-html_title: Smallstep Agent for Device Management Guide
-description: Deploy and configure Smallstep Agent on Linux. Automated device identity management and certificate renewal for enterprise Linux fleets.
+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 for Linux is a background component of the [Smallstep Desktop App](./smallstep-app.mdx).
-Choose one or the other depending on your deployment needs.
+
+The Smallstep Agent brings automated certificate management, device identity, and configuration management features to your endpoints.
 
 # Introduction
 
-While macOS, Windows, and ChromeOS can manage certificates and authentication settings via Mobile Device Management (MDM), Linux does not include automated remote management facilities. The Smallstep Agent brings vital certificate management features to your Linux users and endpoints. It can be installed independently on any Linux device running systemd.
+This guide covers **manual installation** of the Smallstep Agent on:
+
+* [Linux](#linux-installation)
+* [macOS](#macos-installation)
+* [Windows](#windows-installation)
+
+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.
+
+<Alert severity="info">
+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)
+</Alert>
+
+# 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`
 
-In this document, we will install, configure, and start the Smallstep Agent on a Linux device running systemd. We also show how to use the agent’s built-in PKCS#11 (smart card) service. With the PKCS#11 service, you can access Smallstep certificates and keys from applications that support PKCS#11.
+# Linux Installation
 
-# System Requirements
+## System Requirements
 
 - Supported operating systems:
     - Enterprise Linux (RHEL, CentOS Stream, Rocky Linux, Alma Linux, etc)
@@ -22,26 +46,20 @@ In this document, we will install, configure, and start the Smallstep Agent on a
     - 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:
+- 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
-- 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`
+    - certificates in `/var/lib/step-agent` and in your configured locations
 
-# Quick Install
+## Quick Install
 
-On a system with `bash` and `curl`, run the following:
+On a Linux system with `bash` and `curl`, run the following:
 
 ```bash
 curl -fsSL https://packages.smallstep.com/scripts/smallstep-agent-install.sh | sudo env STEP_AGENT_TEAM=[your-team] bash
 ```
 
-
-# Manual Install
+## Manual Install
 
 ### Fedora
 
@@ -194,7 +212,7 @@ curl -fsSL https://packages.smallstep.com/scripts/smallstep-agent-install.sh | s
 
 Users can configure the agent and register their Linux device with your Smallstep team by running:
 
-```jsx
+```bash
 sudo step-agent-plugin register [team name]
 ```
 
@@ -209,7 +227,7 @@ Alternatively, you can pre-register all of your team's devices:
    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.
 
-   ```jsx
+   ```bash
    team: "myteamname"
    fingerprint: "40523785c1d1d11EXAMPLE017b660d52a5fa5f2cb94cf0e1a9e9209dbea0826"
    ```
@@ -225,14 +243,14 @@ Alternatively, you can pre-register all of your team's devices:
 
 Finally, enable and start the agent:
 
-```jsx
+```bash
 sudo systemctl daemon-reload
 sudo systemctl enable --now step-agent
 ```
 
 If you get any errors, check the agent’s status:
 
-```jsx
+```bash
 sudo systemctl status step-agent.service
 ```
 
@@ -277,3 +295,163 @@ pkcs11-tool --module /usr/lib/x86_64-linux-gnu/pkcs11/p11-kit-client.so \
 
 See the [p11-kit](https://p11-glue.github.io/p11-glue/p11-kit/manual/) documentation for more details.
 
+## Uninstall
+
+To uninstall the Smallstep Agent from a Linux system:
+
+1. Remove the agent package:
+
+   **For Fedora/RHEL/Enterprise Linux:**
+   ```bash
+   sudo dnf remove step-agent-plugin
+   ```
+
+   **For Debian/Ubuntu:**
+   ```bash
+   sudo apt-get remove step-agent-plugin
+   ```
+
+2. Optionally, remove configuration and certificate files:
+
+   ```bash
+   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
+
+1. Download the latest package from [packages.smallstep.com](https://packages.smallstep.com/stable/darwin/step-agent-plugin_latest.pkg)
+
+2. 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](https://smallstep.com/app/?next=/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:
+
+1. Run the following to uninstall the launch agent and remove runtime state:
+
+   ```bash
+   /Applications/SmallstepAgent.app/Contents/MacOS/SmallstepAgent svc uninstall
+   /Applications/SmallstepAgent.app/Contents/MacOS/SmallstepAgent reset
+   rm /Library/LaunchAgents/com.smallstep.launchd.Agent.plist
+   ```
+
+3. Remove the application directory:
+
+   ```bash
+   rm -rf /Applications/SmallstepAgent.app
+   ```
+
+4. Remove the package receipt:
+
+   ```bash
+   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
+
+1. Download the agent installer from the [Smallstep releases page](https://github.com/smallstep/step-agent-plugin/releases):
+   - For most systems: `step-agent-plugin_amd64_<version>.msi`
+   - For ARM64 systems: `step-agent-plugin_arm64_<version>.msi`
+
+2. Install the agent silently:
+
+   ```powershell
+   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](https://smallstep.com/app/?next=/settings/api/tokens/add) 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](https://smallstep.com/app/?next=/settings) 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](https://gateway.smallstep.com/v2025-01-01/operations/PostDevices) 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](https://smallstep.com/app/?next=/devices)
+
+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.
+
+## 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:
+
+```powershell
+msiexec /x "{EDB2FA84-917D-4156-AA1A-4BC5BB10C682}" /quiet
+```
+
+Alternatively, uninstall via the Windows "Add or Remove Programs" settings.
+

platform/smallstep-api.mdx

@@ -1,5 +1,5 @@
 ---
-updated_at: November 06, 2025
+updated_at: January 05, 2026
 title: Smallstep API
 html_title: Platform API Reference Documentation Guide
 description: Complete API reference for managing devices, certificates, and PKI programmatically. Integrate Smallstep into your security workflows.
@@ -32,31 +32,4 @@ You can get an API token in two ways:
 ### Example: Add devices via the API
 
 You can import devices from any source into Smallstep using our API.
-
-Devices added via API are automatically approved.
-but they will not be marked as high-assurance
-until Smallstep receives an attestation from the device.
-
-Use the [Add Device](https://gateway.smallstep.com/v2025-01-01/operations/PostDevices) endpoint to create a device.
-- For Apple devices, the `permanentIdentifier` must be the device's 9-character serial number.
-- For TPM 2.0 devices, the `permanentIdentifier` must be the TPM Endorsement Key URI, in the format `urn:ek:sha256:ul3sYf6uQ6jVEXAMPLEXoAuHI10U8gTvEJ6bMj95LXI=`. (You can retrieve the EK URI by running `step agent tpm --fingerprint` on the device.)
-- To create and assign a user to a device, fill in the `user` fields.
-
-Once added,
-the devices will be automatically approved.
-
-You can see the device using the [List Devices](https://gateway.smallstep.com/v2025-01-01/operations/ListDevices) endpoint:
-
-```bash
-set +o history
-echo "Authorization: Bearer [your API token]" > api_headers
-set -o history
-curl -sH @api_headers --request GET \
-  --url https://gateway.smallstep.com/api/devices \
-  --header 'Accept: application/json' \
-  --header 'x-smallstep-api-version: 2025-01-01' | jq
-```
-
-Or, in your Smallstep console,
-you'll see the device listed under Recent Devices.
-
+See [Build Your Inventory](./enrollment-guide.mdx) for details.