From d4edcdfa6a98d8c37287f5fdc94fced291bd907b Mon Sep 17 00:00:00 2001 From: Joseph Yaksich Date: Sun, 2 Aug 2026 06:21:48 +0000 Subject: [PATCH] release: 0.0.38 with accurate Windows first-run documentation Cuts 0.0.38 and corrects the public documentation for the Windows first-run experience that 0.0.37 and 0.0.38 actually fixed. A typical new Windows 11 PC has WSL and VirtualMachinePlatform disabled. 1Helm enables both itself, which requires one Windows restart partway through setup. The README, website manual, getting-started guide, and user guide now state that plainly: WSL is not a prerequisite, the single UAC prompt, the PowerShell progress window that must stay open, the restart as a normal step rather than an error, and resuming by reopening 1Helm as the same Windows user. SmartScreen on the unsigned Setup executable is disclosed honestly. Also adds the per-platform install and removal paths the repository front page never documented, first-run troubleshooting for all three platforms, and the two Settings sections (Notifications, Feedback) the user guide omitted. The website's disclosed Authenticode version is release-coupled, so test/site.mjs now derives it from package.json instead of pinning a literal that goes stale on every patch bump. Release pins: version, changelog, and local/1helm-channel-machine:0.0.38. Co-Authored-By: Claude Fable 5 --- CHANGELOG.md | 3 ++ README.md | 84 ++++++++++++++++++++++++++------- docs/GOVERNANCE.md | 5 +- docs/USER_GUIDE.md | 62 +++++++++++++++++++++--- docs/VISION.md | 2 +- package-lock.json | 4 +- package.json | 2 +- site/content.mjs | 4 +- site/manual.html | 20 ++++++++ src/server/channel-computers.ts | 2 +- src/server/db.ts | 2 +- test/channel-computers.mjs | 2 +- test/site.mjs | 5 +- 13 files changed, 164 insertions(+), 33 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index b6389af..43c7491 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] +## [0.0.38] - 2026-08-02 + ### Fixed - Windows first-run no longer reports "Shared runtime setup failed" when all @@ -1036,6 +1038,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 Application Support, and isolated Apple container machines. [Unreleased]: https://github.com/gitcommit90/1Helm/compare/v0.0.36...HEAD +[0.0.38]: https://github.com/gitcommit90/1Helm/compare/v0.0.30...v0.0.38 [0.0.37]: https://github.com/gitcommit90/1Helm/compare/v0.0.30...v0.0.37 [0.0.36]: https://github.com/gitcommit90/1Helm/compare/v0.0.35...v0.0.36 [0.0.35]: https://github.com/gitcommit90/1Helm/compare/v0.0.34...v0.0.35 diff --git a/README.md b/README.md index 8e4dd1c..b91ceb6 100644 --- a/README.md +++ b/README.md @@ -110,7 +110,10 @@ Skipper ─── crosses the boundary ─────────┘ ## Install -On Apple Silicon: +Whichever platform, it works best on a dedicated machine: your crew works +around the clock, and your everyday computer takes naps. + +### macOS (Apple Silicon) 1. [Download the current signed DMG](https://1helm.com/download/macos). 2. Open it and drag **1Helm** to Applications. @@ -125,21 +128,70 @@ update preserves it — credentials, databases, resident state, files, and workspaces. Profile → Check for updates asks the Mac running 1Helm—not the device displaying the web UI—to download and verify the signed update. -Windows 11 x64 gets a [Setup executable](https://1helm.com/download/windows) -that provisions one installation-scoped WSL 2 runtime and one durable OCI -container per ordinary channel. Linux hosts run the same channel containers -natively under Podman. The verified installer provisions a durable systemd -service with an atomic, -digest-verified, health-checked updater — see the -[Linux install guide](https://1helm.com/manual/install-linux). Whichever platform, -it works best on a dedicated machine: your crew works around the clock, and -your everyday computer takes naps. +### Windows 11 x64 + +1. [Download the current Setup executable](https://1helm.com/download/windows). +2. Windows Setup is **not yet Authenticode signed**, so SmartScreen shows + "Windows protected your PC". Choose **More info** → **Run anyway**. +3. Open 1Helm and complete Captain → Providers → Workspace. +4. At the Workspace step, 1Helm builds its WSL 2 runtime. **You do not need WSL + installed beforehand.** A stock Windows 11 ships with WSL and + VirtualMachinePlatform turned off, and 1Helm enables both itself: + - Approve the one administrator (UAC) prompt. + - A PowerShell window opens and reports progress. **Leave it open** until it + finishes. + - Because those Windows features were just turned on, **Windows has to + restart once.** 1Helm says so in plain language. This is the normal path + on a new PC — it is not an error, and nothing is lost. + - Restart, sign back in as the **same** Windows user, then open 1Helm and + continue setup. It picks up where it left off; already-completed steps are + skipped. + +Setup downloads Microsoft's pinned WSL 2 package and a pinned Ubuntu 24.04 root +filesystem, both SHA-256 verified, and the WSL package is additionally checked +for a valid Microsoft Authenticode signature. The result is one +installation-scoped WSL 2 runtime hosting one durable OCI container per ordinary +channel, with Windows-drive mounts and process interop disabled. App state lives +in `%APPDATA%\1Helm-OCI-v1`; the shared runtime disk lives in +`%LOCALAPPDATA%\1Helm-Runtime`. + +### Linux (Ubuntu/Debian, systemd) + +Linux hosts run the same channel containers natively under Podman. The verified +installer provisions a durable systemd service with an atomic, digest-verified, +health-checked updater: + +```bash +curl -fsSLo /tmp/1helm-install.sh https://1helm.com/install.sh +less /tmp/1helm-install.sh +sudo bash /tmp/1helm-install.sh +``` + +It requires root, systemd, apt, cgroup v2, and x86-64 or arm64 — see the +[Linux install guide](https://1helm.com/manual/install-linux). + +### Removing 1Helm + +Use **Settings → Admin → Prepare to remove 1Helm** first on any platform. It is +Captain-only, requires typed confirmation, and prepares backend-owned resident +machines for safe deletion. Export irreplaceable channel files before you start. + +- **macOS** — drag 1Helm to the Trash. `~/Library/Application Support/1Helm-OCI-v1` + is preserved unless you delete it yourself. +- **Windows** — uninstall from Settings → Apps → Installed apps. The uninstaller + removes 1Helm's own containers, unregisters its WSL runtime, and deletes + `%LOCALAPPDATA%\1Helm-Runtime`. +- **Linux** — `sudo /opt/1helm/uninstall-host.sh` removes the services, helper, + and 1Helm-owned containers while preserving `/var/lib/1helm-oci-v1` for + recovery. + +### Release discipline Mac, Linux, and Windows use one synchronized desktop release version. A release is held in full until the signed/notarized Mac DMG and updater ZIP, verified Linux host archive, and Windows Setup/Squirrel feed have all passed native install and update acceptance from the same source commit. Windows -Authenticode status is disclosed in every release; v0.0.31 is `NotSigned`. +Authenticode status is disclosed in every release; v0.0.38 is `NotSigned`. ### Connect from a phone or tablet @@ -152,10 +204,10 @@ frontend; the password is never retained and the resulting session is stored in the iOS Keychain or encrypted with a key held by Android Keystore. - The native iOS and Android gateway source is included in this repository, - but neither mobile platform has a current v0.0.31 public build. The most + but neither mobile platform has a current v0.0.38 public build. The most recent signed Android APK is the older v0.0.23 gateway, and 1Helm is not currently listed in the public iOS App Store. Use the HTTPS browser interface - for the current v0.0.31 experience. + for the current v0.0.38 experience. - The native clients require HTTPS, do not contain or initialize the 1Helm server or a frozen copy of its product frontend, and do not retain host data or provider credentials beyond the selected server address and secure @@ -277,7 +329,7 @@ and an audit trail. A prompt saying “use this service” is not a connector. service with health-check rollback. - Signed, Apple-notarized, stapled Apple Silicon DMG releases. - Browser access from phones and tablets to an already configured HTTPS 1Helm - host; native mobile gateway source is present but has no v0.0.31 public build. + host; native mobile gateway source is present but has no v0.0.38 public build. ### Platform truth @@ -286,7 +338,7 @@ and an audit trail. A prompt saying “use this service” is not a connector. | **Apple Silicon macOS 26** | Native desktop product and real isolated Linux computer per resident (Apple `container machine`, `home-mount=none`). | | **Linux / CI** | Supported headless systemd host with one durable Podman OCI container per resident, runtime-owned storage, and exact ownership checks; CI may select an explicit test backend. | | **Windows 11 x64** | Native desktop product with one installation-scoped WSL 2 OCI runtime and one durable container per resident; Windows-drive mounts and interop are disabled. | -| **iPhone, iPad, and Android** | Use the current HTTPS browser interface. Native gateway source exists, but v0.0.31 has no public mobile artifact and the iOS app is not publicly listed. | +| **iPhone, iPad, and Android** | Use the current HTTPS browser interface. Native gateway source exists, but v0.0.38 has no public mobile artifact and the iOS app is not publicly listed. | Not yet shipped: current public mobile builds, a native Linux desktop shell, a hosted control plane, rich Photon attachment fidelity, or blind execution of @@ -313,7 +365,7 @@ A fresh data directory opens first-run setup. The source runtime defaults to | `PORT` | `8123` | HTTP/WebSocket control-plane port. | | `CTRL_DATA_DIR` | `./data` | Databases, routing state, uploads, and non-OCI development/Apple workspace mirrors. | | `HELM_CHANNEL_COMPUTER_BACKEND` | `apple` on macOS, `oci` on Linux and Windows | Host isolation backend; `native` and `mock` are explicit development/test overrides. | -| `HELM_CHANNEL_MACHINE_IMAGE` | `local/1helm-channel-machine:0.0.37` | Versioned channel-machine image contract. | +| `HELM_CHANNEL_MACHINE_IMAGE` | `local/1helm-channel-machine:0.0.38` | Versioned channel-machine image contract. | ### Agent-first JSON CLI diff --git a/docs/GOVERNANCE.md b/docs/GOVERNANCE.md index d5802ae..35cd5eb 100644 --- a/docs/GOVERNANCE.md +++ b/docs/GOVERNANCE.md @@ -86,7 +86,10 @@ contract as the slice hardens. `/var/lib/1helm-oci-v1`. - Windows verification must prove the Setup/Squirrel signature status, clean install, old-to-new update, loopback health, WSL lifecycle, and retained - application data on Windows 11 x64. Do not substitute a self-signed + application data on Windows 11 x64. Clean install must be exercised on a host + where WSL and VirtualMachinePlatform start disabled, covering the elevation + prompt, the required Windows restart, and resumed setup after that restart. + Do not substitute a self-signed certificate or block an otherwise accepted release solely because the artifacts are honestly disclosed as unsigned. diff --git a/docs/USER_GUIDE.md b/docs/USER_GUIDE.md index 8d77feb..f5cd638 100644 --- a/docs/USER_GUIDE.md +++ b/docs/USER_GUIDE.md @@ -204,6 +204,9 @@ not consume half of the visible screen. - **Workflows** — recurring resident work, next run, pause/resume, run counts, and failures. - **Connections** — native host-brokered Gmail and Photon configuration. +- **Notifications** — per-account global mute and mobile notification opt-in. +- **Feedback** — send a comment and optional attachments to the 1Helm team, + with privacy-bounded diagnostics included only if you check that option. - **Audit** — retained events and hash-chain verification. - **Domains** — local-first collaboration and optional Cloudflare domain. - **Providers** — accounts, keys, models, routes, quotas, logs, and endpoint. @@ -211,6 +214,9 @@ not consume half of the visible screen. Skipper work; these never replace resident Linux computers. - **Members** — coworkers, access requests, and invitations. +Those sections are the Captain/admin view. A signed-in member who is not an +administrator sees only **Providers** and **Notifications**. + ## Providers, models, and routes Accounts and keys form one fabric. Connect multiple ChatGPT, Claude, @@ -377,14 +383,17 @@ Source/developer deployments report that their host operator owns updates. Every host update preserves: ```text -~/Library/Application Support/1Helm-OCI-v1 +macOS: ~/Library/Application Support/1Helm-OCI-v1 +Linux: /var/lib/1helm-oci-v1 +Windows: %APPDATA%\1Helm-OCI-v1 (plus %LOCALAPPDATA%\1Helm-Runtime) ``` On macOS that directory contains databases, credentials, workspaces, resident -state, and Apple mirrors. Linux preserves the equivalent OCI-generation state -under `/var/lib/1helm-oci-v1`. The retired data roots remain untouched and are -not imported by this generation. Do not delete either current data root during -replacement. +state, and Apple mirrors. Linux and Windows preserve the equivalent +OCI-generation state; on Windows the shared WSL runtime disk lives separately +under `%LOCALAPPDATA%\1Helm-Runtime`. The retired data roots remain untouched +and are not imported by this generation. Do not delete a current data root +during replacement. Before removing 1Helm, use its removal preparation flow. It is Captain-only, requires typed confirmation, reports backend-owned resident machines, and @@ -403,6 +412,47 @@ Recovery principles: ## Troubleshooting +### First run and installation + +**Windows asks me to restart in the middle of setup.** That is the expected +path on a normal Windows 11 PC. WSL and VirtualMachinePlatform ship disabled; +1Helm turns them on for you, and Windows cannot use them until it restarts. +Restart, sign back in as the same Windows user, open 1Helm, and continue — +completed steps are skipped. Nothing is lost and nothing else is required. + +**Windows says "Windows protected your PC" when I run Setup.** Windows Setup is +not yet Authenticode signed, so SmartScreen warns about it. Choose **More info** +→ **Run anyway**. Every release discloses its Authenticode status; v0.0.38 is +`NotSigned`. Only run an installer you downloaded from +[1helm.com](https://1helm.com/download/windows) or the project's GitHub +releases. + +**A PowerShell window opened during Windows setup.** That window is the setup +itself and shows live progress. Leave it open until it finishes; closing it +early aborts the step. 1Helm mirrors the same progress in the app and writes a +log to `%APPDATA%\1Helm-OCI-v1\windows-wsl-setup.log`. + +**Windows setup failed or stalled.** Check the PowerShell window for the error, +then use **Retry shared runtime setup** in onboarding or Settings → Channel +computers. Setup is idempotent — retrying resumes rather than starting over. +The runtime requires Windows 11 **x64**; arm64 Windows is not supported by this +build. + +**macOS blocks the app or reports it is damaged.** The Mac release is Developer +ID signed, notarized, and stapled, so Gatekeeper should accept it after you +drag it to Applications. If it does not, you are almost certainly running a +partially downloaded or re-hosted copy — download the DMG again from +[1helm.com](https://1helm.com/download/macos). Do not strip quarantine +attributes or re-sign an ad-hoc build to work around a failed verification. + +**The Linux installer refuses to run.** It requires root, a running systemd +host, `apt`, cgroup v2, and an x86-64 or arm64 CPU, and it installs Podman +rather than Docker. The error names the missing prerequisite. Follow the +[Linux install guide](https://1helm.com/manual/install-linux); check progress +with `sudo systemctl status 1helm` and `sudo journalctl -u 1helm -f`. + +### In the app + **A button highlights but Continue does nothing.** Ensure every visible question has one selected option or typed answer. If it still fails, capture the thread and app version; selection and the submitted answer should survive live repaints. @@ -445,7 +495,7 @@ fallback. - Operational history is locally tamper-evident. - Mac artifacts are Developer ID signed, notarized, stapled, and Gatekeeper verified. Linux assets are digest-verified, and Windows Authenticode status - is disclosed for every release (`NotSigned` for v0.0.31). + is disclosed for every release (`NotSigned` for v0.0.38). For the detailed boundary, see [SECURITY.md](../SECURITY.md). For product intent, see [VISION.md](VISION.md). diff --git a/docs/VISION.md b/docs/VISION.md index 6111566..66791c5 100644 --- a/docs/VISION.md +++ b/docs/VISION.md @@ -87,7 +87,7 @@ verification. synchronized public desktop-host product. Every named desktop release must publish all three from one version and exact source commit. - 1Helm is self-hosted and open source. Native mobile gateway source is present, - but v0.0.31 has no public Android/iOS build and 1Helm is not listed in the + but v0.0.38 has no public Android/iOS build and 1Helm is not listed in the public iOS App Store. A hosted control plane, blind community-skill execution, and a native Linux desktop shell are not shipped. diff --git a/package-lock.json b/package-lock.json index 3802d1f..a8d9dd8 100644 --- a/package-lock.json +++ b/package-lock.json @@ -1,12 +1,12 @@ { "name": "1helm", - "version": "0.0.37", + "version": "0.0.38", "lockfileVersion": 3, "requires": true, "packages": { "": { "name": "1helm", - "version": "0.0.37", + "version": "0.0.38", "hasInstallScript": true, "license": "AGPL-3.0-only", "dependencies": { diff --git a/package.json b/package.json index e3c456c..317c8ed 100644 --- a/package.json +++ b/package.json @@ -1,7 +1,7 @@ { "name": "1helm", "productName": "1Helm", - "version": "0.0.37", + "version": "0.0.38", "private": true, "type": "module", "license": "AGPL-3.0-only", diff --git a/site/content.mjs b/site/content.mjs index a9a9876..4db1b98 100644 --- a/site/content.mjs +++ b/site/content.mjs @@ -13,7 +13,7 @@ const doc = (path, title, description, content) => ({ title, description, kind: const security = doc("/manual/security-model", "Security model", "How 1Helm isolates residents, brokers credentials, audits actions, validates skills, and defines the human boundary.", `

