Couch installer v0.2.2

Couch installer v0.2.2

This update changes only the installer. It installs the same Couch OS as v0.2.0
and v0.2.1: alpha .215 (v0.1.0-alpha.20260922.215), the very same image file.

Fixed

"Asking the remote over USB failed" on some computers. The installer refused
its own USB port when the computer numbered the remote's USB bus 0, which is
what macOS does for a remote on the first USB controller. It stopped before
asking the remote anything, and nothing was written. Reinstalling, installing
fresh and the Android USB step were all affected, and all are fixed. If this
happened to you there is nothing to put right: the remote was never touched.

Unchanged from v0.2.1

Everything v0.2.1 added is still here: reinstalling without the saved Android
enrollment, the check that the remote has fully started before it is restarted,
clearing a remote that is stuck starting into COUCH RECOVERY, and the list of
saved enrollments with their dates, newest first.

Windows note

Before restarting the remote, the installer checks it over USB. On Windows this
check uses the remote's COM port, and it has not been tested on Windows
hardware yet. If it can't connect, you restart the remote with its Power button,
as before.

Install

Linux x64 and macOS, from an interactive terminal:

curl --fail --location --proto '=https' --tlsv1.2 \
  https://github.com/Couch-OS/couch-installer/releases/download/installer-v0.2.2/install.sh | sh

Windows x64, from PowerShell:

Invoke-RestMethod 'https://github.com/Couch-OS/couch-installer/releases/download/installer-v0.2.2/install.ps1' | Invoke-Expression

Verification

• The install script checks the size and SHA-256 of everything it downloads
  from this release, and starts nothing if one doesn't match.
• SHA256SUMS lists the SHA-256 of every other file in this release.
• release-provenance.json records where everything came from: the programs
  were built by this repository's Build installer binaries workflow,
  run 35891700032,
  from commit 48bf90b070eb4ae5bfab952ff4c480ee5a203c8c, and the source for
  that commit is in couch-installer-source.tar.gz.

Couch installer v0.2.1

Superseded by installer v0.2.2, which fixes the installer refusing a USB bus number of 0 and stopping with "Asking the remote over USB failed". The published install commands point at v0.2.2.

Couch installer v0.2.1

This update changes only the installer. It installs the same Couch OS as
v0.2.0: alpha .215 (v0.1.0-alpha.20260922.215), the very same image file.

New

Reinstall without the saved Android enrollment. "Reinstall existing Couch"
can now carry on without the folder your first install saved. Before it writes
anything, the installer checks that the remote really is running Couch, and it
saves the remote's calibration first. The trade-off: after a reinstall like
this, "Restore stock Android" is not available for that remote.

Remotes stuck starting into COUCH RECOVERY can be reinstalled. If your
remote keeps starting into COUCH RECOVERY, the installer offers to clear that
and restart the remote straight into the installer. Not on Windows yet: there,
use "My remote shows COUCH RECOVERY" first.

Fixed

A retry no longer lands in COUCH RECOVERY. The reinstall now waits until
Couch has fully started before it restarts the remote.

Improved

Saved enrollments are easier to pick. The list shows the date each one was
saved, newest first. The installer remembers a folder only once it has actually
matched your remote. If a folder doesn't match, it tells you what changed and
points you to a folder that does.

Windows note

Before restarting the remote, the installer now checks it over USB. On Windows
this check uses the remote's COM port, and it has not been tested on Windows
hardware yet. If it can't connect, you restart the remote with its Power button,
as before.

Install

Linux x64 and macOS, from an interactive terminal:

curl --fail --location --proto '=https' --tlsv1.2 \
  https://github.com/Couch-OS/couch-installer/releases/download/installer-v0.2.1/install.sh | sh

Windows x64, from PowerShell:

Invoke-RestMethod 'https://github.com/Couch-OS/couch-installer/releases/download/installer-v0.2.1/install.ps1' | Invoke-Expression

Verification

• The install script checks the size and SHA-256 of everything it downloads
  from this release, and starts nothing if one doesn't match.
• SHA256SUMS lists the SHA-256 of every other file in this release.
• release-provenance.json records where everything came from: the programs
  were built by this repository's Build installer binaries workflow,
  run 35757327317,
  from commit db5844d4329c21b3c1e7639e2cf99da9a010658a, and the source for
  that commit is in couch-installer-source.tar.gz.

