Project Launcher#

The project launcher is the first screen you see when you run psw wizard with no arguments. It’s where you decide which user project to work with – either by creating a new one or opening one you’ve worked on before. (The launcher belongs to the installer UI; once a project is bootstrapped you switch to psw dashboard, which opens an existing project directly and has no launcher screen of its own.)

What It Looks Like#

Two cards sit side by side, each with an icon and a clear description:

• New Project (plus icon) – Type a folder path (e.g. /home/you/homelab) and hit “Create Project”. PSW creates the folder and drops you into the Setup Wizard . If the folder already exists, the launcher shows an error asking you to use “Open Project” instead – this prevents accidentally overwriting an existing project.
• Open Project (folder icon) – Type the path to an existing project folder and hit “Open Project”. PSW detects what state the project is in and takes you to the right place: the wizard if setup isn’t finished, or operations mode if everything is already deployed.

If you’ve opened projects before, a Recent Projects list appears above the cards showing your history. Each entry shows the project name, path, and current status (Operational, Setting up, New, or Missing if the folder was deleted). Click one to jump straight in. The small x button removes it from the list without deleting any files.

Why It Exists#

PSW needs to know where your project lives before it can do anything – your project folder is the single source of truth for your entire setup. The launcher is the one place where that decision is made. Once you pick a folder, the project path is locked in for the rest of the session. The wizard’s Start step shows it as read-only so there’s no confusion about where things are being saved.

Skipping the Launcher#

If you already know the path, pass it directly:

psw wizard --project ~/homelab

This skips the launcher entirely and goes straight to the wizard or operations mode, depending on the project’s state.

How It Detects Project State#

The launcher uses phase detection to figure out what state each project is in. It checks for specific files (project.yml, hardware.yml, .psw/converge/state.yml, etc.) and labels each project accordingly:

What Happens Next#

After you pick or create a project, the launcher redirects you to the right screen inside the wizard app – whichever step matches the project’s current phase :

• Mid-wizard project – you land on the next unfinished step (Start / Hardware / Plan / Install / Launch).
• Already-operational project – you land on the Launch screen, which shows a completion panel with your SSO credentials and a direct link to the deployed dashboard at https://dashboard.<your-domain>. From then on you use operations mode (via psw dashboard or that URL), not the wizard.

You never pick – the launcher detects the state from files on disk and redirects accordingly.