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.

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.

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.

Next steps

• Endpoint custom fields
• Built-in script library