Autonomy without architecture is just ambient authority. 1Helm makes routine action cheap inside a narrow world and makes boundary crossings explicit, attributable, and recoverable.

Resident isolation

Each ordinary channel receives a separate persistent Linux world: an Apple container machine with no Mac home mount, or a durable OCI container. Linux runs OCI natively. Windows hosts containers inside one managed WSL 2 runtime whose Windows-drive mounts and interop are disabled. Exact labels, storage mounts, and owner markers gate lifecycle operations. Other residents and the host home are not exposed.

Authoritative files

OCI workspace storage belongs to the runtime and is authoritative. Files and Cowork receive narrow direct access to that channel's storage; command and terminal paths do not copy the whole workspace. Apple's backend retains its bounded, symlink-contained mirror.

Skipper boundary

Skipper owns native host operations, fleet lifecycle, credential brokering, and cross-channel work. A resident calls Skipper directly with the invoking thread; a Captain-authored request is required for host-authorized operations. Skipper returns the result to the resident automatically.

Credentials and connections

Provider, Gmail, and Photon credentials stay in host-owned storage. Residents receive task-scoped tools and permission records, not raw access tokens or the native Messages database. Photon accepts only the configured Captain phone and keeps that direct Skipper conversation in the Captain's private #main.

Skill supply chain

