Environments

By default, authentication and authorization happen within the Universal.Server.exe process. To run these from a different process, you can select an environment by setting the -SecurityEnvironment parameter of Set-PSUSetting in settings.ps1. See Security for more information on this.

Execution environments define the PowerShell runtime, modules, variables, and execution settings used by scripts, APIs, apps, automation jobs, and security processes. Manage them under Manage > Environments > Environments or in environments.ps1.

Choose an environment type

Type	Use
Integrated	Runs directly in the PowerShell Universal server process.
PowerShell 7	Uses the PowerShell 7 host included with PowerShell Universal.
PowerShell 7 (Isolated)	Uses multi-pwsh to run a selected PowerShell 7 version, optionally in a managed virtual environment.
Windows PowerShell 5.1	Uses the Windows PowerShell runtime installed on the server.
Custom	Starts the executable and arguments you specify.
Container	Runs in the configured Devolutions Agent container image.

All environments can define modules, PowerShell variables, PSModulePath entries, startup scripts, and advanced runspace settings. Select an environment by name when configuring a script, schedule, API, app, terminal, or security environment.

Configure resources

Use the Resources tab when editing an environment to configure these settings:

• Modules: Module names or module-file paths that PowerShell Universal imports when it creates runspaces.
• Variables: Names of PowerShell Universal variables to make available. Use * to include all matching variables.
• PSModulePath: Additional module-search paths for the environment.
• Startup scripts: Repository-relative scripts that run when a new runspace is created.

Startup scripts run once for each new runspace. They run once when a job starts, but can run more often for APIs and apps as their runspaces are created. Platform variables are not available in startup scripts.

PowerShell 7 isolated environments

An isolated environment uses multi-pwsh instead of the PowerShell host included with PowerShell Universal. Choose this type when a script needs a specific PowerShell 7 release or stronger process isolation from the server's PowerShell SDK and loaded assemblies.

Every isolated environment must have a PowerShell version. PowerShell Universal rejects an isolated environment that does not specify one.

Install and select PowerShell versions

1. Go to Manage > Environments > PowerShell Versions.
2. Enter a multi-pwsh selector such as stable, preview, lts, or 7.4, then select Install.
3. Refresh the version list. It shows each version, its path, scope, and whether it is available for isolated environments.
4. Create or edit an environment, select PowerShell 7 (Isolated), and select an installed isolated version.

Only versions marked Isolated are selectable for isolated environments. You can remove multi-pwsh-installed versions from the same tab when they are no longer needed.

Create an isolated environment in configuration with a concrete version or a multi-pwsh selector:

New-PSUEnvironment `
    -Name 'Isolated PowerShell 7.4' `
    -Type Isolated `
    -PowerShellVersion '7.4'

Managed virtual environments

Enable Virtual on an isolated environment to run it in a managed multi-pwsh virtual environment. PowerShell Universal creates the virtual environment before it is used and selects it whenever the environment starts a job.

The managed virtual-environment identity is derived from the environment's name, PowerShell version, modules, PSModulePath, and startup-script settings. Changing those settings creates a new managed identity. PowerShell Universal cleans up managed virtual environments that are no longer referenced by an environment.

Use a virtual environment when you want the multi-pwsh runtime state to remain isolated from other environments. Container environments also use a managed virtual environment when Virtual is enabled or when the environment has modules configured.

New-PSUEnvironment `
    -Name 'Isolated PowerShell 7.4 virtual' `
    -Type Isolated `
    -PowerShellVersion '7.4' `
    -Virtual `
    -Modules @('Az.Accounts')

Devolutions Agent support

When a job targets a connected Devolutions Agent, PowerShell Universal uses the environment's PowerShell version selector with the agent's multi-pwsh executable. For an isolated or container environment that uses a managed virtual environment, the server exports that virtual environment and the agent imports it before the job starts.

This transfer is automatic and uses a short-lived, authenticated download URL. The agent reuses an already imported matching virtual environment. Configure the same environment normally, then choose the Devolutions Agent or computer group in the run or schedule options.

PowerShell 7 minimal environments

Enable Minimal on a PowerShell 7 environment to run jobs in a dedicated PowerShell subprocess through local PowerShell remoting. This mode avoids loading the normal PowerShell Universal hosting assemblies into the script process, which is useful for scripts and modules that have assembly-binding conflicts with the server.

Minimal mode is available for PowerShell 7, Windows PowerShell 5.1, and Custom environments. PowerShell Universal retains the job's formatted output and pipeline output from minimal PowerShell 7 runs, so output remains available in the job log and job history.

Minimal environments still have important limitations:

• They do not support feedback, progress reporting, secrets, or Universal integrated cmdlets.
• Configured non-secret variable values are provided as process environment variables.
• Use the normal PowerShell 7 environment when the script needs full PowerShell Universal host integration.

To enable it in the admin console, edit a PowerShell 7 environment and select Minimal. In configuration:

New-PSUEnvironment `
    -Name 'PowerShell 7 Minimal' `
    -Type PowerShell7 `
    -Minimal `
    -Variables @('*')

A Custom minimal environment can run another command-line executable. Use {scriptPath} in its arguments when the executable must receive the resolved script path.

New-PSUEnvironment `
    -Name 'Python' `
    -Path 'python' `
    -Arguments '{scriptPath}' `
    -Variables @('*') `
    -Minimal

Standard environments

Integrated

The Integrated environment runs scripts directly in the PowerShell Universal server process. It avoids interprocess serialization and is simple to configure, but cannot run as alternate credentials or use another PowerShell version. Because scripts share the server process, problematic scripts can affect platform stability.

The Integrated environment is always available. You can still configure modules or persistent runspaces for it in environments.ps1:

New-PSUEnvironment -Name 'Integrated' -Path 'none' -Modules @('ActiveDirectory')

PowerShell 7

The standard PowerShell 7 environment uses the PowerShell host included with PowerShell Universal. It is the recommended default for broad third-party module compatibility. If a script requires Windows Forms or another Windows PowerShell-only dependency, use Windows PowerShell 5.1 or a Custom environment instead.

Windows PowerShell 5.1

Windows PowerShell 5.1 uses the Windows PowerShell runtime installed on the server. Use it for scripts and modules that require Windows PowerShell.

Use environments across PowerShell Universal

• APIs: Set -ApiEnvironment with Set-PSUSetting in settings.ps1.
• Automation: Set -Environment for scripts and schedules, or select it when starting a job.
• Apps: Set -Environment with New-PSUApp.
• Security: Set -SecurityEnvironment with Set-PSUSetting when authentication and authorization should run outside the server process.

Windows PowerShell compatibility

PowerShell 7 can automatically use local Windows PowerShell remoting when a command or module is unavailable. This compatibility feature creates a Windows PowerShell process per runspace and can substantially increase process count, memory use, CPU use, and serialization overhead.

Disable implicit Windows PowerShell compatibility in the environment's Advanced tab when it is not required. It is disabled for the Integrated environment and cannot be enabled there.

If you must use compatibility, remove the compatibility session after the command completes:

Import-Module PSScheduledJob -UseWindowsPowerShell
Get-ScheduledJob | Out-Null
Get-PSSession -Name 'WinPSCompatSession' | Remove-PSSession

PowerShell cmdlets

Manage environments with New-PSUEnvironment, Get-PSUEnvironment, Set-PSUEnvironment, and Remove-PSUEnvironment.