Before you begin
- Atlas Reach enabled for the tenant, with the Atlas Reach agent installed and approved on your devices
- Script running turned on for your Atlas AVD deployment. It is off by default; see Before you start: turn on script running below
- The reach.script permission to run scripts. A schedule needs the permission of its action (see Permissions)
- To run scripts from your Scripts library: the Starter plan or higher. Ad-hoc scripts do not need it
Before you start: turn on script running
Running scripts is off on every new Atlas AVD deployment, so no one can run code on your devices until you decide to allow it. While it is off, Run a script and scheduled script runs are refused with "Script execution is not enabled on this deployment". Atlas AVD runs in your own Azure subscription, so an Azure administrator turns it on in the Azure portal:
- Open the App Service (web app) that runs Atlas AVD in your subscription.
- Go to Settings → Environment variables, and on the App settings tab click Add.
- Enter the name ATLAS_REMOTE_SCRIPT_RUN_ENABLED and the value true (lower case).
- Click Apply, then Apply again to confirm. The app restarts and script running is available within a few minutes.
Scripts run on your devices with full rights (LocalSystem on Windows, root on macOS and Linux) unless you choose otherwise. Turn script running on only once your roles are set up so that only the people who should run scripts hold reach.script. To turn it off again, delete the setting or set it to false.
Run a script on a device
Open Atlas Reach → Devices and, on the device's row, choose Run a script. The Run script dialog opens.
- Choose the source. Ad-hoc script: pick an interpreter and paste or type the script. Script library: pick a script from your Scripts library; Atlas runs the latest version (or the version you choose) exactly as it was saved, and the script's interpreter is used.
- Optionally open Run options to set who the script runs as, its arguments, environment variables and working directory (see Run options).
- Click Run. The output, the exit code and any errors appear in the dialog once the device finishes. Click Run another to run a second script.
- Every run is also kept on the device's Jobs tab, under Script runs, so you can come back to the output later.
- A script is stopped after 60 seconds by default. You can raise the timeout to up to 15 minutes.
- If the device is a session host that is powered off, Atlas can power it on first; the dialog shows Powering on the device while it starts.
Run options
- Run as: System (LocalSystem / root), the default, runs as the agent's service identity. Logged-on user runs in the signed-in user's session, which you need for HKCU, the user profile or OneDrive; it fails if no one is signed in.
- Arguments: one positional argument per line, up to 64. For a library script that declares parameters, the arguments come from those parameters instead.
- Environment variables: NAME=value, one per line, up to 64. To pass a secret, use {{secret.NAME}} as the value. Atlas fills it in from Atlas Vault when the script runs and redacts the value from the captured output.
- Working directory: where the script starts. Leave it blank for the agent's default.
A script can be up to 256 KB. The agent captures up to 256 KB each of standard output and error output; anything beyond that is cut off and the run is marked as truncated. A device whose agent is too old to support run options says so in the dialog, and the run may be refused.
Interpreters
Atlas Reach runs PowerShell, CMD, Batch, bash, zsh, sh and python scripts. The interpreter must exist on the device: CMD and Batch are Windows only, PowerShell on macOS and Linux needs PowerShell 7 (pwsh) installed, and python scripts need Python installed on the device. When you run one script on several devices, Atlas warns you if the interpreter is not available on all of them, and those devices report an error.
Run a script on many devices
On Atlas Reach → Devices, tick the devices in the grid, then choose Run script. The dialog for the selection works like the single-device dialog, with a timeout per device, and shows a result for each device as it finishes. Each device's result is also kept on its own Jobs tab, under Script runs.
- A script run reaches up to 500 devices at a time, whether you tick them or run it on a device group.
- Other bulk actions under Bulk actions (deploy software, install updates, agent update and the rest) run on up to 500 ticked devices, or on up to 10,000 devices when you run them on a device group.
- The Bulk jobs card on the Devices tab tracks the runs you start from Bulk actions and how many are still in progress. Open a job to see each device's result.
- Devices that cannot take part, for example because they are offline or not yet approved, are listed as skipped with the reason.
Create an Automation schedule
A schedule runs an action on a set of devices on a recurrence. Open Atlas Reach → Automation and click New schedule.
- Enter a name, for example Nightly disk cleanup, and an optional description.
- Choose the action (listed below). The action cannot be changed once the schedule is created.
- Under When, choose Daily, Weekly (with a day of the week) or Monthly (with a day of the month), the time in 24-hour format, and the timezone. Times follow the timezone's daylight saving changes. On a monthly schedule, a day the month does not have (such as the 31st) runs on the month's last day.
- Under Target, choose a host pool, a tag, specific devices or a device group. Devices are matched each time the schedule fires, so new devices in the pool, tag or group are included automatically.
- Choose what happens if a device is offline when the schedule fires: Skip offline devices, or Run when the device reconnects.
- Fill in the action's options and click Create schedule.
Schedule actions
- Run a script: an ad-hoc script with its interpreter, or a script from your Scripts library. A library script runs its latest approved version at every fire. Library scripts that declare parameters cannot be scheduled yet; run them from the Run script dialog.
- Deploy software: install, uninstall or upgrade a package, with the same mechanisms as a manual deploy. A file-based install needs a source URL and the file's SHA-256.
- Install approved Windows Updates: each device installs the updates your patch policy approves (or auto-approves) for it, based on its latest scan. There is nothing else to choose.
- Reboot: with an optional delay and a message to signed-in users.
- Agent self-update check: each device runs its normal self-update check now.
- Run network discovery: each target device scans its own network, as Run discovery on the Discovered tab does.
Deploy software, Install approved Windows Updates and Reboot change the device, so they respect your maintenance windows and blackouts.
Manage schedules
- The Schedules list shows each schedule's cadence, target, next run, last run and whether it is enabled.
- Use the switch to pause and resume a schedule, Run now to fire it straight away, Edit to change it, and Delete to remove it.
- Run history opens Recent fires: when each fire ran, how many devices it was dispatched to, and how many were queued or skipped.
- With Run when the device reconnects, an offline device runs the action when it comes back, as long as that is within 24 hours of the fire.
- A tenant can have up to 200 schedules.
Permissions
- Running a script, on one device or many, needs reach.script.
- A schedule needs the permission of its action: reach.script for Run a script; reach.deploy for Deploy software, Install approved Windows Updates and Agent self-update check; reach.control for Reboot and Run network discovery.
- Viewing schedules and their history needs reach.view.
- Library scripts also need the Scripts feature, which is included from the Starter plan.
Troubleshooting
- "Script execution is not enabled on this deployment": script running is off. Follow Before you start: turn on script running.
- Run a script is greyed out with "You don't have permission to run scripts": your role does not have reach.script. Ask an administrator.
- The run fails at once on some devices: the interpreter is missing there, or, for Logged-on user, no one is signed in.
- A script stops early: it hit its timeout. Raise the timeout, up to 15 minutes.
- Output ends abruptly: it passed 256 KB and was cut off. Write long output to a file on the device instead.
- A scheduled fire shows no targets: no device matched the host pool, tag, devices or group when it fired. Check the target and the devices' tags.