> ## Documentation Index
> Fetch the complete documentation index at: https://docs.iru.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Custom Scripts Overview

> Deploy custom scripts to managed Mac and Windows devices using Iru Endpoint. Run shell, Python, PowerShell, or batch scripts on enrollment or on schedule.

<Callout icon="list-check" color="#B84A7A" iconType="regular">Custom Scripts are available for Mac computers and Windows devices</Callout>

### What is a Custom Script?

Custom scripts in Iru Endpoint are a powerful way to automate tasks and configure settings on managed devices. Think of them as a set of instructions that can be deployed and executed on enrolled devices using the Iru Agent. With custom scripts, you can configure device settings, install or update software applications, run maintenance tasks, and enforce security policies. You can also use custom scripts to collect device information, like hardware inventory or system logs. A collection of prebuilt and regularly maintained scripts is available in our [GitHub repository](https://www.github.com/kandji-inc/support/tree/main/Scripts).

<Tabs>
  <Tab title="Mac">
    <Note>
      Iru Endpoint's Custom Script Library Item can deploy scripts in various languages. However, our support team is best equipped to help troubleshoot scripts written in shell, bash, zshell, or Python. Support can also assist with AppleScript, provided it is invoked by one of the supported languages.
    </Note>

    ### How Custom Scripts Work

    The Iru Agent runs custom scripts on enrolled Mac computers. Your custom script can specify any shell or interpreter on the Mac computer. If a shell or interpreter is not specified, the default shell (/bin/sh) is used. Custom scripts are always executed as the root user.

    #### Execution Frequency

    Depending on the script you want to deploy, you can specify whether it will be run once at every check-in, once per day, or on-demand from Self Service.

    <AccordionGroup>
      <Accordion title="Install once per device">
        For **Install once per device**, Iru reruns the audit script at each check-in until the Library Item reaches **Pass** for that device. If a remediation script is enabled and succeeds, the Library Item can show **Remediated**, but Iru still reruns the audit script on later check-ins until it reaches **Pass**.
      </Accordion>

      <Accordion title="Run every 15 min">
        The script will be run at each check-in (\~ every 15 minutes).
      </Accordion>

      <Accordion title="Run daily">
        The script will be run every 24 hours based on the previous run time.
      </Accordion>

      <Accordion title="Run on-demand from Self Service">
        The script will never be run automatically and will only be offered as an optional item from Self Service. After executing the item, the **Run** button will be relabelled **Run again**.
      </Accordion>
    </AccordionGroup>

    <Callout icon="lightbulb" color="#2563EB" iconType="regular">
      The Custom Script Library Item can also be offered via Self Service in the first 3 scenarios above.
    </Callout>

    #### Exit Codes and Outputs

    <AccordionGroup>
      <Accordion title="Exit code results">
        If the audit script exits with code **0**, that run has **Pass** status. If the audit script exits with any non-zero exit code, that run has **Error** status. When a run has **Error** status, Iru generates an alert. See our [Global Alerts](/en/endpoint/devices/global-alerts) support article for details.
      </Accordion>

      <Accordion title="Script output logging">
        Stdout and Stderr are recorded in the script's audit information, which can be found on the device status page or custom script status page.
      </Accordion>
    </AccordionGroup>

    #### Remediation

    A remediation script allows the main **Audit Script** to be used as a true audit script to check for system configuration or application state. If the audit script exits with any non-zero exit code, that run has **Error** status; Iru then runs the remediation script.

    <Check>
      If the remediation script exits with code **0**, the Library Item status for that device is **Remediated**. If the remediation script exits with a non-zero exit code, the Library Item status for that device is **Error**, and Iru generates an alert. See our [Global Alerts](/en/endpoint/devices/global-alerts) support article for details.
    </Check>

    #### Restart Options

    The restart option allows you to force a restart after a successful script execution. When selecting this option, the user will receive a restart timer from the Iru Agent menu bar application. This timer will be a 5-minute restart timer if the item was initiated from Self Service or a 30-minute restart timer if initiated in another way such as during a check-in.

    <Tip>
      The restart option will behave differently based on the use of a remediation script:

      * If a [**Remediation** script](#remediation) is being used, when the **Remediation** script exits 0, this will trigger the restart countdown.
      * If a **Remediation** script *is not* being used, when the **Audit** script exits 0, this will trigger the restart countdown.
    </Tip>

    ### Add a Custom Script Library Item

    To add this Library Item to your Iru Endpoint Library, follow the steps outlined in the [Library Overview](/en/endpoint/library/library-items-profiles/library-overview) article.

    <Steps>
      <Step title="Name the Library Item">
        Give the new Custom Script Library Item a **Name**.
      </Step>

      <Step title="Assign to Blueprints">
        Assign to your desired [Blueprints](/en/endpoint/getting-started/blueprints-and-library/configuring-blueprints).
      </Step>

      <Step title="Select Execution Frequency">
        Select an **Execution Frequency**.
      </Step>

      <Step title="Configure Self Service (optional)">
        Optionally, make the script available in **Self Service**.
      </Step>

      <Step title="Add Audit Script">
        Paste your script into the **Audit Script** field.
      </Step>

      <Step title="Add Remediation Script (optional)">
        Optionally, configure and paste a **Remediation Script**.
      </Step>

      <Step title="Configure restart option (optional)">
        If desired, check the box to **Restart after a successful execution**.
      </Step>

      <Step title="Save configuration">
        Click **Save**.
      </Step>
    </Steps>

    ### Related Articles

    <CardGroup cols={2}>
      <Card title="Library Overview" icon="books" href="/en/endpoint/library/library-items-profiles/library-overview">
        Curate, create, and manage Library Items and add them to Blueprints
      </Card>

      <Card title="Configuring Blueprints" icon="cog" href="/en/endpoint/getting-started/blueprints-and-library/configuring-blueprints">
        Create and configure device Blueprints for policy management
      </Card>

      <Card title="Deploy Homebrew Using a Custom Script" icon="apple" href="/en/endpoint/library/deployment-guides/apple/deploy-homebrew-using-a-custom-script">
        Deploy Homebrew to Mac computers using a custom script
      </Card>

      <Card title="Global Variables" icon="code" href="/en/endpoint/library/library-items-profiles/global-variables">
        Learn how to use global variables in Iru Endpoint to dynamically insert device and user information into profiles, scripts, and configuration settings.
      </Card>

      <Card title="Global Alerts" icon="bell" href="/en/endpoint/devices/global-alerts">
        Configure how Iru Endpoint surfaces alerts when Custom Scripts or other Library Items report issues
      </Card>
    </CardGroup>
  </Tab>

  <Tab title="Windows">
    ### Windows Custom Script

    The **Windows custom script** Library Item allows you to run PowerShell scripts on managed Windows devices. You can use this item to audit device state, enforce configuration through remediation, or perform administrative tasks not covered by built-in Windows profiles.

    Windows custom scripts support an audit and remediation model, enabling detection of non-compliant states and automatically correcting them.

    ### Create a Windows Custom Scripts Library Item

    <Steps>
      <Step title="Navigate to Library">
        Navigate to **Library**.
      </Step>

      <Step title="Add Library Item">
        Select **Add Library Item**.
      </Step>

      <Step title="Select Windows Custom Script">
        Search for and select **Windows Custom Script**.
      </Step>

      <Step title="Enter Name">
        Enter a descriptive **Name**.
      </Step>

      <Step title="Confirm Status">
        Confirm the status is set to **Active**.
      </Step>

      <Step title="Assign to Blueprints">
        Assign the Library Item to one or more **Blueprints**.
      </Step>
    </Steps>

    ### Script Details

    The **Script details** section defines settings for audit and remediation scripts.

    #### Audit Script

    The **Audit script** determines whether the device is in the desired state.

    You can provide the audit script using one of the following options:

    * **Upload signed script**
      * Upload a signed PowerShell `.ps1` file.
    * **Manually enter script**
      * Paste or edit PowerShell code directly into the editor.

    <Note>
      The audit script should exit with a non-zero exit code when the device is not compliant. A zero exit code indicates compliance.
    </Note>

    #### Command Line Parameters (Optional)

    The **Command line parameters** field allows you to pass arguments to the audit and remediation scripts at runtime.

    * Use standard PowerShell parameter syntax.
    * Parameters are appended when the script executes.

    Example: `-Mode Full -ConfigPath "C:\Config.json"`

    <Tip>
      This is useful for making scripts reusable without hardcoding values.
    </Tip>

    #### Remediation Script (Optional)

    Select **Add remediation script** to configure a remediation action.

    * The remediation script runs only when the audit script reports non-compliance.
    * You can upload a signed script or manually enter remediation logic.
    * Use remediation scripts to correct configuration drift or enforce settings.

    <Note>
      The remediation script should exit successfully after the issue is resolved.
    </Note>

    #### Execute In

    Use **Execute in** to select the PowerShell environment used to run the scripts:

    * **64 bit**
    * **32 bit**

    **64 bit** runs the script in the standard 64-bit PowerShell environment and is recommended for most Windows devices.

    <Note>
      Use 32 bit only if the script or its dependencies require WOW64 compatibility.
    </Note>

    ### Assignment and Execution

    After saving the Library Item:

    1. Click **Save**.
    2. Assign it to one or more **Blueprints** using **+ Assign**.

    Scripts will execute once per device.

    ### Best Practices

    * Sign PowerShell scripts before uploading whenever possible.
    * Separate detection logic (audit) from enforcement logic (remediation).
    * Test scripts on non-production devices before wide deployment.

    ### Related Articles

    <CardGroup cols={2}>
      <Card title="Microsoft PowerShell Documentation" icon="book" href="https://learn.microsoft.com/powershell/">
        Official PowerShell docs from Microsoft
      </Card>

      <Card title="Everything about exceptions (PowerShell)" icon="book" href="https://learn.microsoft.com/en-us/powershell/scripting/learn/deep-dives/everything-about-exceptions">
        PowerShell exception handling
      </Card>

      <Card title="Global Alerts" icon="bell" href="/en/endpoint/devices/global-alerts">
        Configure how Iru Endpoint surfaces alerts when Windows Custom Scripts or other Library Items report issues
      </Card>
    </CardGroup>
  </Tab>
</Tabs>