devolutions/powershell-universal-skills/install-sandbox-psu

install-sandbox-psu

Spins up a fully isolated PowerShell Universal (PSU) sandbox — either by downloading a pre-built release from the Devolutions CDN or by building and publishing a local .NET project. Each sandbox gets its own data directory, port, log paths, and generated relaunch/teardown scripts, so multiple sandboxes of the same version can run side-by-side without interfering.

When to use

• Quickly test a released version of PSU without a system-wide install
• Run the current branch of a PSU source repo against a clean data directory
• Reproduce bugs in an isolated environment you can throw away
• Develop and test custom PSU components (pair with custom-component-generate-psu)

Prerequisites

• PowerShell 7 (pwsh)
• Internet access

Script

.agents/skills/install-sandbox-psu/scripts/Install-PSU.ps1

Parameters

Sandbox layout

Each sandbox lives at $env:TEMP\PSUSandbox-<version>-<sandboxId>\:

PSUSandbox-2026.1.3.0-a3f9c2\
  psu\                  PSU binaries (extracted zip or dotnet publish output)
  data\
    repository\         PSU configuration repository
    psu.db              SQLite database
  logs\
    systemlog.txt
  agent\logs\
    log.txt
  Dashboard\            UniversalDashboard assets folder
  sandbox.json          Stored config for reproducible relaunches
  Start-Sandbox.ps1     Auto-generated relaunch script (no rebuild)
  Remove-Sandbox.ps1    Auto-generated teardown script

Environment variables set

The following are set as process-scoped environment variables before launching the server, so the child process inherits them:

Port is auto-selected from the unused range 5001–6000 on first run and stored in sandbox.json for all subsequent runs.

Usage examples

Install and run the latest CDN release (empty sandbox)

pwsh .agents/skills/install-sandbox-psu/scripts/Install-PSU.ps1

Seed from the default demo Git repo

pwsh Install-PSU.ps1 -GitRepo

Seed from a custom Git repo

pwsh Install-PSU.ps1 -GitRepo https://github.com/myorg/my-psu-config -SandboxId myconfig

Seed from a local configuration directory

pwsh Install-PSU.ps1 -ConfigurationDirectory C:\myconfig -SandboxId myconfig

Install a specific version

pwsh Install-PSU.ps1 -PSUVersion 2025.3.1.0 -SandboxId testing

List all sandboxes

pwsh Install-PSU.ps1 -List

Tear down a sandbox

# Stops the process and deletes the entire folder
pwsh Install-PSU.ps1 -Teardown -SandboxId dev
 
# Or run the generated script directly
pwsh "$env:TEMP\PSUSandbox-local-dev\Remove-Sandbox.ps1"

If the teardown fails, don't force close any processes. Let the user know which locks are preventing cleanup so they can investigate or try again after a reboot.

Expected output

On successful start:

==========================================
  PSU Sandbox Started
  Version    : 2026.1.3.0
  Source     : cdn:2026.1.3.0
  SandboxId  : a3f9c2
  URL        : http://localhost:5001
  Process ID : 12345
  Root       : C:\Users\...\Temp\PSUSandbox-2026.1.3.0-a3f9c2
  Relaunch   : ...\Start-Sandbox.ps1
  Teardown   : ...\Remove-Sandbox.ps1
==========================================

Notes

• The CDN zip is cached in $env:TEMP and reused across sandbox instances of the same version — only the data directory is per-sandbox.
• sandbox.json stores the port and all paths. Re-running Install-PSU.ps1 with the same -SandboxId reuses the existing port and data, making runs reproducible.
• The script is idempotent: running it twice with the same -SandboxId starts the server against the existing data without re-downloading or re-extracting.