The ultimate harness for coding agents and beyond. All your agents. All your machines. One command center. Start with code, then follow your curiosity and build across disciplines: CAD, circuits, robots, games and music.
Releasing the desktop app
Running apps self-update from a public GCS bucket (lib/update/desktop_updater.dart). Releasing is
pushing a tag: ../.github/workflows/release-desktop.yml builds both macOS builds (Intel on Skia,
Apple Silicon on Impeller — see "Two macOS builds" below) and both Linux architectures, publishes them
to that bucket, and cuts the GitHub Release. The tag IS the version — CI never bumps.
Tags are vX.Y.Z_desktop, not plain vX.Y.Z: the CLI (cli/, tags vX.Y.Z_cli) and the backend
(backend/, tags vX.Y.Z_backend) release from this same repo, so the suffix is what tells each
tag-push trigger which workflow to run. It is stripped before anything treats it as a version — the
manifest, --build-name, the release title and the updater's comparison all see a bare X.Y.Z.
# from the repo root (or `cd desktop && make release ...`, which is the same script)
make release-desktop # bump the patch, tag, push — CI does the rest
make release-desktop ARGS="--dry-run" # print the version it would cut and the notes, do nothing
make release-desktop ARGS="--minor" # bump the MINOR version, per the usual semver convention
make release-desktop ARGS="1.3.0" # release an explicit version
make release-desktop ARGS="--notes-file notes.md" # hand-written release notes
make release-desktop ARGS="--prepare" # package the final pushed PR head during tests/review; publish nothing
make release-desktop ARGS="--wait" # release, then follow this exact tag through public verification
Nothing is built locally and no GCS credentials are needed. The script uses Git and a public
HTTPS read of the manifest; --prepare and --wait also need the authenticated gh CLI.
For an authorized release, run --prepare once the final implementation is pushed to its PR
branch, while the required tests and review run. It selects the next version by the same rules
as a release, builds/signs/notarizes all platforms in CI, and verifies all nine downloads at an
isolated candidate path. It creates neither a release tag nor a product manifest/Release page.
After checks pass, merge and release that same version normally. CI reuses the candidate only
when the Desktop build inputs and version match; unrelated component merges and a clean
squash are supported. Changed build inputs or version require a new build.
Candidate packaging does not replace application
tests or authorize publication. See the validation guide
for identity checks, bounded waiting, expiration and disposable promotion validation.
Why the version comes from two places. scripts/release-desktop.sh takes the highest of the last
git tag and the highest version in the live metadata.json, across every desktop-* key. Publishing
used to be a local command that bumped from the manifest and tagged nothing, so the two drifted: this
repo once had a single tag v1.0.52 while the manifest was already serving 1.0.61. Bumping from
tags alone there produces a version LOWER than what users run — every app refuses it (semverGt)
while the release still reports success. That local path is gone; the tag is now the only way in.
A release contains the one before it. The script refuses a checkout that lacks the last release's
commit (the highest v*_desktop tag, and the tag of the version the manifest serves): it is still on
origin/main, so nothing else stopped it, and it would ship older code under a newer version to every
app. v1.2.36_desktop was cut that way on October 1, 2026, twenty commits behind
v1.2.35_desktop. Update the checkout (git fetch origin && git checkout --detach origin/main). A
rollback, which means to do exactly this, is make release-desktop ARGS="--allow-older". --prepare
is not checked: it publishes nothing. make release-web checks the same against the last v*_web tag.
pubspec.yaml's version: field is never touched; it's a dev-only placeholder.
Managed Node runtime
Node lives under ~/.harness/runtime and does not alter the user's system Node, Homebrew, nvm, or
shell PATH. That is the point of it — the CLI launcher is written against that exact binary, so a
Finder launch (where PATH is launchd's bare /usr/bin:/bin:/usr/sbin:/sbin) and a Terminal launch
behave identically.
The desktop app no longer installs it; the harness installer does — for the app's first run and
for a terminal install alike. This repo still owns the publishing, so the command below is unchanged
and still has to be run before a release needs a newer Node. Publish macOS and Linux
archives for both ARM64 and x64 (including machines where uname -m reports amd64) before
releasing a desktop build that requires a new Node version:
make upload-node-runtime ARGS="22.23.2"
The publisher downloads the official Node archives and SHASUMS256.txt, verifies each archive before
uploading, then atomically merges harness/runtime/metadata.json. The app verifies the manifest's
size and SHA-256 again before extracting an archive. A runtime manifest applies to fresh installs;
roll out a changed runtime to existing users with a newer desktop build. Never replace an existing
versioned archive in place.
Until that managed manifest covers a platform, the desktop build falls back to its checksum-pinned official Node 22 archive for it. The fallback keeps first-run setup functional but is intentionally not a replacement for publishing the managed runtime channel before release.
tmux is a separate step and unrelated to Node: on macOS it comes from Homebrew when Homebrew is already there, else from the managed runtime below; on Linux from apt — and only when tmux is missing; a computer that already runs it is never asked about any of them.
Managed tmux runtime (macOS)
The same idea as Node, for the one host dependency that still came from a package manager: a
checksum-verified tmux archive under harness/runtime/tmux/, built once per tmux version so a Mac
with no tmux and no Homebrew can obtain it with no compiler, no package manager and no password.
cli/scripts/build-managed-tmux.sh builds tmux against static libevent and ncurses (terminfo is
read from macOS's own /usr/share/terminfo); the result links only libSystem and is ad-hoc
signed. Its three macOS traps — the toolchain clang needing SDKROOT, tmux's configure silently
linking the system ncurses 5.4 unless LIBTINFO_LIBS is explicit, and libevent's autoconf detecting
a pipe2 macOS does not have — are handled in the script and gated by otool -L and a real
new-session smoke test (under Rosetta for the x64 build). pkg-config is pointed at our own
.pc files only (PKG_CONFIG_LIBDIR) and jemalloc is disabled: with Homebrew on the build host —
every CI runner — tmux 3.7's configure otherwise picks up a Homebrew jemalloc. Keep the pinned tmux
level with what Homebrew ships (3.7c today): a tmux client and server must agree on their protocol,
and a managed client older than a Homebrew server on the same socket only says "server exited
unexpectedly".
Publish from CI, never by hand unless rebuilding the same version:
gh workflow run release-tmux-runtime.yml -f tmux_version=3.7c # build both, publish
gh workflow run release-tmux-runtime.yml -f tmux_version=3.7c -f publish=false # build only, inspect
make upload-tmux-runtime ARGS="3.7c /path/to/archives" # the publisher CI calls
The manifest is harness/runtime/tmux/metadata.json — its own file, because install.sh slices a
manifest by the first "<platform>" key and Node's already has one — with the same
{version,url,sha256,size,archiveRoot} entries. install.sh reads it on a Mac that has no tmux and
no Homebrew (Homebrew's tmux is used when Homebrew is already there): download into
~/.harness/runtime/tmux-<ver>-<platform>, verify, record the binary in ~/.harness/runtime/current-tmux
(which the daemon's ensureTmuxOnPath falls back to when neither its PATH nor the user's login shell
resolves a tmux — the terminal's tmux always wins, so daemon and terminal share one server) and link it as
~/.local/bin/tmux. The desktop runs that same install.sh --host in-app, so on macOS first-run setup
never opens a Terminal window. Publish a new runtime before the install.sh that pins a newer
tmux level, and keep it level with what Homebrew ships.
Managed grid runtime
The grid CLI, as a runtime beside Node and tmux: the daemon shells out to grid for every Local
model (gridExec.ts), and the Local model manager has an agent run it by name in its pane, so a
machine that installs the harness must have one without a second installer. Same shape as the other
two — harness/runtime/grid/metadata.json, its own manifest for the reason tmux has one, entries
{version,url,sha256,size,archiveRoot}, archives grid-<ver>-<platform>/bin/grid — with one
difference: the manifest's version is a pin. install.sh lays that grid down (step 3b, optional:
a failed download does not fail the install), and the daemon moves every installed machine to it
on its next start (ensureManagedGrid), keeping one version back for the panes still running the
old one. Laid down read-only, bin/ included, so grid update — an os.replace into that
directory — fails loudly instead of overwriting the pin; the daemon also sets
GRID_NO_UPDATE_CHECK=1 on every spawn and pane. Never linked into ~/.local/bin: that path is
grid's own installer's (uv's, on a Mac), and the daemon puts the managed grid on an agent pane's
PATH itself.
Linux archives wrap autonomous-grid's own release binaries (grid-linux-{x86_64,arm64}, verified
against the release's SHA256SUMS at build time, then re-hosted under our manifest so nothing is
fetched from GitHub at install time). macOS archives are built by cli/scripts/build-managed-grid.sh
from a checkout of the release tag with grid's own packaging/build_binary.sh — Nuitka onefile,
ad-hoc signed, not notarized: the SIGKILL grid's README attributes to ad-hoc signing is Gatekeeper on a
quarantined download, which a curl-fetched runtime never is (the managed tmux runs the same way).
Nuitka does not cross-compile, so darwin-x64 builds on an Intel runner; drop it from platforms
when none is available.
gh workflow run release-grid-runtime.yml -f grid_version=0.3.47 # build all four, publish
gh workflow run release-grid-runtime.yml -f grid_version=0.3.47 -f publish=false # build only, inspect
gh workflow run release-grid-runtime.yml -f grid_version=0.3.47 -f platforms=darwin-arm64,linux-x64,linux-arm64
make upload-grid-runtime ARGS="0.3.47 /path/to/archives" # the publisher CI calls
The pin may only move to a version at or above GRID_VERSION_FLOOR (cli/src/lib/gridExec.ts); the
publisher refuses anything lower, because the daemon would too. Move the floor and the pin in the
same change when a harness release starts to need a newer grid.
Two macOS builds — Intel on Skia, Apple Silicon on Impeller
Every release ships the macOS app twice: the same universal (arm64 + x86_64) build of the same
commit, differing in one Info.plist key, FLTEnableImpeller — which renderer Flutter draws with.
| Build | Renderer | Manifest keys | Files | Installed by |
|---|---|---|---|---|
| Intel | Skia (FLTEnableImpeller = false) |
desktop-macos, desktop-macos-dmg |
Harness-macos.{zip,dmg} |
Intel Macs, every install from before the split on either CPU, and the website download |
| Apple Silicon | Impeller (the engine default) | desktop-macos-arm64, desktop-macos-arm64-dmg |
Harness-macos-arm64.{zip,dmg} |
Apple Silicon Macs whose updater knows the key |
CI calls scripts/build-macos-variants.py <version> --metadata-prefix <run-prefix>.
It compiles one universal app, copies it into separate directories, pins and verifies each
renderer, then packages, notarizes and uploads both variants in parallel. Version/build-number,
arm64/x86_64 slices, signatures and hardened runtime are checked before publication. Each variant
still receives both app and DMG notarization, with the stapled app inside the DMG. Separate scratch
manifests are combined only after all macOS, Linux and Windows builds succeed, followed by verification of
all nine public downloads. macos-build-timings records the bounded build and per-variant phases.
App copies and DMG staging use independent APFS clones when available. The temporary
notarization ZIP uses faster compression; the downloadable ZIP retains normal compression
and is rebuilt from the stapled app while DMG notarization runs. Compression failures stop
publication; uploads wait for both artifacts and their checks. Packaging phase timings are
printed in the build log. Signing and both notarization checks remain the same.
scripts/publish-macos-variant.sh intel|apple-silicon <version> remains the single-variant entry
point. With --no-build, APP_BUNDLE selects an existing bundle; the uploader's OUTPUT_DIR
keeps parallel archives separate. These overrides do not permit rebuilding an arbitrary path.
Without --metadata-prefix, the coordinator only builds and verifies local bundles.
To validate workflow changes with real signing and notarization, dispatch
desktop-internal-build.yml on the candidate branch with test_build=true. It builds both
renderers, verifies all four internal downloads, records timings, and deletes only that run's
random artifact prefix. It does not update release tags or the live updater manifest.
Why. Intel users report the app stuttering; Apple Silicon users do not. Flutter renders macOS with
Impeller by default, and the one thing that differs between those two users running the same universal
build is the GPU Impeller drives — so the Intel build opts out. A release build can only opt out through
Info.plist: the engine compiles its command-line switches out of release (GetSwitchesFromEnvironment),
and an Info.plist belongs to a bundle, so choosing by CPU means shipping two bundles. The x86_64 code an
Intel Mac runs is identical in both — the split is about the renderer, not the CPU slices; a universal
build was already native on Intel.
Why both stay universal. The Intel build carries the key every older install polls, Apple Silicon ones included, so it has to launch on both. The Apple Silicon build stays universal so a Mac running it under Rosetta, or a DMG handed to the wrong person, still launches.
Why the Intel build kept the old key and file name. desktop-macos is what every install before the
split polls, and desktop-macos-dmg is what harness.autonomous.ai/desktop/download-macos serves. The
Skia build there fixes every Intel Mac on its next update, with no new updater needed first, and hands a
new visitor a build that works on whatever Mac they have — so the website needed no change. The cost is
one release on Skia for an Apple Silicon Mac arriving from an old build or from the website: the build
it lands on already asks for desktop-macos-arm64, and moves onto Impeller at the next release (not the
same one — the updater only ever moves to a strictly newer version).
How the updater picks (DesktopUpdater._otaKeys). An Intel Mac reads desktop-macos only — the
arm64 build renders on exactly what it must not, however new. Apple Silicon reads both and takes the
newer, desktop-macos-arm64 winning a tie: a release that published both installs the Impeller
build, and one that only moved desktop-macos (a hand publish that stopped halfway, say) still reaches
it rather than hiding behind an older arm64 entry.
TODO(BE): this is a workaround, not a diagnosis, and it has a real cost. Every machine this app is
developed on is Apple Silicon, on Impeller, so Intel users now run a renderer nobody here looks at, and a
Skia-only rendering bug reaches them unseen. Nothing here has measured that Skia cures the stutter
either — confirm it with an Intel user on the first release that carries it, and if they still stutter
on Skia, the renderer was not the cause and this split should go. The Grid app is the precedent both
ways: it added this exact opt-out for Intel (autonomous-grid-app 87def3c6) and removed it the same
day (58687e7f), because its real cause turned out to be CI shipping a newer Flutter than the team ran,
fixed by pinning. Harness's release already builds with the Flutter it is developed on (FLUTTER_VERSION in
release-desktop.yml), so that cause
does not apply here. Re-check on every Flutter bump: the engine reads FLTEnableImpeller in
FlutterDartProject.mm, and the day that read goes away the Intel build silently goes back to Impeller.
Publishing by hand
scripts/publish-macos-variant.sh (one macOS build per run) and scripts/upload-desktop-linux.sh are
the publishing steps. The macOS one builds and pins the renderer, then hands the bundle to
scripts/upload-desktop.sh --no-build, which does everything after the build exactly as it always has.
CI runs them with the version taken from the tag, and they are also reachable directly when CI cannot be:
make upload-desktop VERSION=1.3.0 # both macOS builds, Intel first
make upload-desktop VERSION=1.3.0 ARGS="--no-notarize" # the same, Developer ID signed only
bash scripts/publish-macos-variant.sh intel 1.3.0 # one macOS build
bash scripts/publish-macos-variant.sh apple-silicon 1.3.0
bash scripts/publish-macos-variant.sh intel 1.3.0 --build-only # build + pin the renderer, publish nothing
make upload-desktop-linux ARCH=arm64 # per Linux architecture
macOS takes an explicit version. Two runs have to publish one version, and upload-desktop.sh's own
auto-bump reads the manifest — the second run would see the first one's upload and bump again.
make release-desktop ARGS="--dry-run" prints the next one. ⚠️ upload-desktop.sh run on its own still works,
and is now wrong: it builds without the renderer pin and writes desktop-macos, which puts Impeller
back on every Intel Mac. Go through publish-macos-variant.sh.
These create no git tag, so the repo stops reflecting what is published — one tag, v1.0.52, once
sat nine releases behind a manifest already serving 1.0.61. Prefer make release-desktop; if you do publish
by hand, cut a make release-desktop afterwards to bring the tag back in line, and remember it only publishes
the platform you ran it on.
For one macOS build, publish-macos-variant.sh:
- Takes the build (
intel/apple-silicon) and the version it was given (CI passes the tag'sX.Y.Z). - Runs
flutter build macos --release --build-name=<version> --build-number=<n>— the version is stamped into the bundle'sInfo.plistat build time, not read from any file. - Pins the renderer. Intel: writes
FLTEnableImpeller = false, reads it back, and re-signs the outer bundle — the edit broke Xcode's seal — keeping the identity, hardened runtime and entitlements Xcode signed it with, and failing if the entitlements come out different. Apple Silicon: writes nothing, and fails if the key is there, so an opt-out committed tomacos/Runner/Info.plistcannot quietly put it on Skia. Both then verify the signature and the hardened runtime. - Hands the bundle to
upload-desktop.sh --no-buildwith that build's keys and file names (OTA_KEY,DMG_KEY,GCS_PATH,DMG_GCS_PATH— set per build, so two runs cannot write each other's), which: - Asserts the built bundle's
CFBundleShortVersionStringreally carries that version before publishing anything. - Packages the
.appwithditto -c -k --sequesterRsrc --keepParent(keeps the bundle structure and extended attributes intact — a plainzipdoes not). - Notarizes the zip, staples the ticket into the
.app, and asserts Gatekeeper accepts it (spctl). - Packages a
.dmgfrom that same stapled bundle — a staging folder holdingHarness.appplus an/Applicationssymlink, imaged withhdiutil— then signs, notarizes and staples the image too. The final ZIP is rebuilt during DMG notarization; both artifacts must finish and pass their checks. - Uploads both artifacts with a year-long immutable
Cache-Control(see "GCS layout"). - Download-merge-reuploads
metadata.jsonin a single write, touching only that build's two keys.
A failed build stops the release; nothing is uploaded and no version is consumed.
One build, two artifacts — per macOS build — and why the dmg is separate
Each macOS build is one flutter build and one signature. Its dmg is cut from the bundle its zip was
cut from, after stapling — an app stapled afterwards would leave the image carrying an unstapled copy
that Gatekeeper can only clear by calling Apple on first launch.
The two artifacts serve different jobs and must not be merged:
- zip /
desktop-macos,desktop-macos-arm64— whatDesktopUpdaterconsumes. It unpacks withditto -x -kand thenmvs the running bundle in place. It has no code path for a disk image, and a mounted dmg volume is read-only, so it could not host the app it is asked to replace. - dmg /
desktop-macos-dmg,desktop-macos-arm64-dmg— what a person downloads and drags into Applications. Nothing in the app ever reads these keys.
Expect two notarization submissions per build — four per release, the two builds in parallel on CI. They cannot be collapsed: stapling only attaches a ticket to the exact artifact submitted, so the zip's ticket does not cover the image. The second pass is usually quick because Apple has already seen that app's cdhash.
Publishing also refreshes the public download link with no web deploy: harness.autonomous.ai/desktop/download-macos
(in autonomous-code, apps/web/src/app/desktop/download-macos/) resolves desktop-macos-dmg — the
Intel build, which runs on any Mac — from this same manifest on every request, so the new version is
live the moment step 10 lands. Offering the Apple Silicon dmg there is a change in that repo, not this
one.
GCS layout
gs://s3-autonomous-upgrade-3/harness/desktop/metadata.json
gs://s3-autonomous-upgrade-3/harness/desktop/<version>/Harness-macos.zip (Intel build, Skia)
gs://s3-autonomous-upgrade-3/harness/desktop/<version>/Harness-macos.dmg
gs://s3-autonomous-upgrade-3/harness/desktop/<version>/Harness-macos-arm64.zip (Apple Silicon build, Impeller)
gs://s3-autonomous-upgrade-3/harness/desktop/<version>/Harness-macos-arm64.dmg
The manifest is always read straight off the GCS origin (CDN_ASSET_BASE_URL in upload-desktop.sh/
upload-desktop-linux.sh does not apply to it) — it's polled every ~60s by every running app, and this
product's CDN caps any cacheable response at ~31 days regardless of origin headers, so it must never be
CDN-fronted. The zip/dmg/AppImage it points at are the opposite: immutable once published, so their
url fields point at cdn.autonomous.ai instead, and are uploaded with a long Cache-Control on
purpose.
{
"desktop-macos": {
"version": "1.2.4",
"url": "https://cdn.autonomous.ai/harness/desktop/1.2.4/Harness-macos.zip",
"sha256": "<64 hex>",
"size": 45231920
},
"desktop-macos-dmg": {
"version": "1.2.4",
"url": "https://cdn.autonomous.ai/harness/desktop/1.2.4/Harness-macos.dmg",
"sha256": "<64 hex>",
"size": 47118336
},
"desktop-macos-arm64": {
"version": "1.2.4",
"url": "https://cdn.autonomous.ai/harness/desktop/1.2.4/Harness-macos-arm64.zip",
"sha256": "<64 hex>",
"size": 45231920
},
"desktop-macos-arm64-dmg": {
"version": "1.2.4",
"url": "https://cdn.autonomous.ai/harness/desktop/1.2.4/Harness-macos-arm64.dmg",
"sha256": "<64 hex>",
"size": 47118336
}
}
The bucket must be public-read — that is bucket policy, not something the script sets.
Signing — Developer ID, notarized
The Release build is signed with a real Developer ID Application certificate (team
54DJVWMJCC, "Autonomous Inc.") and notarized — a freshly downloaded copy (browser, Slack,
AirDrop — anything that sets the com.apple.quarantine extended attribute) passes Gatekeeper with
no "unidentified developer" prompt and no manual Open Anyway/xattr -d workaround needed.
What that takes, end to end:
- The signing certificate (
Developer ID Application: Autonomous Inc. (54DJVWMJCC)) must be in the machine's login keychain — not the System keychain, which prompts for an admin password on everycodesigninvocation and breaks a non-interactive build.security find-identity -v -p codesigningshould list it with no password needed to check. macos/Runner.xcodeproj's Runner target Release config carriesCODE_SIGN_STYLE = Manual,CODE_SIGN_IDENTITY = "Developer ID Application",DEVELOPMENT_TEAM = 54DJVWMJCC,ENABLE_HARDENED_RUNTIME = YES, andOTHER_CODE_SIGN_FLAGS = "--timestamp"— notarization hard- rejects a signature with no secure timestamp ("Archive contains critical validation errors"), and Manual signing style doesn't request one on its own the way Automatic does.macos/Runner/Release.entitlementspinscom.apple.security.get-task-allowtofalse— Flutter's build backend stamps thistrueregardless of build mode, and notarization rejects a debugger-attachable binary outright.- A
notarytoolkeychain profile must exist for the script's notarize step (see the comment block at the top ofscripts/upload-desktop.shfor the one-timestore-credentialssetup — needs an app-specific password from appleid.apple.com, never the Apple ID's own password).
scripts/upload-desktop.sh submits the packaged zip to Apple's notary service (notarytool submit --wait), staples the returned ticket onto the .app (stapler staple — this changes the bundle's
contents, so the zip is rebuilt from the stapled bundle before upload), and asserts spctl -a
accepts the result before publishing anything. Skip notarizing with --no-notarize (the build
stays Developer ID signed, just without Apple's ticket — more likely to prompt Gatekeeper on a copy
downloaded fresh by someone else, though probably still fine for the OTA self-update path below,
which doesn't reliably pick up the quarantine flag in the first place).
How a running app self-updates
DesktopUpdaterchecks the manifest once on launch, then every minute (lib/update/desktop_updater.dart) —desktop-macoson an Intel Mac, the newer ofdesktop-macos-arm64anddesktop-macoson Apple Silicon (see "Two macOS builds").- Compares against the running app's own version (
package_info_plus) — strictly newer only, so republishing an old build cannot downgrade anyone. - After the user chooses Update now, downloads the zip and verifies its sha256 before anything is unpacked. A mismatch is discarded.
- Unpacks into a staging directory and re-reads
CFBundleShortVersionStringfrom the staged bundle as a sanity check that the download really is the version it claims to be. It installs it only if whoever signed the running app signed it too (lib/update/update_signature.dart): on macOScodesign --verify --deep --strictagainst a Developer ID requirement with the running app's team and identifier, notarized; on Windows every.exe/.dlland the launcher Authenticode-valid, the app, the launcher andapp/<version>/harness-desktop.catsigned like the runningharness-desktop.exe(subject and Artifact Signing identity), and that catalog matching every file in the folder,data/app.soincluded. Otherwise the banner says it is not signed by the running app's publisher and the current version stays. The manifest can only pick among builds we signed. A running app that is itself unsigned (a local or staging build) keeps the sha256 check alone; Linux AppImages are unsigned, so Linux does too. Rotating keys: a new Developer ID certificate or a renewed Artifact Signing certificate changes neither the team nor the identity, so nothing is needed. A new team or a new identity validation needs one bridge release, signed the old way, whose rule also accepts the new signer. - Checks on launch (including the sign-in screen) and every minute. When a newer build exists, it shows a non-blocking notification. The user chooses Update now to download and install it, or Skip version to silence that exact version. A later version is shown normally; the account menu also has Check for updates to revisit a skipped version.
- On restart: a detached helper process waits for this app to exit, backs the current bundle up as
Harness.app.prev, swaps the staged build into place, relaunches it, and — if the relaunched app doesn't stay alive a few seconds later — restoresHarness.app.prevand relaunches the old build instead.
Rolling out safely
Publish to a scratch manifest before touching the real one, and point a test build at it via
--dart-define. release-desktop.yml has a workflow_dispatch trigger that takes both the version and the
manifest to write, so a rehearsal never touches the real one:
gh workflow run release-desktop.yml -f version=1.3.0 -f metadata_path=harness/desktop/metadata-test.json
flutter run -d macos --dart-define=DESKTOP_UPDATE_METADATA_URL=https://storage.googleapis.com/s3-autonomous-upgrade-3/harness/desktop/metadata-test.json
A debug build does not check at all (canCheck wants release mode), so the line above only does
something in a release build. To exercise the band, its percentage and the install itself while
developing, add --dart-define=DESKTOP_UPDATE_FORCE=true — and always with a scratch manifest, or
the debug build will offer to replace itself with the current public release:
flutter run -d macos \
--dart-define=DESKTOP_UPDATE_FORCE=true \
--dart-define=DESKTOP_UPDATE_METADATA_URL=http://127.0.0.1:8899/metadata.json
A local origin is enough for that manifest: serve a zip of any Harness.app (its
CFBundleShortVersionString must match the version the manifest advertises, which the staging step
verifies) with its real size and sha256 — a local build is ad hoc signed, so it skips the signature check (step 4 above),
while a released build only takes a zip signed by its own team — and write the body slowly if you want to read the
percentage rather than watch it jump to 100. applyStaged replaces the bundle it is running from,
so run a COPY of the build rather than the one flutter run owns.
Internal builds — an unlisted link, not a release
../.github/workflows/desktop-internal-build.yml builds any branch the way a release would — both macOS
builds, Developer ID signed, notarized, stapled and checked by Gatekeeper — and uploads them where
no running app and no public page will ever look:
git push origin HEAD:internal/<name> # builds that commit: Debug off
gh workflow run desktop-internal-build.yml --ref <branch> -f debug_surface=false
(workflow_dispatch only exists once the file is on main; the internal/** push works from any
branch that carries it.) The run prints one .dmg link per build — as a notice at the top of the run
page, and in its summary — named Harness-macos[-arm64]-<next version>-<commit>.dmg.
- Unlisted, not private — and this repository is public. The files sit under
harness/desktop-internal/<128 random bits>/and the bucket refuses anonymous listing, so a build cannot be found by guessing. The run page that prints its link is public, though, so anyone who opens it can download the build. The team chose that on 2026-09-10 over a key-derived link that only key holders could work out; if it stops being acceptable, that is the design to go back to. - Take a build back with
gcloud storage rm -r gs://s3-autonomous-upgrade-3/harness/desktop-internal/<token>(the summary prints it); the workflow strips the release's year-long cache headers from these files so a deletion sticks. - It never updates itself.
DESKTOP_UPDATE_METADATA_URLpoints at a manifest nothing writes, so a tester stays on the build they were asked to test rather than being moved onto the next public release. The next internal build is installed by its own link. - Same code path as a release, flags aside.
publish-macos-variant.sh --build-onlybuilds and pins the renderer (its--dart-define=arguments go toflutter buildand nowhere else), thenupload-desktop.sh --no-buildpackages, notarizes and uploads, moved onto the internal prefix by its existing env overrides (GCS_PATH,DMG_GCS_PATH,METADATA_PATH). Its signing steps are the release's own.github/actions/macos-signing, so an internal build also proves those before a release depends on them. - Why not by hand. An Info.plist edited and re-signed on a laptop reached a tester as "The application "Harness" can't be opened", and a laptop without the notarytool profile cannot notarize at all — which is what makes a copy downloaded fresh on another Mac open cleanly.
Rollback
The relaunch-health check (step 6 above) only guards against a build that fails to start. To roll back a build that starts but is otherwise broken, publish a higher version containing the older code — the updater refuses to move backwards, so editing the manifest to an older version will not roll a running app back.
Linux
scripts/upload-desktop-linux.sh publishes architecture-specific Linux ARM64 and x64 releases to the
same metadata.json as macOS. release-desktop.yml runs it on both a ubuntu-22.04 and a
ubuntu-22.04-arm runner — the oldest Ubuntu supported, because the bundle links the build host's
GLib and glibc and a 24.04 build will not start on 22.04 — so one make release-desktop covers every build — which is also why the nine
desktop-* keys only stay on one version when the release goes through CI. Run by hand
(make upload-desktop-linux ARCH=arm64) it moves one key and leaves the others behind. amd64 and
x86_64 are accepted aliases for x64; aarch64 is accepted as an alias for arm64.
With no ARCH, the command detects the host architecture. A build must run on a matching
Ubuntu/Linux host because Flutter Linux desktop builds use the host architecture. --no-build can
package and upload an already-built bundle for the selected architecture. APPIMAGETOOL must point
at an executable appimagetool-<x86_64|aarch64>.AppImage — release-desktop.yml downloads a pinned one per
matrix job; running by hand, fetch one yourself from the
AppImage/appimagetool releases.
No signing/notarization step — there is no Linux equivalent of Apple's Developer ID/notarization,
and none is needed: the trust boundary is the same sha256-verified manifest entry DesktopUpdater
already checks on every platform.
The Linux viewer uses the host's WebKitGTK 4.1 runtime (libwebkit2gtk-4.1-0). The AppImage
contains Harness and its Flutter bundle, but does not bundle WebKitGTK. The Linux plugin is loaded
optionally: if the host runtime or plugin is unavailable, Harness still launches and viewer panes
show the URL placeholder (recordings offer browser playback). Install the runtime package and
restart Harness to enable embedded viewing. Linux release builds also need
libwebkit2gtk-4.1-dev on the build host.
webview_all_linux is deliberately pinned to 1.2.1: its published manifest uses
webview_flutter_platform_interface, while 1.3.0 switched to the separate
webview_platform_interface package. A caret constraint would allow that incompatible
interface change. The lockfile records the source archive hash; upgrading the plugin
requires reviewing its native code and rerunning Linux integration tests. The pin
neither freezes the distribution's WebKitGTK security updates nor establishes that
the plugin has been security-audited or endorsed by Flutter. It is MIT-licensed;
retain its attribution in Flutter's bundled notices.
webview_win_floating is deliberately pinned to 2.3.2, its last release that registers on
Windows alone: 3.x registers on Linux too, where it would replace webview_all_linux. Its
fullscreen_window dependency still adds that small native plugin to the Linux build. It and
video_player_win, pinned to 3.3.1, are BSD-3-Clause and one author's work, not endorsed by
Flutter. Upgrading either requires reviewing its native code and retesting on Windows. Their
DLLs ship in the Windows package, which the release signs. Retain their attribution in
Flutter's bundled notices.
The official webview_flutter
currently lists Android, iOS and macOS implementations, with no endorsed Linux
implementation. webview_flutter_linux
is an experimental, non-endorsed WPE WebKit implementation requiring WPE WebKit 2.52+,
so it is not a drop-in endorsed replacement for this GTK integration.
GTK views are detached while registered Flutter transient overlays are open, including pane menus, the agent picker and resize help. All native viewers are hidden for that interval because a popup may cross pane boundaries; their controllers retain the loaded pages. Dismissal restores them without navigation or reload.
Packaged as a single-file AppImage, not a tarball. The script stages an AppDir
(usr/bin/ = the Flutter bundle/ verbatim, plus a hand-written harness.desktop and the
harness.png icon CMake already installs at the bundle root) and hands it to appimagetool with
--appimage-extract-and-run, so packaging needs no FUSE on the build host. AppRun is a plain
symlink to usr/bin/harness — the Flutter runner locates its own lib//data/ next to
/proc/self/exe, which resolves to the real binary after exec regardless of the symlink used to
launch it.
No Info.plist-style version stamp. flutter build linux has nowhere to stamp a version the way
Xcode does into Info.plist, so the release script writes a plain version.txt into the built
bundle (build/linux/<arm64|x64>/release/bundle/version.txt, which ends up at usr/bin/version.txt
inside the AppDir) and asserts it before packaging. lib/core/app_version.dart (what Settings ▸
About shows) reads this file back on Linux, falling through to PackageInfo.fromPlatform() (which
would otherwise just return pubspec.yaml's never-bumped placeholder) everywhere else — this still
works unchanged for a running AppImage, since the AppImage runtime mounts the whole AppDir at a
temporary path and the app resolves version.txt relative to its own (mounted) executable exactly
as it did inside the old tarball. lib/update/desktop_updater.dart's downloadAndStage() does
not re-verify this against the manifest for Linux — sha256 already authenticates the entire
single-file download, so there's nothing left inside it to disagree with the hash.
GCS layout
gs://s3-autonomous-upgrade-3/harness/desktop/metadata.json (shared with macOS, different key)
gs://s3-autonomous-upgrade-3/harness/desktop/<version>/Harness-linux-x64.AppImage
gs://s3-autonomous-upgrade-3/harness/desktop/<version>/Harness-linux-arm64.AppImage
{
"desktop-linux-x64": {
"version": "1.2.4",
"url": "https://cdn.autonomous.ai/harness/desktop/1.2.4/Harness-linux-x64.AppImage",
"sha256": "<64 hex>",
"size": 41230011
}
}
How a running Linux app self-updates
Same shape as macOS (see above), with the platform-specific pieces:
DesktopUpdaterreads thedesktop-linux-arm64ordesktop-linux-x64manifest entry for its runtime architecture instead ofdesktop-macos.- The download IS the artifact — a single
.AppImagefile, made executable after its sha256 verifies, with nothing to unpack. - On restart, the detached helper resolves the running AppImage's own path from the
APPIMAGEenvironment variable (set by the AppImage runtime on launch — the process itself runs from a temporary FUSE mount, not from that path),mvs it to a.prevbackup,mvs the staged file into its place, then execs that same path directly (there's noopen -n/LaunchServices equivalent for a plain packaged Linux binary) and checks it's still alive withpgrep -f, same as macOS.
Rolling out safely / rollback
Same conventions as macOS — publish to a scratch METADATA_PATH first, and roll back only by
publishing a newer version containing the older code (see above).
Windows
Every release ships Windows with macOS and Linux: release-desktop.yml's build-windows builds each architecture on
its own runner and upload-windows publishes from ubuntu. Three files go to harness/desktop/<version>/:
Harness-windows-x64.zipandHarness-windows-arm64.zip(desktop-windows-x64,desktop-windows-arm64), the install-shaped zips below, which the Windows updater andinstall.ps1 -Apptake;harness-install.exe(desktop-windows-installer), what the website's Download for Windows serves. It carries no app: it reads the manifest when it runs, picks this PC's zip asinstall.ps1 -Appdoes, checks it and runs itsHarness.exe --install(installer/, docs/superpowers/specs/2026-10-19-windows-installer-design.md).
sign-windows Authenticode-signs every .exe and .dll in both zips and harness-install.exe through Azure Artifact
Signing, then writes and signs app/<version>/harness-desktop.cat, a catalog of every file in the version folder
that the updater checks ("How a running app self-updates", step 4), as AUTONOMOUS INC., once the repository variable WINDOWS_SIGNING is required
(docs/windows-code-signing.md). Until then it is skipped and the files ship
unsigned: Windows shows SmartScreen once, on the installer a browser downloaded, and Smart App Control blocks the build
where it is on. Once signing is required, a failed signature stops the release and a candidate prepared unsigned is
not reused. A failed Windows build stops the release, as a failed macOS or Linux build does.
If Microsoft Defender flags harness-install.exe or the app, submit the file as a software developer at
https://www.microsoft.com/wdsi/filesubmission with the release version. Do not change the build to dodge a detection.
Staging
scripts/package-windows.ps1 packages the complete Flutter Release bundle in the per-user install shape:
Harness.exe (the harness-desktop-launcher binary), Harness.ico, current, and
app\<version>\ with harness-desktop.exe, harness_pipe_io.dll, the other runtime DLLs and data\.
The app's first-frame .started marker is excluded. Harness.exe --install installs from this
zip, and the Windows updater consumes the same layout. The version comes from the app EXE's
ProductVersion resource, stamped by flutter build windows --build-name <version>; Windows
does not use a version.txt file.
The Windows desktop workflow has a release mode that builds both x64 and arm64 staging zips, and a staging
harness-install.exe (desktop-windows-installer) in the x64 job, on
their own runners. It passes --dart-define=HARNESS_STAGING=true, so the installed app reads the
staging desktop manifest and installs the staging CLI. dry_run defaults to true. Its artifact
contains proposed Windows manifest entries, computed without reading or writing the bucket;
it does not describe the live manifest's unrelated keys. A live staging publication requires the
owner's explicit approval, then merges the two keys into the observed staging manifest generation:
# Only after approval for this staging publish:
gh workflow run windows-desktop.yml -f release=true -f version=<version> -f dry_run=false
gs://s3-autonomous-upgrade-3/harness/staging/desktop/metadata.json
gs://s3-autonomous-upgrade-3/harness/staging/desktop/<version>/harness-desktop-<version>-windows-x64.zip
gs://s3-autonomous-upgrade-3/harness/staging/desktop/<version>/harness-desktop-<version>-windows-arm64.zip
gs://s3-autonomous-upgrade-3/harness/staging/desktop/<version>/harness-install.exe
The publisher validates both complete zips (check-windows-zip.py) and the installer before upload, creates each versioned object only
when absent, reads the uploaded bytes back, and conditionally writes the manifest so another
publisher's change cannot be lost. If a publish stops after uploading an object, that version is
spent: inspect staging and use a new version. Signing is separate.
Install by one command. After an approved staging publish, bash cli/scripts/upload-install-ps1.sh --app
publishes harness/staging/desktop/install.ps1, a copy of B's installer with its app-default line on. A person runs
irm https://cdn.autonomous.ai/harness/staging/desktop/install.ps1 | iex. It chooses this PC's zip from the staging
desktop manifest, verifies its size and SHA-256, and runs the zip's Harness.exe --install. PowerShell's download
does not add the browser's mark of the web, so SmartScreen does not show its first-run prompt. Smart App Control can
still block an unsigned build. --app --production is the owner's later publication step, after production has the
Windows manifest keys.
First production release
The first release with Windows follows the merge of the Windows PR, and each step needs the owner's go. The CLI side
comes first: the app installs the CLI through the production install.ps1, which 404s until step 5. Until then, do
not cut a desktop release, because every desktop release now publishes the Windows zips and harness-install.exe.
- the CLI release. macOS and Linux go to production; its Windows terminal host and CLI go to staging only;
- the staging E2E on Windows (docs/testing/windows-cli-e2e.md) with that release;
- the Windows Node runtime manifest, through the Node workflow with the production
metadata_path; cli/scripts/promote-pty-payload.sh <that release>, which uploads nothing and checks each payload file's SHA-256 and size;bash cli/scripts/upload-install-ps1.sh --production. It refuses until production has this CLI's Windows terminal host and a Windows Node runtime;make release-desktop, the first with the Windows keys;bash cli/scripts/upload-install-ps1.sh --app --production, which refuses until production has both Windows zips;- the website release. Its Windows download answers 503 until the production manifest has
desktop-windows-installer, so it goes last.