The external catalog is discovery metadata, not executable trust. 1Helm shows the open registry's results without applying its own browse-time allowlist. A selected GitHub source is resolved to an immutable commit, bounded to 256 KiB, scanned for instruction override, exfiltration, remote-pipe execution, broad destructive commands, security disabling, private-host access, and prompt extraction, then hashed and wrapped beneath runtime authority.

Audit and limits

New activity, tool starts/results, and skill installation decisions enter an append-only SHA-256 chain. The chain is tamper-evident, not a remote transparency log: an administrator with database access can still delete or replace the entire database. Historical rows predating the chain are not backfilled.

Known dependency debt

The pinned Photon SDK currently carries moderate OpenTelemetry advisories upstream. It runs in a supervised loopback-only child process with telemetry disabled. 1Helm tracks the exact pin and will upgrade when the required Photon API remains compatible; this is not represented as a clean dependency audit.

Report a vulnerability

Use GitHub's private vulnerability reporting for the 1Helm repository. Do not open a public issue containing credentials, tokens, or an unpatched exploit.

`); -const gettingStarted = doc("/manual/getting-started", "Getting started", "Install 1Helm, connect providers, create the workspace, and give the first resident a real outcome.", `

The normal setup is three product decisions. 1Helm handles the infrastructure around them.