Couch installer v0.2.0 (acceptance prerelease: fresh installs start on alpha .215)

Superseded by installer v0.2.1, which installs the same OS image and adds reinstalling without the saved Android enrollment. The published install commands point at v0.2.1.

Couch installer v0.2.0 (draft)

Tag: installer-v0.2.0 · Repository: Couch-OS/couch-installer · Prerelease

This is an acceptance prerelease. It exists so the rebuilt image can be
installed on a real remote and checked. The published install commands still
point at installer-v0.1.1, and they stay there until that install has been
done and has passed.

This release changes what gets installed. The installer program itself is the
same one installer-v0.1.1 shipped — on Linux and macOS the binaries are
byte-for-byte identical. What is new is the operating system image it writes.

What is new for a fresh install

Installing with installer-v0.1.1 put a .170-era image on the remote, from
September 16th. This release installs an image built around Couch
v0.1.0-alpha.20260922.215. For somebody setting up a remote, that means:

It starts on a current Couch. Settings → About will say
v0.1.0-alpha.20260922.215 straight after installing, and Check for updates
will correctly say there is nothing newer. With the old image a brand-new
remote arrived several releases behind and had to update itself before it was
current.

It cannot get stuck in COUCH RECOVERY from the old boot script. The
previous image carried a boot script with the fault that strands a remote on
the COUCH RECOVERY screen after a runtime update fails its health check — the
fault installer-v0.1.1 added a rescue action for. This image carries the
fixed script, so a remote installed from it does not have that fault in the
first place. The rescue action is still here and still works for remotes
installed from older images.

Bluetooth is built in. The Bluetooth packages ship inside the image, so the
Bluetooth switch comes up and turns on without the extra "installing packages"
step older remotes show on first use.

Every remote gets its own identity. The image contains no machine ID; each
remote mints its own on first boot. Two remotes installed from this same image
will not share one.

Nothing about how the installer talks to the remote changes: same write path,
same wire protocol, same installation protocol 1, same saved-enrollment and
backup requirements.

Install

Linux x64 and macOS, from an interactive terminal:

curl --fail --location --proto '=https' --tlsv1.2 \
  https://github.com/Couch-OS/couch-installer/releases/download/installer-v0.2.0/install.sh | sh

Windows x64, from PowerShell:

Invoke-RestMethod 'https://github.com/Couch-OS/couch-installer/releases/download/installer-v0.2.0/install.ps1' | Invoke-Expression

These are the commands for this prerelease. The commands published on the
website still fetch installer-v0.1.1 and will keep doing so until this image
is accepted on a remote.

The launcher downloads only the host, terminal and installer.json from this
release, checks each one's byte size and SHA-256 against the values written into
the script, and starts nothing on a mismatch. There is no latest URL and no
fallback to an unverified executable.

What it installs

installer.json is a schema-2 descriptor. It names the installer and the OS
separately:

Installer version	v0.2.0
Installer source commit	e805aebda718012d060c99040e7e1c84f0301d1a
OS version	v0.1.0-alpha.20260922.215
OS source commit	eea577bbfaaa410bed0b1b80216bfe0b32b3dd56
Installation protocol	1
Device model	sanytron-ha100

The OS payload is pinned at its immutable URL in Couch-OS/couch, by byte size
and SHA-256:

https://github.com/Couch-OS/couch/releases/download/v0.1.0-alpha.20260922.215/couch-v0.1.0-alpha.20260922.215-ha100-public-inputs.tar.gz
75312816 bytes
9dc6a34a38dd6f0d7a4510c82f92424b16e543bf6aba2308777de2042c64ee8e

This is a different payload from the one installer-v0.1.0 and
installer-v0.1.1 selected. It is the one thing that changes here.

About the OS image:

• The Couch runtime inside it is the published .215 release — all 27 files
  match the signed release manifest byte for byte, checked against the finished
  image rather than against a build plan.
• The kernel is the signed one from the v0.1.0-alpha.20260916.168 release,
  not rebuilt here: kernel source commit 81d180fc19ec…, zImage
