> For the complete documentation index, see [llms.txt](https://docs.stepsecurity.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.stepsecurity.io/developer-machines/installation/script.md).

# Script

The **Script** page generates a ready-to-deploy installation package for Dev Machine Guard. It walks you through a four-step wizard: pick an operating system, choose a deployment pattern, set your configuration, then review and generate the output.

The page supports **macOS, Windows,** and **Linux**. The deployment patterns, scheduler mechanisms, configuration fields, and generated output all adapt to the operating system you select in Step 1.

For the underlying delivery model (loader script versus signed installer) and the binary verification flow, see the [Installation](https://docs.stepsecurity.io/developer-machines/installation.md) overview.

### Generating an installation package

The wizard has four steps. Use **Continue** to advance and **Previous** to go back. Your selections carry through to the output generated at the end.

#### Step 1: Operating system

Select the target platform: **macOS, Windows,** or **Linux**. Your choice determines the loader type, the available deployment patterns, the scheduler used, the configuration fields shown, and the format of the generated output.

<figure><img src="https://754495266-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FQJRZY4cfEeY3I7DXTOCp%2Fuploads%2FyC6pC0n2UMOmYPUo8dHQ%2FScreenshot%202026-07-01%20at%2015.00.50.png?alt=media&amp;token=cf3dc939-1a8a-4a5a-9604-6d29507f9659" alt=""><figcaption></figcaption></figure>

#### Step 2: Deployment pattern

Choose how you want to run the agent. The available options depend on the operating system selected in Step 1.

On macOS and Windows, patterns are grouped by intent under **Get started** (try it on a single machine) and **Scale deployment via MDM** (roll out to many machines). Linux offers its two patterns directly, without the MDM grouping.

**macOS**

* Get started: **One-time execution** (recommended) runs the script once for an on-demand scan; **Scheduled via launchd** installs a LaunchAgent so it runs on a schedule on this machine.
* Scale via MDM: **MDM-scheduled** (recommended) has your MDM run the script on a recurring schedule; **Scheduled via launchd** pushes once via MDM and the agent self-schedules via launchd.

<figure><img src="https://754495266-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FQJRZY4cfEeY3I7DXTOCp%2Fuploads%2FFLSkUYs8i9XvYgXDD2U4%2FScreenshot%202026-07-01%20at%2015.01.03.png?alt=media&amp;token=a085e5f5-138b-4ae2-b41a-da3f579bc7ba" alt=""><figcaption></figcaption></figure>

**Windows**

* Get started: **One-time execution** (recommended) runs the script once for an on-demand scan; **Scheduled via Task Scheduler** registers a Scheduled Task so it runs on a schedule on this machine.
* Scale via MDM: **Win32 app** (recommended) produces a `.intunewin` package for Microsoft Intune; **MSI installer** provides the signed `.msi` for SCCM / Configuration Manager.

<figure><img src="https://754495266-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FQJRZY4cfEeY3I7DXTOCp%2Fuploads%2FdmiBO7aTX2w8vMcjZFcd%2FScreenshot%202026-07-01%20at%2015.24.41.png?alt=media&amp;token=1979865f-f744-4835-a982-c3d4c9570bcf" alt=""><figcaption></figcaption></figure>

**Linux**

* **One-time execution** runs the script once per invocation.
* **Repeated execution** registers a systemd user timer to run on a schedule on this machine.

<figure><img src="https://754495266-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FQJRZY4cfEeY3I7DXTOCp%2Fuploads%2Fk1vdjXwMTKXlPdIRbBWz%2FScreenshot%202026-07-01%20at%2015.32.44.png?alt=media&amp;token=92bc560b-d2c5-46f2-afaa-8af92cbb7ddf" alt=""><figcaption></figcaption></figure>

For step-by-step fleet rollout guides, see [MDM Deployment](https://docs.stepsecurity.io/developer-machines/installation/script/mdm-deployment.md).

#### Step 3: Configuration

The configuration fields depend on the operating system and deployment pattern selected.

**Scan frequency** (self-scheduling patterns only)

Sets how often the agent scans the device after install, in hours (default `4`). It appears whenever the agent runs on its own recurring schedule: Windows Task Scheduler, the Linux systemd user timer (Repeated execution), and the macOS scheduled and MDM-scheduled patterns. On Windows MSI deployments it maps to the `SCANFREQUENCY` property. It does not appear for one-time execution, where there is no recurring schedule.

**Agent version**

* **Latest** (loader-based and Win32-app patterns): the agent resolves the newest release on each run. The page shows the version currently resolved as latest. This enables automatic updates. See [Auto-updating](#auto-updating).
* **Pin specific version**: lock the install to a known release.
* **MSI version** (Windows MSI installer pattern): the MSI version to install. Select it from the dropdown. From v1.18.1, MSI installs then update themselves. See [Automatic Updates](https://docs.stepsecurity.io/developer-machines/installation/script/mdm-deployment/windows/automatic-updates-windows-msi.md) (Windows MSI).

**Inactive threshold**

Sets the number of days after which a device with no telemetry is marked inactive in the device list. This applies to all devices and is saved to your organization settings when you generate. The same setting can be managed later on the [Settings](https://docs.stepsecurity.io/developer-machines/installation/settings.md) page.

**Advanced configuration**

Expand this section to control install location, scan scope, and package scanners. On Windows MSI deployments these values are delivered via the MSI bootstrap file.

* **Install directory**: where the agent binary and logs live. Leave blank for the default: `~/.stepsecurity` on macOS and Linux, `%ProgramData%\StepSecurity` on Windows.
* **Scan directories**: one absolute path per line. Leave blank to scan the user's home directory.
* **Include TCC-protected directories** (macOS): scan Documents, Downloads, and similar locations. Requires Full Disk Access.
* **Package scanners**: choose which package ecosystems to scan (**npm, Homebrew, Python**).
* **Scan timeout**: maximum run time, in hours.
* **Stale-process age**: kill hung runs after this many hours.

<figure><img src="https://754495266-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FQJRZY4cfEeY3I7DXTOCp%2Fuploads%2Fh5SSfRNhkVCEcfYyjZpl%2FScreenshot%202026-07-01%20at%2015.01.19.png?alt=media&amp;token=7c6c1bfb-fa53-4870-bafb-6e3f868a17ce" alt=""><figcaption></figcaption></figure>

#### Step 4: Review and generate

Review a summary of every selection. Hover a field to jump back and edit it, then select **Generate script** (or **Regenerate script** after a change).

The generated output depends on the deployment pattern:

* **Script patterns** (one-time execution, scheduled, repeated, MDM-scheduled) produce a loader script you copy or download, plus deployment instructions. The script is named for the platform and tenant, for example `stepsecurity-loader-linux-<customer>.sh`.

<figure><img src="https://754495266-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FQJRZY4cfEeY3I7DXTOCp%2Fuploads%2FOCZbAGPhJVQRZouimhCm%2FScreenshot%202026-07-01%20at%2015.01.43.png?alt=media&amp;token=daa2792b-52fe-4ec4-a7a1-9b1348887ac5" alt=""><figcaption></figcaption></figure>

* **Win32 app** (Windows) produces the **Install** and **Uninstall** command lines to use when adding the `.intunewin` package as a Win32 app in Intune, along with a link to the [Intune guide](https://docs.stepsecurity.io/developer-machines/installation/script/mdm-deployment/windows/microsoft-intune.md). Download the `.intunewin` from the GitHub release.

<figure><img src="https://754495266-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FQJRZY4cfEeY3I7DXTOCp%2Fuploads%2FkQH9PpJlBDkYybijWtkK%2FScreenshot%202026-07-01%20at%2015.27.31.png?alt=media&amp;token=45a080f3-81f5-412d-b91b-9f25d140dc2b" alt=""><figcaption></figcaption></figure>

* **MSI installer** (Windows) produces the architecture-specific MSI download URLs (x64 and ARM64), a `bootstrap.json` to pre-stage tenant credentials and advanced scan configuration, and a link to the [SCCM guide](https://docs.stepsecurity.io/developer-machines/installation/script/mdm-deployment/windows/microsoft-configuration-manager-sccm.md).

<figure><img src="https://754495266-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FQJRZY4cfEeY3I7DXTOCp%2Fuploads%2FYdvJzlJtVGfqr7uXP7u7%2FScreenshot%202026-07-01%20at%2015.28.31.png?alt=media&amp;token=1658ce50-0409-4ed7-a39c-eae502adc171" alt=""><figcaption></figcaption></figure>

For the exact upload and configuration steps in each MDM tool, follow the linked guide rather than the summary values alone.

### Deploying the output

For script patterns, copy the script from the page or use **Download**, then deploy it through your MDM or EDR tooling. Because the loader handles binary download, version checking, and execution, no further configuration is required on the device. For a quick proof of concept, run the script on your own machine to see results right away.

For Windows Win32-app and MSI patterns, follow the [Windows MDM Deployment](https://docs.stepsecurity.io/developer-machines/installation/script/mdm-deployment/windows.md) guides, which cover credential passing (inline MSI properties versus a pre-staged bootstrap file), architecture selection, upgrades, and uninstall.

#### Fleet deployment via MDM

For step-by-step guides on deploying at scale, see [MDM Deployment](https://docs.stepsecurity.io/developer-machines/installation/script/mdm-deployment.md):

* **Windows** — [Microsoft Configuration Manager (SCCM/MEMCM)](https://docs.stepsecurity.io/developer-machines/installation/script/mdm-deployment/windows/microsoft-configuration-manager-sccm.md), [Microsoft Intune](https://docs.stepsecurity.io/developer-machines/installation/script/mdm-deployment/windows/microsoft-intune.md)
* **macOS** — [Iru](https://docs.stepsecurity.io/developer-machines/installation/script/mdm-deployment/macos/iru-formerly-kandji.md), [Jamf Pro](https://docs.stepsecurity.io/developer-machines/installation/script/mdm-deployment/macos/jamf-pro.md)

### Setting a custom device ID

You can give a device an identity you control by setting a custom `device_id` in the agent's `config.json`. Scans, scheduling, hooks, and device policies use that ID, and the hardware serial number is still reported separately. Changing a device's ID resets its scan schedule, and its next scan reports the full inventory. Setting a custom device ID requires agent **v1.18.1 or later**. Identity templates require **v1.19.0 or later**.

Set the `device_id` in either of two ways.

**Interactive configuration**

Run the `configure` command and provide your preferred `device_id` when prompted:

```
./stepsecurity-dev-machine-guard configure
```

**Non-interactive configuration**

Set the `device_id` through a JSON configuration file:

```
echo '{"device_id": "my-device-123"}' > /tmp/dmg.json
./stepsecurity-dev-machine-guard configure --non-interactive --from-file /tmp/dmg.json
```

#### **Using an identity template**

From v1.19.0, `device_id` can also be a template made of literal text and these tokens:

| Token        | Expands to                                                                                                                       |
| ------------ | -------------------------------------------------------------------------------------------------------------------------------- |
| `{serial}`   | The machine identity, normally the hardware serial number                                                                        |
| `{hostname}` | The machine name, in lowercase. A host with no usable name (empty, `unknown`, or `localhost`) uses its machine identity instead. |

Use `{hostname}` for pooled virtual desktops that are rebuilt under the same names, so a rebuilt host keeps its device record and history. See Azure Virtual Desktop (AVD).

```
./stepsecurity-dev-machine-guard configure --device-id "{hostname}"
```

On Windows MSI installs, set the same value with the `DEVICEID` MSI property or the `device_id` key in the bootstrap file. A literal ID uses 1 to 256 ASCII letters, digits, or `@ . _ + -`. A template with an unknown token logs a warning, and the device falls back to its hardware serial.

**Precedence.** The `STEPSEC_DEVICE_ID` environment variable, set machine-wide, overrides `device_id` in `config.json` on every run. With neither set, the hardware serial is used.

**Check the result.** `configure show` prints what the template resolves to on the device right now. `./stepsecurity-dev-machine-guard identity --json` prints the device ID the machine reports under and where it came from.

### Auto-updating

**Loader-based deployments support automatic updates.** When you set **Agent version** to **Latest** in Step 3, devices pick up the most recent published release on their next scheduled run, with no further action required from you.

**To enable auto-update:**

1. Open the **Script** page.
2. In **Step 3: Configuration**, set **Agent version** to **Latest**.
3. Complete the wizard and generate.

Devices that already have the loader deployed pick up the change on their next scheduled run, and every subsequent release is delivered the same way. You do not need to redeploy the loader through MDM.

**How often updates arrive.** Devices check for a new release once per scheduled run. On self-scheduling patterns, the cadence is set by **Scan frequency**.

**Windows MSI updates itself.** From v1.18.1, devices installed with the **MSI installer** pattern download, verify and switch to new releases on their own, through a separate Update task. StepSecurity sets which release your tenant's devices take. Devices on an MSI older than v1.18.1 need one final MSI deployment through your MDM (mobile device management). See [Automatic Updates](https://docs.stepsecurity.io/developer-machines/installation/script/mdm-deployment/windows/automatic-updates-windows-msi.md) (Windows MSI).

**Windows MSI is different.** The **MSI installer** pattern pins the binary at install time and does not auto-update in place. To upgrade an MSI fleet, deploy a newer MSI version through your MDM. See [Windows MDM Deployment](https://docs.stepsecurity.io/developer-machines/installation/script/mdm-deployment/windows.md).

**Is auto-update safe?** Yes. Every binary the loader downloads is cryptographically verified before it runs. The loader carries an embedded StepSecurity releases public key, and a release is only executed if its signed manifest verifies against that key and its SHA-256 matches. See the [Installation](https://docs.stepsecurity.io/developer-machines/installation.md) overview for the full verification flow.

{% hint style="info" %}
**Rolling back.** On loader-based patterns you can leave **Latest** at any time: set **Agent version** to a known-good pinned version and devices roll back on their next scheduled run. On MSI v1.18.1 or later, an MSI never downgrades a device, so contact StepSecurity support to move your tenant back to an earlier release.
{% endhint %}

### Pinning a specific version

If your environment requires change-controlled rollouts, or you want to validate a release in a staging fleet before promoting it, pin devices to a specific version instead of using **Latest**.

**To pin a version:**

1. Open the **Script** page.
2. In **Step 3: Configuration**, select **Pin specific version** (or, for Windows MSI, choose the desired **MSI version**) and pick the release from the list of published versions.
3. Complete the wizard and generate.

Loader-based devices move to the selected version on their next scheduled run. For MSI, the selected version is the one packaged for deployment. To roll out a later release, repeat with the new version selected.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.stepsecurity.io/developer-machines/installation/script.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
