Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down
84 changes: 68 additions & 16 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand All @@ -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.
Comment on lines +137 to +140

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win

Correct the Windows feature sentence.

Line 139 says 1Helm enables both itself. State the object explicitly.

Proposed fix
-   VirtualMachinePlatform turned off, and 1Helm enables both itself:
+   VirtualMachinePlatform turned off, and 1Helm enables both features itself:
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
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.
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 features itself:
- Approve the one administrator (UAC) prompt.
🧰 Tools
🪛 LanguageTool

[grammar] ~139-~139: Ensure spelling is correct
Context: ... VirtualMachinePlatform turned off, and 1Helm enables both itself: - Approve the o...

(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)

🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@README.md` around lines 137 - 140, Update the Windows setup sentence in the
Workspace step to explicitly state that 1Helm enables WSL and
VirtualMachinePlatform itself, replacing the ambiguous “both” wording while
preserving the surrounding instructions.

Source: Linters/SAST tools

- 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

Expand All @@ -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
Expand Down Expand Up @@ -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

Expand All @@ -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
Expand All @@ -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

Expand Down
5 changes: 4 additions & 1 deletion docs/GOVERNANCE.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down
62 changes: 56 additions & 6 deletions docs/USER_GUIDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -204,13 +204,19 @@ 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.
- **Skipper computers** — optional Captain-owned computers for authorized
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,
Expand Down Expand Up @@ -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
Expand All @@ -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.
Comment on lines +435 to +439

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
set -eu

printf '%s\n' '--- USER_GUIDE.md around the reported section ---'
sed -n '390,455p' docs/USER_GUIDE.md

printf '%s\n' '--- Settings label references ---'
rg -n -i -C 3 'Skipper computers|Channel computers|Retry shared runtime setup|shared runtime setup|Settings.*computers|computers.*Settings' . \
  -g '!node_modules' -g '!dist' -g '!build'

Repository: gitcommit90/1Helm

Length of output: 50373


🏁 Script executed:

#!/bin/bash
set -eu

printf '%s\n' '--- Settings navigation and section rendering ---'
sed -n '70,100p' src/client/settings.ts
sed -n '620,755p' src/client/settings.ts

printf '%s\n' '--- Retry-related settings labels and handlers ---'
rg -n -C 5 'Retry shared runtime setup|retry.*runtime|runtime.*retry|Channel computers' src/client/settings.ts src/client/onboarding.ts test

printf '%s\n' '--- Documentation index and computer section ---'
sed -n '195,220p' docs/USER_GUIDE.md
sed -n '330,348p' docs/USER_GUIDE.md

printf '%s\n' '--- Read-only label consistency check ---'
python3 - <<'PY'
from pathlib import Path
p = Path("src/client/settings.ts").read_text()
for label in ("Skipper computers", "Channel computers", "Retry shared runtime setup"):
    print(f"{label!r}: {p.count(label)} occurrence(s)")
print("tab declaration:", '[["computers", "Skipper computers"]]' in p)
print("channel heading:", 'font-semibold text-fg" }, "Channel computers"' in p)
print("settings retry label:", "Retry shared runtime setup" in p)
PY

Repository: gitcommit90/1Helm

Length of output: 22900


Use the actual Settings path and action label.

The sidebar label is Skipper computers. Inside it, the runtime panel is Channel computers, and the Windows button is Set up shared runtime, not Retry shared runtime setup. Update this step to match the UI.

🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/USER_GUIDE.md` around lines 435 - 439, Update the Windows setup guidance
in USER_GUIDE.md to direct users to Settings → Skipper computers → Channel
computers and use the exact action label “Set up shared runtime”; remove the
incorrect “Retry shared runtime setup” wording while preserving the surrounding
troubleshooting and platform requirements.


**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.
Comment on lines +441 to +446

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win

Do not attribute every Gatekeeper failure to a bad download.

Gatekeeper can reject a complete official artifact for signing, notarization, policy, or system-state reasons. Replace “almost certainly” with neutral diagnostic guidance. Keep re-downloading as one troubleshooting step, and provide a support or verification path if the failure persists.