1. Install or connect

On Apple Silicon, download the signed, notarized, and stapled DMG. On Windows 11 x64, download the Setup executable; its Authenticode status is disclosed in the release notes and v0.0.31 is NotSigned. Ubuntu/Debian hosts use the digest-verified Linux systemd installer. A new desktop installation can host its own workspace or connect to an existing HTTPS 1Helm host. Native mobile apps connect only to an existing configured host. Starting a new host may request one administrator approval for its isolated Linux runtime.

2. Captain

Create the first account. This is the Captain: owner, final authority, and administrator. Public registration closes after the Captain exists.

3. Providers

Connect one or more subscription accounts or API keys. You can add more later, pool accounts, select exact models, and build fallback or round-robin routes. There is no required single “AI brain.”

4. Workspace

Name the workspace. Terminals default on. 1Helm creates #main with the one Skipper, then you create ordinary channels with plain-language purposes. Every ordinary channel gets a private Linux computer.

5. Give an outcome

Try: “Audit this launch folder, turn the notes into a decision brief, resolve obvious gaps yourself, and give me the finished PDF with evidence.” The resident should inspect, execute, create the artifact, and call Skipper itself if it crosses the channel boundary.

`); +const gettingStarted = doc("/manual/getting-started", "Getting started", "Install 1Helm, connect providers, create the workspace, and give the first resident a real outcome.", `

