> For the complete documentation index, see [llms.txt](https://docs.devolutions.net/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.devolutions.net/powershell-universal/config/environments.md). # Environments Configure PowerShell Universal execution environments, including isolated PowerShell versions, virtual environments, Devolutions Agent execution, and minimal mode. 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](/powershell-universal/security/security.md#environment) 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](https://github.com/Devolutions/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: ```powershell 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. ```powershell 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: ```powershell 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. ```powershell 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`: ```powershell 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: ```powershell 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`. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.devolutions.net/powershell-universal/config/environments.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.