5a19cd5ffb36….
• The package closure is the retained authenticated 141-package solve
  b51d36e9…, resolved offline.
• The OS baseline id is unchanged: ha100-alpine321-ffmpeg612-runtimeboot2.
• The image's installer RAM stage was built from installer commit
  656a20dc… — that is installer-v0.1.1's commit, not this release's. The RAM
  stage inside the image and the desktop binaries in this release are versioned
  separately and always have been.
• The image contains no keys, no saved networks, no vendor files and no
  machine ID.

Assets

Asset	What it is
install.sh, install.ps1	Generated launchers with every asset pin inlined
installer.json	Schema-2 release descriptor
couch-installer-host-…, couch-installer-tui-…	Native host and terminal UI for Linux x64, universal macOS and Windows x64
build-receipts.tar.gz	Per-platform build receipts: exact commit, target, rustc -vV, cargo -vV, toolchain and sysroot hashes, binary hashes
couch-installer-source.tar.gz	Installer corresponding source
release-provenance.json, SHA256SUMS	Provenance record and digests for every asset

Binaries were built by the repository's Build installer binaries workflow,
run 35717638766,
from commit e805aebda718012d060c99040e7e1c84f0301d1a with
rustc 1.98.1 (48a229cea 2026-09-01). The macOS binaries are lipo-combined
x86_64 + arm64 and ad-hoc signed. No binary was built on a developer machine.

The only source change between installer-v0.1.1 and this release is the
VERSION file, and that file is not compiled in — so the Linux and macOS host
and terminal binaries here are byte-for-byte identical to
installer-v0.1.1's. The two Windows binaries differ although their source did
not; that is MSVC build nondeterminism, the same difference seen between
installer-v0.1.0 and installer-v0.1.1.

Corresponding source

couch-installer-source.tar.gz covers this exact installer commit, all four
locked Cargo workspaces with their vendored dependency sources, dependency
notices, and one audited Rust standard-library source component. Its scope is
installer: os_source_covered is false.

The OS image's own corresponding source is published on the Couch OS release
v0.1.0-alpha.20260922.215, as five archives:
-corresponding-source.tar.gz (the Couch project at eea577bb… plus all nine
locked Cargo workspaces), -kernel-source.tar.gz, -busybox-source.tar.gz,
-bluez-source.tar.gz, and -exact-source-archive.tar.gz (the git archive
the build attestation names). The kernel and BusyBox archives are the same
bytes as the ones published on .168, because the kernel and the BusyBox
binary in this image are the same binaries; each archive's receipt names the
exact binary hash that is in this image. The BlueZ archive was collected from
this image's own build directory and is identical to .168's in all 23 source
members — it differs only in a one-sentence documentation edit in its
README.md and in the receipt line recording that file's hash.

Verified

• couch-installer-host verify-public against this release's descriptor and the
  rebuilt payload, run with this release's macOS host, accepted the archive and
  extracted all six public OS inputs with no device access. The extracted
  manifest matches the OS identity and every file pin in the build report.
• The host accepts installation protocol 1 and refuses 0, 2 and 3.
• This release's macOS host, with no remote attached, reaches the recovery
  action's "No remote in Couch recovery is connected" screen through the real
  macOS device search, asks for no release configuration, writes nothing and
  exits 0.
• Every SHA-256 in installer.json, in both launchers and in SHA256SUMS was
  cross-checked against the actual asset bytes, and each launcher's download
  URLs point only at this release's tag.
• Each platform's build receipt names commit
  e805aebda718012d060c99040e7e1c84f0301d1a and matches the published binary's
  size and SHA-256.

Not established by this release

• Physical USB installation acceptance on an HA100. This is the whole point
  of the prerelease and the gate before the public commands move. It needs a
  full USB reinstall with the saved Android enrollment, not a recovery boot.
• Release signatures.
• That every downloadable native binary used the audited Rust source component.
• Frozen Windows launcher acceptance, which installer-v0.1.0 ran against its
  real binaries in a Windows ConPTY and this candidate has not repeated.
• The image's display font assets were built using slightly older Pillow and
  fontTools than the build recipe pins. Regenerating them with the pinned
  Pillow 11.3.0 / fontTools 4.60.1 / brotli 1.1.0 is still open.