The normal setup is three product decisions. 1Helm handles the infrastructure around them.

1. Install or connect

On Apple Silicon, download the signed, notarized, and stapled DMG. On Windows 11 x64, download the Setup executable; it is not yet Authenticode signed, so SmartScreen warns once — choose More info → Run anyway. Its status is disclosed in the release notes and v0.0.38 is NotSigned. Ubuntu/Debian hosts use the digest-verified Linux systemd installer. A new desktop installation can host its own workspace or connect to an existing HTTPS 1Helm host. Native mobile apps connect only to an existing configured host. Starting a new host may request one administrator approval for its isolated Linux runtime. On Windows that step also enables WSL 2 for you, which requires one Windows restart partway through setup; reopen 1Helm afterwards and setup continues where it left off. See the Windows guide.

2. Captain

Create the first account. This is the Captain: owner, final authority, and administrator. Public registration closes after the Captain exists.

3. Providers

Connect one or more subscription accounts or API keys. You can add more later, pool accounts, select exact models, and build fallback or round-robin routes. There is no required single “AI brain.”

4. Workspace

Name the workspace. Terminals default on. 1Helm creates #main with the one Skipper, then you create ordinary channels with plain-language purposes. Every ordinary channel gets a private Linux computer.

5. Give an outcome

Try: “Audit this launch folder, turn the notes into a decision brief, resolve obvious gaps yourself, and give me the finished PDF with evidence.” The resident should inspect, execute, create the artifact, and call Skipper itself if it crosses the channel boundary.

`); const architecture = doc("/manual/architecture", "Architecture", "The 1Helm control plane, resident computers, Skipper, model fabric, memory, obligations, connections, and audit chain.", `

1Helm is a compact local control plane around many persistent employee worlds.

Captain
   └─ #main / Skipper ── host · credentials · fleet · cross-channel
        ├─ #product / resident ── private Linux computer ── /workspace