Proposed wording
-If it does not, you are almost certainly running a
-partially downloaded or re-hosted copy — download the DMG again from
+If it does not, verify the download source and download the DMG again from
 [1helm.com](https://1helm.com/download/macos). If the failure persists,
+contact support instead of bypassing verification.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/USER_GUIDE.md` around lines 441 - 446, Revise the macOS Gatekeeper
guidance in the release troubleshooting section to remove the “almost certainly”
attribution to partial downloads or re-hosted copies. Use neutral diagnostic
wording that acknowledges signing, notarization, policy, and system-state
causes; retain re-downloading the DMG as one troubleshooting step, and add a
support or verification path for persistent failures. Keep the warning against
stripping quarantine attributes or using ad-hoc re-signing.


**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.
Expand Down Expand Up @@ -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).
2 changes: 1 addition & 1 deletion docs/VISION.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down
4 changes: 2 additions & 2 deletions package-lock.json

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

2 changes: 1 addition & 1 deletion package.json
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
{
"name": "1helm",
"productName": "1Helm",
"version": "0.0.37",
"version": "0.0.38",

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🗄️ Data Integrity & Integration | 🟠 Major | 🏗️ Heavy lift

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
set -euo pipefail

echo "package.json version:"
python3 -c 'import json; print(json.load(open("package.json", encoding="utf-8"))["version"])'

echo "Website fallback release and digest references:"
rg -n -C 8 'fallback|release|artifact|digest|sha256|0\.0\.' site/server.mjs

Repository: gitcommit90/1Helm

Length of output: 8059


🏁 Script executed:

#!/bin/bash
set -euo pipefail

echo "Relevant package metadata and scripts:"
sed -n '1,140p' package.json

echo "Release fallback references:"
rg -n -C 4 'RELEASE_FALLBACK|SITE_RELEASE_FETCH_DISABLED|SITE_RELEASE_METADATA_JSON|latestLinuxRelease|0\.0\.30|0\.0\.38' site test* .github 2>/dev/null || true

echo "Changed-file summary:"
git diff --stat

Repository: gitcommit90/1Helm

Length of output: 37716


🏁 Script executed:

#!/bin/bash
set -euo pipefail

echo "Website release routes and fallback test:"
sed -n '80,125p' test/site.mjs
sed -n '330,430p' site/server.mjs

echo "All release metadata consumers:"
rg -n -C 3 'latestAssetUrl|latestReleaseAssets|RELEASE_PAGE|/download/|sha256|digest' site/server.mjs test/site.mjs site/public/install.sh

echo "Standalone fallback invariant check:"
python3 - <<'PY'
import json, re
from pathlib import Path

package_version = json.loads(Path("package.json").read_text())["version"]
source = Path("site/server.mjs").read_text()
tag = re.search(r'tag_name:\s*"v([^"]+)"', source).group(1)
names = re.findall(r'\["([^"]+)",\s*"([0-9a-f]{64})"\]', source)
urls = re.findall(r'releases/download/v([^/]+)/\$\{name\}', source)

print({"package_version": package_version, "fallback_version": tag})
print("fallback_asset_versions:", sorted(set(re.findall(r"1Helm-([0-9]+\.[0-9]+\.[0-9]+)-", "\n".join(n for n, _ in names)))))
print("fallback_url_versions:", sorted(set(urls)))
print("version_matches:", package_version == tag)
PY

Repository: gitcommit90/1Helm

Length of output: 24005


Update the website fallback metadata before publishing 0.0.38.

When GitHub release fetching fails, site/server.mjs serves v0.0.30 assets and digests. Update the fallback and its test expectation, then add a check that the fallback version matches package.json.

🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@package.json` at line 4, Update the website release fallback metadata used by
the GitHub-fetch failure path in site/server.mjs from v0.0.30 to v0.0.38,
including its asset and digest values, and update the corresponding test
expectation. Add validation that the fallback version matches the package.json
version before publishing.

"private": true,
"type": "module",
"license": "AGPL-3.0-only",
Expand Down
Loading
Loading