• The retained 141-package closure archive is not yet published as an immutable
  asset; it exists only on the build host and one Mac copy.
• The Alpine aports and distfiles corresponding-source component was not
  collected — no aports or distfiles cache exists on the build host. The OS
  source set covers the Couch project, all Cargo dependencies, the kernel,
  BusyBox and BlueZ, but not the Alpine package recipes.

Couch installer v0.1.1

Couch installer v0.1.1 (draft)

Tag: installer-v0.1.1 · Repository: Couch-OS/couch-installer · Prerelease

An installer-only release. It carries exactly the same Couch OS payload as
installer-v0.1.0 — same archive, same URL, same bytes — and adds one thing: a
way to rescue a remote that keeps starting into COUCH RECOVERY, without anyone
having to type commands into a serial console.

Nothing about installing Couch changes here. The on-device write path, the wire
protocol, the release descriptor's OS selection and every firmware pin are the
same as in installer-v0.1.0.

What is new

My remote shows COUCH RECOVERY is a new entry on the installer's first
menu, next to the install and restore choices.

When a runtime update fails its health check, the remote correctly rolls back —
but on older images the reboot lands in recovery with a flag still set that
sends it straight back to the COUCH RECOVERY screen on every following start.
The remote is not broken and nothing on it is lost; one flag is stuck on. Until
now the only way out was two commands typed into a hidden serial console.

What you see, in order:

1. Connect the remote by USB while it shows COUCH RECOVERY. Nothing is
   opened or written yet.
2. Found your remote — it tells you where the remote is and which Couch
   version the next start will bring up, then asks, in as many words, whether
   to leave recovery. If you stop here, the remote is left exactly as it was.
3. Done — the remote restarts by itself, and when Couch is back you open
   Settings → Updates to finish updating it.

What it does when you say yes: it clears the one flag that keeps sending the
remote to recovery, reads it back to confirm it is really clear, and only then
restarts the remote. If the read-back is not clean it stops and tells you, and
it never tries a second time.

What it never touches: your settings, your paired devices, your rooms and
activities, the Couch version installed on the remote, its Android side, its
saved originals, and every partition other than the 512 bytes holding that one
flag. It installs nothing, downloads nothing, needs no release configuration
and asks for no administrator rights. Before it writes anything it checks, read
only, that it is really talking to a Couch recovery shell on an HA100 — if any
of those checks disagree it refuses and writes nothing at all.

If more than one remote in recovery is plugged in, it refuses and asks you to
unplug the others. It never picks a remote for you.

If your remote shows COUCH RECOVERY

1. Get the remote's screen showing COUCH RECOVERY. If the screen is off,
   hold the side Power button until it comes on.
2. Plug the remote into your computer with a USB cable. It has to be a data
   cable, not a charge-only one.
3. Run the install command for your computer from the Install section
   below. It starts the Couch installer; nothing is installed by opening it.
4. On the first menu choose My remote shows COUCH RECOVERY, then
   Find my remote.
5. When it says Found your remote, choose Leave recovery and restart the
   remote.
6. Watch the remote restart on its own. When Couch is back, open
   Settings → Updates and let it finish updating.

If it says no remote was found, check that the screen still shows COUCH
RECOVERY, that the cable is plugged into both ends, and that it is a data
cable — then choose Look again.

Install

Linux x64 and macOS, from an interactive terminal:

curl --fail --location --proto '=https' --tlsv1.2 \
  https://github.com/Couch-OS/couch-installer/releases/download/installer-v0.1.1/install.sh | sh

Windows x64, from PowerShell:

Invoke-RestMethod 'https://github.com/Couch-OS/couch-installer/releases/download/installer-v0.1.1/install.ps1' | Invoke-Expression

The launcher downloads only the host, terminal and installer.json from this
release, checks each one's byte size and SHA-256 against the values written into
the script, and starts nothing on a mismatch. There is no latest URL and no
fallback to an unverified executable.

What it installs

installer.json is a schema-2 descriptor. It names the installer and the OS
separately:

Installer version	v0.1.1
Installer source commit	656a20dc5e92feee1ee005362b662bdd54e69788
OS version	v0.1.0-alpha.20260916.170
OS source commit	de2c0ecda41102816c9121c421dfdede5b704dbc
Installation protocol	1
Device model	sanytron-ha100

The OS payload is pinned at its immutable URL in Couch-OS/couch, by byte size
and SHA-256:

https://github.com/Couch-OS/couch/releases/download/v0.1.0-alpha.20260916.170/couch-v0.1.0-alpha.20260916.170-ha100-public-inputs.tar.gz
69729275 bytes
fa5b88eaaf347dbcab8d2dc69906eb8d4d05e72ed9274f10aaaead4787c88f0a

This is the same OS payload installer-v0.1.0 selected, down to the byte.
The descriptor's os and payload blocks are unchanged from that release; only
the installer's own version, source commit and release URL differ. It is served
byte-for-byte identically by the retained dangerouslaser/couch archive, and
the host accepts either owner, so existing published descriptors keep working.
Installing from this release installs exactly what the previous one installed.

Assets

Asset	What it is
install.sh, install.ps1	Generated launchers with every asset pin inlined
installer.json	Schema-2 release descriptor
couch-installer-host-…, couch-installer-tui-…	Native host and terminal UI for Linux x64, universal macOS and Windows x64
build-receipts.tar.gz	Per-platform build receipts: exact commit, target, rustc -vV, cargo -vV, toolchain and sysroot hashes, binary hashes
couch-installer-source.tar.gz	Installer corresponding source
release-provenance.json, SHA256SUMS	Provenance record and digests for every asset

Binaries were built by the repository's Build installer binaries workflow,
run 35707051461,
from commit 656a20dc5e92feee1ee005362b662bdd54e69788 with
rustc 1.98.1 (48a229cea 2026-09-01) — the same compiler release and commit
that built installer-v0.1.0. The macOS binaries are lipo-combined
x86_64 + arm64 and ad-hoc signed. No binary was built on a developer machine.

The recovery action lives in the native host, so the Linux and macOS terminal
binaries are byte-for-byte identical to installer-v0.1.0's. Only the host
binaries changed for those platforms.

Corresponding source

couch-installer-source.tar.gz covers this exact commit, all four locked Cargo
workspaces with their vendored dependency sources, dependency notices, and one
audited Rust standard-library source component. Its scope is installer:
os_source_covered is false. The selected OS release keeps its own
corresponding-source archive, which an installer-scoped archive cannot replace.

The Rust standard-library source component is the same audited component
installer-v0.1.0 shipped, imported unchanged and rehashed against its
couch-external-source receipt; the build receipts record the same compiler
release and commit for every platform in this release.

Verified

• couch-installer-host verify-public against this release's descriptor and the
  pinned payload, run with this release's macOS host, accepted the archive and
  extracted all six public OS inputs with no device access. The archive's
  manifest matches the OS identity and every file pin.
• The pinned payload was downloaded again from its immutable URL: 69729275
  bytes, SHA-256 fa5b88ea…c88f0a, exactly the pin.
• The host accepts installation protocol 1 and refuses 0, 2 and 3.
• This release's macOS host, with no remote attached, reaches the new action's
  "No remote in Couch recovery is connected" screen through the real macOS
  device search, asks for no release configuration, writes nothing and exits 0.
• Every SHA-256 in installer.json, in both launchers and in SHA256SUMS was
  cross-checked against the actual asset bytes, and each launcher's download
  URLs point only at this release's tag.
• Each platform's build receipt names commit
  656a20dc5e92feee1ee005362b662bdd54e69788 and matches the published binary's
  size and SHA-256.

Not established by this release

• Physical acceptance on an HA100: installation, restore, and — for the new
  action — actually clearing the flag on a remote that is stuck and watching it
  come back. That remains an unverified physical step.
• Release signatures.
• That every downloadable native binary used the audited Rust source component;
  the build receipts record each platform's compiler identity for that
  comparison.
• Frozen Windows launcher acceptance, which installer-v0.1.0 ran against its
  real binaries in a Windows ConPTY and this candidate has not repeated. This
  release's install.ps1 differs from that one only in its version string, its
  release URL and its three pinned sizes and hashes.

Couch installer v0.1.0