@@ -31,7 +31,7 @@ const connections = doc("/manual/connections", "Connections", "How Gmail, Photon
 
 const installMac = doc("/manual/install-macos", "Install on macOS", "Install the signed, notarized Apple Silicon 1Helm app and initialize per-channel Linux computers.", `
The native consumer product currently targets Apple Silicon Macs.
Requirements
  • Apple Silicon Mac (arm64).
  • macOS 26 for Apple's container runtime.
  • Administrator approval once during verified runtime installation.
Install
  1. Download the current DMG.
  2. Open it and drag 1Helm to Applications.
  3. Open 1Helm. Gatekeeper verifies the Developer ID signature and notarization ticket.
  4. Complete Captain → Providers → Workspace. Approve Apple's signed runtime inline if requested.
Data and upgrades
This generation stores application state under ~/Library/Application Support/1Helm-OCI-v1. Profile → Check for updates asks the Mac hosting 1Helm to download and verify the signed, notarized update. When the host reports it ready, Restart & install quiesces the local service and replaces the app. The browser is never given a DMG as the update action, and Application Support remains in place.
Removal
Use Settings → Admin → Prepare to remove 1Helm before trashing the app. This removes only verified 1Helm-owned channel machines while preserving the application state for a future reinstall.
${button("/download/macos", "Download current DMG", "primary")}${button("https://github.com/gitcommit90/1Helm/releases", "Release history ↗")}
`);
 const installLinux = doc("/manual/install-linux", "Install on Linux", "Install 1Helm as a durable systemd service with one OCI container per resident.", `
Linux is a supported headless host product. It persists the control plane under systemd and gives every ordinary channel its own durable Podman container.
Supported baseline
Ubuntu or Debian with systemd and apt, cgroup v2, an x86-64 or arm64 CPU, 4 GiB RAM minimum (8 GiB recommended), and 20 GiB free disk. Each real workload needs additional storage. Nested deployments must permit Podman and delegated cgroups.
${code("linux-install", "curl -fsSLo /tmp/1helm-install.sh https://1helm.com/install.sh\nless /tmp/1helm-install.sh\nsudo bash /tmp/1helm-install.sh", "bash")}
The installer verifies architecture, installs an exact official Node runtime after checking its published SHA-256 manifest, installs Podman and the fixed root-owned OCI helper, creates a restricted 1helm service account, stores control-plane and runtime state in /var/lib/1helm-oci-v1, and atomically switches /opt/1helm/current.
Host-owned updates
A Captain update action creates one private request file. The host—not the browser—downloads the exact stable Linux release artifact, requires GitHub's SHA-256 asset digest, applies the fixed application and OCI contract, restarts, health-checks, and restores the prior release and runtime files on failure.
Open the UI
By default the service listens on port 8123. Use a firewall and an HTTPS reverse proxy before exposing it to the public internet. First boot opens Captain creation.
${code("linux-status", "sudo systemctl status 1helm --no-pager\ncurl -fsS http://127.0.0.1:8123/api/setup/status\nsudo journalctl -u 1helm -f", "bash")}
Back up and remove
Stop the service, then copy /var/lib/1helm-oci-v1 as one coherent unit. The installed /opt/1helm/uninstall-host.sh deletes only exact ownership-checked channel containers and preserves durable recovery state.
`);
-const installWsl = doc("/manual/install-windows", "Install on Windows + WSL", "Native Windows hosting with one shared WSL 2 runtime and one OCI container per resident.", `
Windows 11 hosts one installation-scoped WSL 2 runtime. Every ordinary channel owns a distinct durable OCI container inside it.
Implemented host contract
  • Native x64 Electron host with Squirrel update packaging.
  • Administrator approval once to enable and verify Microsoft's pinned WSL 2 runtime.
  • One SHA-256-pinned Canonical Ubuntu root filesystem owned by the signed-in Windows account.
  • One separately labeled, mounted, and ownership-checked container per resident.
  • Windows-drive automount and Windows process interop disabled.
  • Exact installation/channel ownership checks for stop, deletion, and app removal.
The resident runs as UID/GID 1000 in /workspace. App state lives under %APPDATA%\\1Helm-OCI-v1, and the shared runtime disk lives under %LOCALAPPDATA%\\1Helm-Runtime.
Install
  1. Download the current Setup executable.
  2. Run the installer on Windows 11 x64.
  3. Open 1Helm and complete Captain → Providers → Workspace. Approve Microsoft’s pinned WSL 2 host setup once if requested.
Updates arrive through the app’s native update feed on the machine hosting 1Helm. The release notes record the installer’s Authenticode status.
${button("/download/windows", "Download for Windows", "primary")}${button("https://github.com/gitcommit90/1Helm/releases", "Release history ↗")}
`);
+const installWsl = doc("/manual/install-windows", "Install on Windows + WSL", "Native Windows hosting with one shared WSL 2 runtime and one OCI container per resident, including the one-time restart during first-run setup.", `
Windows 11 hosts one installation-scoped WSL 2 runtime. Every ordinary channel owns a distinct durable OCI container inside it. You do not need WSL installed first — 1Helm sets it up during first run, which includes one Windows restart.
Requirements
  • Windows 11 on an x64 processor. Arm64 Windows is not supported by this build.
  • Administrator approval once, during first-run setup.
  • One Windows restart during first-run setup on a PC where WSL was not already enabled.
  • Virtualization enabled in firmware, as WSL 2 requires.
  • Internet access to fetch Microsoft's pinned WSL 2 package and the pinned Ubuntu root filesystem.
Install
  1. Download the current Setup executable.
  2. Run it on Windows 11 x64. Windows Setup is not yet Authenticode signed, so SmartScreen shows “Windows protected your PC”. Choose More info → Run anyway. Every release discloses its Authenticode status; v0.0.38 is NotSigned. Only run an installer downloaded from this site or the project's GitHub releases.
  3. Open 1Helm and complete Captain → Providers → Workspace.
First run: the WSL 2 runtime and the restart
A typical new Windows 11 PC has both WSL and VirtualMachinePlatform turned off. 1Helm enables them itself when you reach the Workspace step — you do not install WSL beforehand. What you will see:
  1. One administrator prompt (UAC). Approve it. Only the Windows optional features and Microsoft's signed WSL package cross that boundary; the Linux distribution is imported as your ordinary signed-in account.
  2. A PowerShell window opens and reports progress. Leave it open until it finishes. 1Helm mirrors the same progress in the app.
  3. Windows asks to restart. Enabling those features is not complete until Windows restarts, so 1Helm stops and says so. This is the normal path on a new PC — it is not an error and nothing is lost.
  4. Restart, sign back in as the same Windows user, and open 1Helm. Continue setup and it picks up where it left off; already-completed steps are detected and skipped.
Setup then downloads Microsoft's pinned WSL 2 package and a pinned Ubuntu 24.04 root filesystem, verifies both against recorded SHA-256 digests, additionally requires a valid Microsoft Authenticode signature on the WSL package, imports the runtime, and installs Podman inside it.
Implemented host contract
  • Native x64 Electron host with Squirrel update packaging.
  • Administrator approval once to enable and verify Microsoft's pinned WSL 2 runtime.
  • One SHA-256-pinned Canonical Ubuntu root filesystem owned by the signed-in Windows account.
  • One separately labeled, mounted, and ownership-checked container per resident.
  • Windows-drive automount and Windows process interop disabled.
  • Exact installation/channel ownership checks for stop, deletion, and app removal.
The resident runs as UID/GID 1000 in /workspace. App state lives under %APPDATA%\\1Helm-OCI-v1, and the shared runtime disk lives under %LOCALAPPDATA%\\1Helm-Runtime.
Updates
Updates arrive through the app’s native update feed on the machine hosting 1Helm. The release notes record the installer’s Authenticode status. Application data under %APPDATA%\\1Helm-OCI-v1 and the runtime disk under %LOCALAPPDATA%\\1Helm-Runtime are preserved across updates.
Removal
Use Settings → Admin → Prepare to remove 1Helm first, then uninstall from Windows Settings → Apps → Installed apps. The uninstaller removes only 1Helm's own containers, unregisters its WSL runtime, and deletes %LOCALAPPDATA%\\1Helm-Runtime. Export irreplaceable channel files before you start.
Troubleshooting
Setup asked me to restart. Expected. Restart, sign back in as the same user, reopen 1Helm, and continue.
The PowerShell window closed early. Choose Retry shared runtime setup in onboarding or Settings → Channel computers. Setup is idempotent and resumes rather than starting over.
Setup reported a failure. Read the PowerShell window, then check %APPDATA%\\1Helm-OCI-v1\\windows-wsl-setup.log before retrying. A WSL 2 error mentioning an unavailable service or a missing required feature almost always means the restart has not happened yet.
${button("/download/windows", "Download for Windows", "primary")}${button("https://github.com/gitcommit90/1Helm/releases", "Release history ↗")}
`);
 const selfHosting = doc("/manual/self-hosting", "Self-hosting", "Ports, state, backups, HTTPS, upgrades, health checks, and platform boundaries for self-hosted 1Helm.", `
1Helm is the server. The public 1helm.com website is documentation and release distribution, not a dependency of your installed workspace.
Ports
The source runtime defaults to 8123. Native desktop apps choose an ephemeral loopback port. The standalone product website uses 8130. These are separate processes and data trees.
State
Set CTRL_DATA_DIR to a persistent, restricted directory. Never place it in a public web root. Back it up only while the service is stopped or with a filesystem/database-consistent snapshot.
HTTPS
Use Settings → Domains for a workspace-managed Cloudflare tunnel, or put a conventional HTTPS reverse proxy in front of a headless host. Preserve WebSocket upgrades and do not strip Authorization headers.
Health
${code("health", "curl -fsS http://127.0.0.1:8123/api/setup/status\nsystemctl is-active 1helm\njournalctl -u 1helm --since '15 minutes ago'", "bash")}
Upgrades
Use a unique released version. Stop the service, take a state backup, install the tagged source, run npm ci and npm run build, then restart and verify health. Database migrations are additive, but rollback still requires the pre-upgrade data backup.
Resource guidance
A minimal control plane can run in 4 GiB RAM; 8 GiB is a more practical baseline. Model inference usually remains at connected providers, but browser automation, builds, media processing, and several concurrent residents increase CPU, RAM, and storage demand.
`);
 
 export const pages = {
diff --git a/site/manual.html b/site/manual.html
index 72e2942..83fc990 100644
--- a/site/manual.html
+++ b/site/manual.html
@@ -200,6 +200,16 @@ 
Security

 
   

     
Troubleshooting

+    
Windows asked me to restart during setup

+    
That's expected, and it's the normal path on a new PC. Windows 11 ships with WSL and VirtualMachinePlatform turned off; 1Helm turns them on for you, and Windows can't use them until it restarts. Restart, sign back in as the same Windows user, open 1Helm, and continue — setup picks up where it left off and skips what's already done. Nothing is lost.

+    
Windows says "Windows protected your PC"

+    
Windows Setup isn't Authenticode signed yet, so SmartScreen warns about it. Choose More info → Run anyway. Every release discloses its Authenticode status — v0.0.38 is NotSigned. Only run an installer you got from 1helm.com or the project's GitHub releases.

+    
A PowerShell window opened on Windows

+    
That window is the setup, and it shows live progress. Leave it open until it finishes — closing it early aborts the step. If it did close, choose Retry shared runtime setup in onboarding or Settings → Channel computers; setup resumes rather than starting over. The log is at %APPDATA%\1Helm-OCI-v1\windows-wsl-setup.log.

+    
macOS won't open the app

+    
The Mac release is Developer ID signed, notarized, and stapled, so Gatekeeper should accept it once it's in Applications. If it doesn't, you likely have a partial or re-hosted download — get the DMG again from 1helm.com. Don't strip quarantine attributes or re-sign an ad-hoc build to get around a failed check.

+    
The Linux installer refuses to run

+    
It needs root, a running systemd host, apt, cgroup v2, and an x86-64 or arm64 CPU — and it installs Podman, not Docker. The error names the missing prerequisite. Check progress with sudo systemctl status 1helm and sudo journalctl -u 1helm -f.

     
Skipper reports only #main

     
Ask @skipper what channels exist — inventory comes from the native control plane and includes every channel in your scope, archived ones on request.

     
Terminal and Files disagree

@@ -225,6 +235,16 @@ 
FAQ

       
All three, day one: macOS (signed Apple Silicon app), Windows 11 (x64 installer with one shared WSL 2/Podman runtime), and Linux (native Podman with a systemd host and verified updater). Resident computers work the same way everywhere — one isolated computer per agent.

     
 
+    

+      Do I need to install WSL before installing on Windows?
+      
No. A stock Windows 11 has WSL and VirtualMachinePlatform turned off, and 1Helm enables them itself during setup. Expect three things: one administrator (UAC) prompt, a PowerShell window showing progress that you should leave open, and one Windows restart — Windows can't use the features it just enabled until it restarts. Restart, sign back in as the same user, reopen 1Helm, and setup continues where it left off. Setup executables aren't Authenticode signed yet, so SmartScreen warns once: More info → Run anyway. Full detail is in the Windows guide.

+    

+
+    

+      How do I uninstall 1Helm?
+      
Start with Settings → Admin → Prepare to remove 1Helm, which prepares resident machines for safe deletion — export anything irreplaceable first. Then: on macOS drag the app to the Trash; on Windows uninstall from Settings → Apps, which also removes 1Helm's containers and its WSL runtime; on Linux run sudo /opt/1helm/uninstall-host.sh. macOS and Linux deliberately leave your data root in place for recovery — delete it yourself if you truly want it gone.

+    

+
     

       Which AI models can I use?
       
The ones you already pay for. Connect ChatGPT, Claude, Gemini, and xAI accounts, plus OpenRouter, NVIDIA NIM, Cloudflare, GLM, or any OpenAI-compatible endpoint. Swap models mid-conversation — the agent keeps its identity, memory, and skills.

diff --git a/src/server/channel-computers.ts b/src/server/channel-computers.ts
index 158bf3c..16ffbfc 100644
--- a/src/server/channel-computers.ts
+++ b/src/server/channel-computers.ts
@@ -68,7 +68,7 @@ const APPLE_RUNTIME_VERSION = "1.1.0";
 export const APPLE_RUNTIME_PACKAGE = `container-${APPLE_RUNTIME_VERSION}-installer-signed.pkg`;
 export const APPLE_RUNTIME_URL = `https://github.com/apple/container/releases/download/${APPLE_RUNTIME_VERSION}/${APPLE_RUNTIME_PACKAGE}`;
 export const APPLE_RUNTIME_SHA256 = "0ca1c42a2269c2557efb1d82b1b38ac553e6a3a3da1b1179c439bcee1e7d6714";
-export const DEFAULT_CHANNEL_IMAGE = process.env.HELM_CHANNEL_MACHINE_IMAGE || "local/1helm-channel-machine:0.0.37";
+export const DEFAULT_CHANNEL_IMAGE = process.env.HELM_CHANNEL_MACHINE_IMAGE || "local/1helm-channel-machine:0.0.38";
 const CONTAINER_CANDIDATES = [process.env.HELM_CONTAINER_CLI, "/usr/local/bin/container", "/opt/homebrew/bin/container", "container"].filter(Boolean) as string[];
 const OCI_RUNTIME_VERSION = "1helm-oci-runtime-v1";
 const OCI_HELPER_CANDIDATES = [
diff --git a/src/server/db.ts b/src/server/db.ts
index 067cf48..b9565f2 100644
--- a/src/server/db.ts
+++ b/src/server/db.ts
@@ -939,7 +939,7 @@ export function migrate(): void {
     const platformBackend = process.platform === "darwin" ? "apple" : "oci";
     const configuredBackend = String(process.env.HELM_CHANNEL_COMPUTER_BACKEND || platformBackend);
     const backend = ["apple", "oci", "native", "mock"].includes(configuredBackend) ? configuredBackend : platformBackend;
-    const image = String(process.env.HELM_CHANNEL_MACHINE_IMAGE || "local/1helm-channel-machine:0.0.37");
+    const image = String(process.env.HELM_CHANNEL_MACHINE_IMAGE || "local/1helm-channel-machine:0.0.38");
     for (const channel of q(`SELECT c.id FROM channels c JOIN agent_channels ac ON ac.channel_id=c.id
       WHERE c.kind='channel' AND c.status<>'deleted'`)) {
       const channelId = Number(channel.id);
diff --git a/test/channel-computers.mjs b/test/channel-computers.mjs
index ef8b6a6..7ab91a4 100644
--- a/test/channel-computers.mjs
+++ b/test/channel-computers.mjs
@@ -181,7 +181,7 @@ test("Apple channel-computer contract preserves isolation, files, wakes, archive
 test("runtime digest and packaged image recipe stay pinned", async () => {
   assert.equal(computers.APPLE_RUNTIME_SHA256, "0ca1c42a2269c2557efb1d82b1b38ac553e6a3a3da1b1179c439bcee1e7d6714");
   assert.match(computers.APPLE_RUNTIME_URL, /\/1\.1\.0\/container-1\.1\.0-installer-signed\.pkg$/);
-  assert.equal(computers.DEFAULT_CHANNEL_IMAGE, "local/1helm-channel-machine:0.0.37");
+  assert.equal(computers.DEFAULT_CHANNEL_IMAGE, "local/1helm-channel-machine:0.0.38");
   const packaging = await readFile(join(root, "scripts", "package-mac-dmg.cjs"), "utf8");
   assert.match(packaging, /container\(\?:\$\|\\\/\)/, "release packaging includes container/ image assets");
   const image = await readFile(join(root, "container", "Containerfile"), "utf8");
diff --git a/test/site.mjs b/test/site.mjs
index 27e04c4..718370e 100644
--- a/test/site.mjs
+++ b/test/site.mjs
@@ -61,7 +61,10 @@ test("standalone 1helm.com website serves independent product and documentation
     }
     const gettingStarted = await (await fetch(`${base}/manual/getting-started`)).text();
     assert.match(gettingStarted, /On Windows 11 x64, download the Setup executable/i);
-    assert.match(gettingStarted, /v0\.0\.31 is NotSigned<\/code>/i);
+    // The disclosed Authenticode status is release-coupled: assert against the
+    // shipping version so a patch bump cannot silently leave a stale claim.
+    const shippingVersion = JSON.parse(readFileSync(join(root, "package.json"), "utf8")).version;
+    assert.match(gettingStarted, new RegExp(`v${shippingVersion.replaceAll(".", "\\.")} is NotSigned`, "i"));
     assert.match(gettingStarted, /connect to an existing HTTPS 1Helm host/i);
     assert.doesNotMatch(gettingStarted, /signed Setup executable/i);
     assert.doesNotMatch(gettingStarted, /withheld/i);