---
title: "Run scripts on endpoints"
description: "Run an approved script on endpoints, sites, or device groups now, schedule it on a timetable or at sign-in, and read each endpoint's result."
url: "https://support.outpostplatform.com/automation/run-scripts/"
product: "depot"
type: "how-to"
status: "draft"
ai_summary: "Run a library script from Scripts > Library > Actions > Run against chosen endpoints, sites, or device groups; follow it in Scripts > Batches, where each endpoint's state and exit code are listed and undelivered commands can be canceled. Schedules (Scripts > Schedules) run approved scripts on a cron timetable or at sign-in, optionally offline. Needs command:execute and script:schedule."
availability:
  plans: ["home-lab", "essentials", "enterprise", "msp"]
  platforms: ["windows", "linux", "macos", "freebsd", "openbsd"]
  permission: "command:execute"
  preview: false
source: "https://gitlab.com/outpostplatform/docs/-/edit/main/src/content/docs/automation/run-scripts.md"
license: "CC BY 4.0"
---

# Run scripts on endpoints

This page runs a script from the library on endpoints, either once, as a
batch, or on a schedule, and shows where to read each endpoint's result. The
script must be approved to run on more than one endpoint or on a schedule. See
[Write and approve a script](/automation/write-and-approve-scripts/).

## Before you begin

- To run a script or cancel a run you need `command:execute`. To create or
  change a schedule you need `script:schedule`.
- On the MSP plan, open the client's workspace first. Runs and schedules belong
  to one client.
- The endpoints must accept the script's interpreter. See
  [Interpreters](/automation/scripting/#interpreters).

## Run a script now

1. Go to **Scripts** > **Library**.
2. On the script's row, select **Actions** > **Run**.
3. Under **Where it runs**, choose the target:
   - **Choose endpoints**: search for endpoints and add them.
   - **Sites**: choose one or more sites. Select **Include endpoints in child
     sites** to reach their child sites too.
   - **Device groups**: choose one or more device groups.

   An endpoint whose operating system or interpreters do not match the script
   is marked with the reason.
4. Under **Parameters**, enter the values the script asks for.
5. Under **How it runs**, choose **Run as**: **SYSTEM** or **Signed-in user**.
6. In **Give up after (hours)**, keep the default of `4` or change it. An
   endpoint that stays offline longer than this never runs the script, and its
   command is marked expired.
7. Select **Review**, check the summary, and select **Run script**.

Connected endpoints receive the command straight away. The others receive it
when they reconnect, until the time you set runs out.

To run a script on one endpoint while you look at it, open the endpoint and use
its **Commands** tab.

## Follow a run

**Scripts** > **Batches** lists every run started from the library, with its **Script**, **Target**, number of **Endpoints**, **Started**,
**Expires**, and who started it.

1. Select **Open** on a run.
2. The counts show how many endpoints are **Pending**, **Dispatched**,
   **Succeeded**, **Failed**, **Timed out**, **Expired**, or **Canceled**.
3. The table lists each endpoint with its **State**, **Exit code**, **Started**,
   and **Finished** times. Select **Output** on a row to read what the script
   printed, on that endpoint's command history.
4. Select **Refresh** to update the page.

To stop a run, select **Cancel run**. Canceling stops commands that have not
reached an endpoint yet. A script already running on an endpoint finishes and
reports back as usual.

## Schedule a script

1. Go to **Scripts** > **Schedules** and select **New schedule**.
2. In **Name**, enter a name.
3. In **Script**, choose an approved script. Only approved scripts can be
   scheduled.
4. In **Trigger**, choose when it runs:
   - **On a schedule**: in **Repeats**, choose **Every hour**, **Every day**,
     **Every week**, **Every month**, or **Custom expression**, then set the
     **Day**, **Day of month**, **Hour**, and **Minute**. **Day of month** goes
     up to 28, so the schedule never skips a short month. For **Custom
     expression**, enter a standard five-field **Cron expression**.
   - **When a user signs in**: runs on the endpoint each time somebody signs in.
     To pass the signed-in user's name to the script, use the `{{login.user}}`
     placeholder in a parameter value.
5. For **On a schedule**, choose the **Time zone**. It is a named zone, such as
   `America/Chicago`, so the time stays right through daylight saving changes.
6. In **If the server was down when it was due**, choose **Run it once, late**
   or **Skip it and wait for the next one**. A schedule never runs a burst of
   catch-up runs.
7. Select **Run on the endpoint even when it cannot reach the server** to let
   each endpoint fire the schedule from its own copy while it is offline. A
   sign-in schedule always runs on the endpoint.
8. Under **Where it runs**, choose the endpoints, sites, or device groups.
9. Enter the **Parameters**, choose **Run as**, and set **Timeout (seconds)**.
10. Make sure **Enabled** is selected, and select **Save schedule**.

A schedule runs the script's current approved version, with its signature. If
the script is changed and returns to draft, the schedule stops firing until the
script is approved again.

To change or remove a schedule, select **Edit** or **Delete** on its row in
**Scripts** > **Schedules**.

## Verify

- For a run: in **Scripts** > **Batches**, open the run. Each endpoint you
  targeted shows **Succeeded** with exit code `0` once it has run.
- For a schedule: in **Scripts** > **Schedules**, the row shows **Next due**
  and **Last fired**. Select **Runs** to list each occurrence with its **Due**
  time, **Endpoint**, **State**, **Result**, and whether it was **Fired by the
  server** or **Fired by the endpoint**.

## If something goes wrong

| Symptom | Cause | Fix |
| --- | --- | --- |
| Rows stay **Pending** | The endpoints are offline. | Wait for them to reconnect, or raise **Give up after (hours)** on the next run. |
| Rows show **Expired** | The endpoint stayed offline past the time you set. | Run the script again when the endpoint is online. |
| Rows show **Timed out** | The script ran longer than its timeout or `script_execution.max_runtime_seconds`. | Raise the timeout on the script or the run, or the profile setting. |
| A sign-in schedule never fires on an endpoint | The endpoint cannot see sign-ins: a Windows agent not running as a service, a Linux endpoint without systemd-logind, or a FreeBSD or OpenBSD endpoint. | Run the agent as a service, or use a timed schedule. |
| **Signed-in user** cannot be chosen | Nobody is signed in, or the platform cannot run as the user. | Run as **SYSTEM**. See [Platform differences](/automation/scripting/#platform-differences). |

## Next steps

- [Endpoint custom fields](/automation/custom-fields/)
- [Built-in script library](/automation/script-library/)