ship’s manual · guide

Install on Windows

There is nothing to download and no Windows application to install. 1Helm runs its ordinary Linux build inside a WSL 2 distribution named 1helm, and your browser is the interface at http://localhost:8123. Because no .exe ships, nothing needs code signing and SmartScreen never appears.

What you need

• Windows 11 on an x64 processor. Arm64 Windows is not supported by this build.
• Virtualization enabled in firmware, as WSL 2 requires.
• Internet access, and roughly 10 GB of free disk.
• One Windows restart, partway through.
• You do not need to install WSL first. The command below does that for you.

Install

The whole install is one command, run twice, with a Windows restart in between. This is the command:

irm https://1helm.com/install.ps1 | iex

Now, in order:

1. Open PowerShell. The ordinary one — do not choose “Run as Administrator”.
2. Paste the command above and press Enter.
3. A Windows permission pop-up appears. Click Yes.
4. Wait about a minute. The window ends by printing “Restart required” and a short numbered list. That is normal. It is not an error and nothing is lost.
5. Restart the PC.
6. Sign back in as the same Windows user, and open PowerShell again.
7. Paste the same command again and press Enter.
8. Wait about six and a half minutes. Pages of apt output scroll past; that is normal progress. When it is finished it prints the address and opens your default browser on the onboarding page.
9. Create the Captain, connect a provider, and name the workspace.

Measured end to end on a real Windows 11 machine: about 8 minutes 49 seconds, restart included.

Why the permission pop-up, and why only there

Exactly two operations need administrator rights: turning on the Windows optional features Microsoft-Windows-Subsystem-Linux and VirtualMachinePlatform, and installing Microsoft’s own WSL package. Those run in one separate elevated pass, and that pass is the only pop-up you see. Microsoft’s WSL installer is checked against a pinned SHA-256 and required to carry a valid Microsoft Authenticode signature before it is run.

Everything after that — importing the distribution, installing 1Helm inside it, registering the keepalive — deliberately runs as the signed-in user, because WSL state is per-user. A distribution imported by an elevated session started with different credentials would belong to that administrator instead of to the person using the machine. That is also why step 6 says the same Windows user.

Why the restart

Windows cannot activate those two features without restarting. The first run says so plainly and stops; the second run detects what is already done and carries on from there. Every step is idempotent, so running the command again is always safe.

Things you may see

• Microsoft’s “Welcome to WSL” window. It may open during the second run. It is Microsoft’s own window, it is harmless, and you can close it.
• A wait after 1Helm reports it is running. The channel-computer runtime needs roughly another 40 seconds to finish preparing before your first channel computer can be created. It has not hung.
• Pages of apt output. That is the Linux installer doing the long step — the container runtime and the channel image.

If you download the script instead of piping it

Windows blocks running downloaded .ps1 files, so a saved copy needs the explicit form:

powershell -NoProfile -ExecutionPolicy Bypass -File .\install.ps1

The irm … | iex one-liner is unaffected, because it pipes a string into PowerShell rather than executing a file.

Using it

Open http://localhost:8123 in any browser on that PC; the installer also adds a Start Menu shortcut that opens the same address in your default browser. WSL tears an idle distribution down seconds after its last session closes, so the installer registers a per-user scheduled task — the keepalive — that holds the distribution open, starts again when you sign in, and restarts 1Helm’s service if it stops.

One behaviour difference from earlier versions: #main’s Terminal is now bash inside the WSL distribution, not cmd.exe. Windows commands do not work there. That is deliberate — the host is Linux now.

Updates

A Windows host updates exactly like a Linux host, because it is one: the root-owned updater inside the distribution downloads the exact stable Linux release artifact, requires its published SHA-256 digest, installs into a versioned directory, switches atomically, health-checks, and restores the previous release if anything fails. There is no Windows update feed and no Windows artifact, so there is nothing to sign and no signing status to disclose.

Uninstall

From an ordinary PowerShell window, signed in as the user who installed it:

irm https://1helm.com/uninstall.ps1 | iex

It stops the keepalive, runs 1Helm’s own Linux uninstaller inside the distribution so its containers and services come out cleanly, then unregisters the 1helm distribution and removes C:\1helm and the Start Menu shortcut. Other WSL distributions on the PC are never touched, and Windows’ own WSL feature is left installed.

This destroys data. Unregistering the distribution deletes its virtual disk, and every channel’s files, the workspace database, and your provider credentials all live on that disk. There is no undo and nothing is copied to Windows first, so download anything irreplaceable from http://localhost:8123 before you start. The script asks you to type remove first; -Force skips that prompt and exists only for scripted removal.

Troubleshooting

It printed “Restart required” and stopped. That is the expected halfway point, not a failure. Restart, sign back in as the same Windows user, open PowerShell, and run the same command again.

“Running scripts is disabled on this system.” You are running a downloaded .ps1 file. Use the -ExecutionPolicy Bypass -File form above, or use the irm … | iex one-liner, which is not affected.

A “Welcome to WSL” window opened. That is Microsoft’s, not ours. Close it and carry on.

Port 8123 is already in use. Windows and every WSL distribution share one network namespace, so anything already listening on 8123 — another distribution, or an ordinary Windows process — stops 1Helm binding it. The installer refuses to continue rather than half-install, and names the port. Stop whatever owns it, then run the command again.

Do I need to install WSL first? No. Nothing to prepare, nothing to download.

The browser cannot reach the address. Give it a moment after the installer finishes, then ask the service inside the distribution how it is doing:

wsl -d 1helm -u root --exec systemctl status 1helm

Arm64 Windows. Not supported by this build. The installer checks first and stops with that exact reason.