Skip to main content

Run macOS Scripts as the Logged-In User with Outset

What

By default, FileWave Client scripts on macOS run as root. That is the right context for most device-level work, but it is not always the right context for settings that belong to the current user session.

Outset is a MacAdmins Open Source utility that can run scripts and packages during boot, at the login window, during user login, or on demand. A common FileWave workflow is to deploy Outset with FileWave, then deploy scripts into Outset's login folders so they run as the logged-in user at login.

This article covers macOS. Outset is not a Windows tool. For Windows user-context scripting, see Execute Powershell Scripts as Defined User.

When to use this

Use this approach when the script needs the logged-in user's context instead of the FileWave Client's root context. Common examples include per-user application preferences, Dock customization, user LaunchAgents, user keychain-aware tasks, or settings that write into the user's home folder.

Do not use this as a replacement for normal FileWave scripts that need root privileges. Software installation, system configuration, profile deployment, and device-level changes should usually remain in FileWave scripts, Fileset payloads, or MDM profiles.

Requirements

  • macOS 10.15 or later, based on Outset's current project requirements.
  • FileWave Central access to deploy the Outset package and your script Fileset.
  • The Outset release package from the Outset releases page.
  • For macOS 13 or later, a managed Login Items profile is recommended so users do not have to approve or enable Outset manually.

How it works

Outset watches specific folders under /usr/local/outset/. For user-context login scripts, the two most useful folders are:

  • /usr/local/outset/login-once/: runs a script once per user, then records that it has run in the user's Outset preferences.
  • /usr/local/outset/login-every/: runs a script at every user login.

When Outset processes login scripts, it runs them in the user context and passes the current console user as the first argument. In most scripts, $HOME and whoami should reflect the logged-in user instead of root.

If multiple scripts exist in the same folder, Outset processes them in alphanumeric order. Prefix filenames with numbers, such as 001-configure-dock.zsh, when ordering matters.

Basic FileWave workflow

  1. Download the current Outset release package from GitHub.
  2. Create a FileWave Fileset that installs the Outset package on target Macs.
  3. Create a separate Fileset for the script or scripts you want Outset to run.
  4. Place each script in the correct Outset folder in the Fileset payload, such as /usr/local/outset/login-once/ or /usr/local/outset/login-every/.
  5. Ensure scripts are owned by root and have permissions 755. Outset will not process scripts that fail its ownership or permission checks.
  6. Associate the Outset Fileset first, then the script Fileset. Run a Model Update after making the deployment changes.
  7. Have the user log out and back in, or test during the next normal login.

Example script

The following example writes a small log entry in the current user's Library folder. It is intentionally simple; replace the example action with the per-user setting you need to apply.

#!/bin/zsh

outset_user="$1"
log_file="$HOME/Library/Logs/filewave-outset-example.log"

{
  echo "Outset ran at: $(/bin/date)"
  echo "Outset user argument: ${outset_user}"
  echo "whoami: $(/usr/bin/whoami)"
  echo "HOME: ${HOME}"
} >> "$log_file"

exit 0

To run this once for each user, deploy it to a path like:

/usr/local/outset/login-once/001-filewave-user-context-example.zsh

To run it at every login, deploy it to:

/usr/local/outset/login-every/001-filewave-user-context-example.zsh

Script ownership and permissions

Outset enforces script ownership and permissions before it runs items from its processing folders. Scripts must be owned by root and have permissions 755.

If your Fileset does not already preserve the required ownership and mode, use a Fileset script or postflight action to correct them after installation:

#!/bin/zsh

script_path="/usr/local/outset/login-once/001-filewave-user-context-example.zsh"

/usr/sbin/chown root:wheel "$script_path"
/bin/chmod 755 "$script_path"

exit 0

macOS 13 and later: managed Login Items

On macOS 13 and later, background services appear in System Settings under Login Items. Outset recommends deploying a managed Login Items profile for io.macadmins.Outset so the service is treated as managed by the organization.

Apple documents the Managed Login Items payload in Apple Platform Deployment: Manage login items and background tasks on Mac.

Testing and troubleshooting

  • Test with a small script that writes to $HOME/Library/Logs/ before deploying a script that changes user settings.
  • Confirm the script is in the intended folder: login-once for one-time per-user work, or login-every for repeated login work.
  • Check that the file is executable and owned by root.
  • Remember that login-once is tracked per user. If the same script has already run for that user, changing the script content may not make it run again. Use a new filename, use Outset's override feature, or use login-every when repeated runs are expected.
  • Review Outset logs in the Outset logs directory under /usr/local/outset/.

If you need to run a command immediately as the current console user from a FileWave root-context script, see Execute macOS scripts as Defined User. That method is useful for targeted commands. Outset is better when the work naturally belongs at login or should run once per user across multiple users on the same Mac.

References

Back to top