Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.
Releasing three.ws Forge for desktop
How a three.ws Forge version gets from apps/forge-desktop/ to the download
page at three.ws/forge-desktop and to the
in-app updater. User guide: docs/forge-desktop.md.
Publishing is owner-gated (CLAUDE.md, stop-and-ask gate 2). Every step below defaults to a dry run that builds and stages without touching the live feed.
How the pieces fit
| Piece | Where | What it does |
|---|---|---|
| Release history | apps/forge-desktop/releases.json |
Version, date and notes, newest first. A build refuses to run without an entry for package.json's version. |
| Manifest | apps/forge-desktop/scripts/release-manifest.mjs |
Hashes the built artifacts and writes release.json, merging the platforms an earlier build already published. Shares its classifier with three.ws Desktop. |
| Linux and Windows | apps/forge-desktop/cloudbuild.yaml |
AppImage, .deb and the NSIS installer on Cloud Build. Signs Windows when the certificate secrets exist. |
| macOS | apps/forge-desktop/scripts/release-mac.sh |
The .dmg and .zip on a Mac (Cloud Build has no macOS workers). Signs and notarizes when the Apple secrets exist. |
| Bucket | gs://three-ws-desktop-releases, prefix releases/forge/ |
Shared with three.ws Desktop (releases/desktop/). Staged builds land in staging/forge/<version>/<build>/. |
| CDN route | apps/desktop/scripts/setup-release-cdn.mjs |
One-time: serves /releases/* on the production load balancer from the bucket through Cloud CDN. |
| Download page | pages/forge-desktop.html, src/forge-desktop.js |
Reads https://three.ws/releases/forge/release.json. A 404 shows the "run it from source" state. |
| Updater | apps/forge-desktop/electron/main/updater.ts |
electron-updater on the generic feed (latest.yml, latest-linux.yml). Patch versions install themselves; minor and major versions prompt. Off on macOS until builds are Developer ID signed. |
One-time setup
The bucket and the /releases/* route are shared with three.ws Desktop, so if
Desktop already ships, skip this.
node apps/desktop/scripts/setup-release-cdn.mjs # plan: prints every command
node apps/desktop/scripts/setup-release-cdn.mjs --apply # owner-gated: edits the production URL map
curl -sI https://three.ws/releases/forge/release.json # 404 until the first publish, from the bucket rather than the app
Cut a version
- Bump
versioninapps/forge-desktop/package.json. - Add the matching entry at the top of
apps/forge-desktop/releases.json(version, date, notes withtitle,summary,tags). The notes are what the download page shows, so write them for users. - Commit both.
Build Linux and Windows
From the repo root:
# Dry run: builds, writes release.json, stages under staging/forge/<version>/<build id>/
gcloud builds submit --config apps/forge-desktop/cloudbuild.yaml \
--ignore-file apps/forge-desktop/.gcloudignore \
--region us-central1 --project aerial-vehicle-466722-p5
# Publish (owner-gated)
gcloud builds submit --config apps/forge-desktop/cloudbuild.yaml \
--ignore-file apps/forge-desktop/.gcloudignore \
--region us-central1 --project aerial-vehicle-466722-p5 \
--substitutions _PUBLISH=1
Inspect a dry run with gcloud storage ls gs://three-ws-desktop-releases/staging/forge/<version>/
and download release.json from there to check the file list and hashes.
Windows signing reads desktop-windows-csc-link (the .pfx, base64) and
desktop-windows-csc-password from Secret Manager, the same publisher identity
as three.ws Desktop. Without them the installer is unsigned, release.json
marks it "signed": false, and the download page shows the SmartScreen steps.
Build macOS
On a Mac with Xcode command line tools, Node 20+ and gcloud signed in to
aerial-vehicle-466722-p5, after the Linux and Windows build so the manifest
merges into theirs:
bash apps/forge-desktop/scripts/release-mac.sh # build and stage
PUBLISH=1 bash apps/forge-desktop/scripts/release-mac.sh # also publish (owner-gated)
Signing reads desktop-macos-csc-link and desktop-macos-csc-password;
notarization reads desktop-apple-api-key, desktop-apple-api-key-id and
desktop-apple-api-issuer. Without them the app is ad-hoc signed, the page
marks it unsigned and shows the Open Anyway steps, and the in-app updater
stays off on macOS.
Publish order
Both publish paths upload in the same order so no client ever sees a feed entry before its file exists:
- Binaries, under versioned names, cached for a year (
immutable). versions/<version>.json, a permanent copy of this release's manifest.release.jsonand thelatest*.ymlupdater feeds, uncached.
Verify
curl -s https://three.ws/releases/forge/release.json | jq '{version, files: [.files[] | {platform, kind, size, signed}]}'
curl -sI "$(curl -s https://three.ws/releases/forge/release.json | jq -r '.files[0].url')" | head -1
Then open three.ws/forge-desktop: the hero offers your platform's build, and All downloads lists every file with its size and SHA-256. Check one hash against the downloaded file.
Roll back
Point the feed back at the previous version's manifest. The binaries it names are still in the bucket because versioned names are never deleted:
gcloud storage cp gs://three-ws-desktop-releases/releases/forge/versions/<previous>.json \
gs://three-ws-desktop-releases/releases/forge/release.json --cache-control="no-cache, max-age=0"
The latest*.yml updater feeds must be rolled back the same way from the
previous build's staging directory, or installed apps keep offering the bad
version.