Couch installer v0.1.0 (draft)

Tag: installer-v0.1.0 · Repository: Couch-OS/couch-installer · Prerelease

The first installer release published from the installer's own repository. The
installer now versions and ships independently of the Couch OS: installer-v…
tags belong to the installer, v… tags remain Couch OS runtime releases. An
installer-only fix can keep the same OS payload, and an OS release no longer
requires a new installer build.

Nothing about the on-device write path or the wire protocol changes here. This
release carries the same installation transaction as the installer published
with Couch v0.1.0-alpha.20260916.170, built from the installer repository's
own source.

Install

Linux x64 and macOS, from an interactive terminal:

curl --fail --location --proto '=https' --tlsv1.2 \
  https://github.com/Couch-OS/couch-installer/releases/download/installer-v0.1.0/install.sh | sh

Windows x64, from PowerShell:

Invoke-RestMethod 'https://github.com/Couch-OS/couch-installer/releases/download/installer-v0.1.0/install.ps1' | Invoke-Expression

The launcher downloads only the host, terminal and installer.json from this
release, checks each one's byte size and SHA-256 against the values written into
the script, and starts nothing on a mismatch. There is no latest URL and no
fallback to an unverified executable.

What it installs

installer.json is a schema-2 descriptor. It names the installer and the OS
separately:

Installer version	v0.1.0
Installer source commit	7f76f500d020ea2142adb4cf469ad2d15c86f9f3
OS version	v0.1.0-alpha.20260916.170
OS source commit	de2c0ecda41102816c9121c421dfdede5b704dbc
Installation protocol	1
Device model	sanytron-ha100

The OS payload is pinned at its immutable URL in Couch-OS/couch, by byte size
and SHA-256:

https://github.com/Couch-OS/couch/releases/download/v0.1.0-alpha.20260916.170/couch-v0.1.0-alpha.20260916.170-ha100-public-inputs.tar.gz
69729275 bytes
fa5b88eaaf347dbcab8d2dc69906eb8d4d05e72ed9274f10aaaead4787c88f0a

This is the same archive the previous installer used. It is served
byte-for-byte identically by the retained dangerouslaser/couch archive, and
the host accepts either owner, so existing published descriptors keep working.

Assets

Asset	What it is
install.sh, install.ps1	Generated launchers with every asset pin inlined
installer.json	Schema-2 release descriptor
couch-installer-host-…, couch-installer-tui-…	Native host and terminal UI for Linux x64, universal macOS and Windows x64
build-receipts.tar.gz	Per-platform build receipts: exact commit, target, rustc -vV, cargo -vV, toolchain and sysroot hashes, binary hashes
couch-installer-source.tar.gz	Installer corresponding source
release-provenance.json, SHA256SUMS	Provenance record and digests for every asset

Binaries were built by the repository's Build installer binaries workflow,
run 35260505555,
from commit 7f76f500d020ea2142adb4cf469ad2d15c86f9f3 with
rustc 1.98.1 (48a229cea 2026-09-01). The macOS binaries are lipo-combined
x86_64 + arm64 and ad-hoc signed. No binary was built on a developer machine.

Corresponding source

couch-installer-source.tar.gz covers this exact commit, all four locked Cargo
workspaces with their vendored dependency sources, dependency notices, and one
audited Rust standard-library source component. Its scope is installer:
os_source_covered is false. The selected OS release keeps its own
corresponding-source archive, which an installer-scoped archive cannot replace.

Verified

• couch-installer-host verify-public against this descriptor and the pinned
  payload accepted the archive and extracted all six public OS inputs with no
  device access, both with this release's macOS host and with a host freshly
  built from the release commit. The archive's manifest matches the OS identity
  and every file pin.
• The host accepts installation protocol 1 and refuses 0 and 2.
• Frozen Windows launcher acceptance ran the unmodified generated install.ps1
  and these real binaries in a Windows ConPTY, requested exactly the three
  release assets, selected Cancel, exited 0, and created no installer session.

Not established by this release

• Physical installation, restore or recovery acceptance on an HA100.
• Release signatures.
• That every downloadable native binary used the audited Rust source component;
  the build receipts record each platform's compiler identity for that
  comparison.