Skip to content

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.

docs(forge-desktop): document three.ws Forge for desktop, its release runbook and its place in the repo

nirholasf4e4d4d95fca
diff --git a/STRUCTURE.md b/STRUCTURE.md
index e60df86a1..c386455fa 100644
--- a/STRUCTURE.md
+++ b/STRUCTURE.md
@@ -46,6 +46,7 @@ bottom.
| Diorama (text → 3D world) | [src/diorama/](src/diorama) `→ /diorama` | In-repo · backend [api/diorama.js](api/diorama.js) | One sentence → an explorable 3D diorama: Claude composes the scene, each object is forged to a real GLB, assembled live, saved to a public gallery + shareable permalink |
| Workbench (image → 3D workflows) | Page [pages/workbench.html](pages/workbench.html) `→ /workbench` + [src/workbench/](src/workbench): controller [main.js](src/workbench/main.js), viewport [viewport.js](src/workbench/viewport.js), in-browser mesh ops [mesh-tools.js](src/workbench/mesh-tools.js), node model [workflows.js](src/workbench/workflows.js), runner [runner.js](src/workbench/runner.js), graph editor [graph-editor.js](src/workbench/graph-editor.js), API client [api.js](src/workbench/api.js) | Live | A desktop-style workspace: icon rail (Generate, Workflows, Extensions, Settings), a workflow panel of node cards, and a viewport with undo/redo, import, GLB/OBJ/STL/PLY export, smooth, decimate and free memory. Workflows are typed image/mesh chains saved per browser and edited in a node graph; they run against the real Forge endpoints (`/api/forge`, `/api/forge-rembg`, `/api/forge-remesh`, `/api/forge?action=rig`, `/api/material-studio`), checkpointing in-browser edits to durable storage before any server step. Extensions reads the live engine catalog and lane health. Docs: [docs/workbench.md](docs/workbench.md) |
| Modly (local GPU generation + Modly app integrations) | Hub page [pages/modly.html](pages/modly.html) `→ /modly` + [src/modly-page.js](src/modly-page.js); shared local client [src/modly-local.js](src/modly-local.js); Forge "Use your GPU" lane [src/forge-modly.js](src/forge-modly.js) wired in [src/forge.js](src/forge.js) `→ /forge`; desktop app [apps/forge-desktop/](apps/forge-desktop); Modly extensions [integrations/modly/](integrations/modly) | Live (web); desktop app and extensions in-repo | Builds on Modly (MIT, Lightning Pixel). Browser surfaces talk to the visitor's own Modly on localhost only after Connect, run its image-to-3D models with real progress and cancel, and copy results to storage so rig/optimize/AR work. Modly users get three.ws cloud nodes and publishing. Docs: [docs/modly.md](docs/modly.md). Tests: tests/modly-local.test.js, integrations/modly/tests/ |
+| three.ws Forge for desktop (Electron app) | App [apps/forge-desktop/](apps/forge-desktop) (Electron main [electron/main/](apps/forge-desktop/electron/main), React renderer [src/](apps/forge-desktop/src), FastAPI engine [api/](apps/forge-desktop/api)); download page [pages/forge-desktop.html](pages/forge-desktop.html) `→ /forge-desktop` + [src/forge-desktop.js](src/forge-desktop.js), [src/forge-desktop-release.js](src/forge-desktop-release.js); release pipeline [apps/forge-desktop/cloudbuild.yaml](apps/forge-desktop/cloudbuild.yaml), [scripts/release-mac.sh](apps/forge-desktop/scripts/release-mac.sh) | In-repo; download page live after deploy, shows "run from source" until the first release is published (owner-gated) | Fork of Modly (MIT, Lightning Pixel) rebranded and wired to three.ws: device-flow sign-in with the key in OS secure storage, one-click Publish to `/avatars/:id`, the CC0 library in Import, three.ws cloud nodes, and an electron-updater feed at `/releases/forge/`. Docs: [docs/forge-desktop.md](docs/forge-desktop.md), runbook [docs/ops/forge-desktop-release.md](docs/ops/forge-desktop-release.md). Tests: tests/forge-desktop-release.test.js, apps/forge-desktop `npm run test:node` |
| Mesh tools + slicer handoff | [src/mesh-ops/](src/mesh-ops) (worker repair/smooth/decimate, panel in Forge Optimize and `/m/:id`), [src/slicer-handoff.js](src/slicer-handoff.js), route [api/slicer/model.js](api/slicer/model.js) `→ /api/slicer/:id/[Nmm/]model.stl\|3mf` over [api/_lib/print/slicer.js](api/_lib/print/slicer.js) | Live after deploy; adapted from Modly (MIT) | In-browser mesh repair, Taubin/Laplacian smoothing and decimation with undo, plus Open in OrcaSlicer / Bambu Studio and print-ready STL/3MF downloads. Docs: [docs/forge.md](docs/forge.md). Tests: tests/mesh-ops.test.js, tests/slicer-handoff.test.js |
| CAD Forge (text → parametric CAD) | Page [pages/cad.html](pages/cad.html) + [src/cad/](src/cad) `→ /cad` and `→ /cad/:id` (controller [main.js](src/cad/main.js), viewer [viewer.js](src/cad/viewer.js), shared parameter contract [params.js](src/cad/params.js)), API [api/cad.js](api/cad.js) `→ /api/cad` over [api/_lib/cad/](api/_lib/cad) (writer ladder, write/build/repair loop, store, service), MCP tools [api/_mcp3d/tools/cad.js](api/_mcp3d/tools/cad.js) (`cad_generate`, `cad_rebuild`), sandboxed kernel worker [workers/cad-forge/](workers/cad-forge) | Built and verified locally · worker deploy pending (deploy it before the API image that carries `/cad`) | A sentence becomes a build123d program the OpenCascade kernel has accepted: kernel errors go back to the writer (Kimi K3 on NIM first) until it builds, and the page streams each real stage. Key dimensions are annotated constants that become sliders; each value set rebuilds on the kernel and is cached under its own link. Downloads STEP, STL, GLB (true scale), a four-view SVG drawing and the Python program; handoffs to AR, Materialize and Scene Studio; refinements are linked designs. Parts join cross-entity search as type `part`. The worker runs model-written code with a static policy, seccomp, an unprivileged uid and rlimits, under a zero-role service account. Docs: [docs/cad-forge.md](docs/cad-forge.md). Tests: [tests/cad-forge.test.js](tests/cad-forge.test.js) plus the worker's in-image gate |
| Scene Composer (dress an avatar) | [pages/compose.html](pages/compose.html) `→ /compose` + [src/scene-compose.js](src/scene-compose.js) | Live | Forge props from text and parent them to a rigged avatar's skeleton bones, then Export GLB or save them back onto the avatar record as `appearance.attachments`. Bones are grouped into readable regions and stripped of rig prefixes; transform gizmos, 50-deep undo, grid snap, camera presets. Feeds off [api/forge.js](api/forge.js), [api/forge-gallery.js](api/forge-gallery.js) (own creations, falling back to the community showcase for a first-time visitor), [api/explore.js](api/explore.js) `?source=avatar&only3d=1` for the avatar picker, and `PATCH /api/avatars/:id` for Save outfit. Below 900px the scene panel becomes a drawer. Docs: [docs/compose.md](docs/compose.md) |
diff --git a/apps/forge-desktop/CONTRIBUTING.md b/apps/forge-desktop/CONTRIBUTING.md
index fa86d63fc..2b6a85844 100644
--- a/apps/forge-desktop/CONTRIBUTING.md
+++ b/apps/forge-desktop/CONTRIBUTING.md
@@ -1,48 +1,52 @@
# Contributing to three.ws Forge
-Thanks for wanting to help out! You don't need write access to the repository to
-pick up a ticket, work on it, and ship a fix, here's how the flow works.
+three.ws Forge lives in the three.ws repository, so it follows the repo-wide
+[contributing guide](../../CONTRIBUTING.md): the same issue tracker, branch
+flow, commit style and pre-push checks. This page covers what is specific to
+the desktop app.
-## Finding something to work on
+## Where things go
-- Browse [open issues](https://github.com/lightningpixel/modly/issues) or the
- [project board](https://github.com/users/lightningpixel/projects/1).
-- Issues labeled `good first issue` are a good place to start if you're new to
- the codebase. See [`CLAUDE.md`](./CLAUDE.md) for an architecture overview.
+| Change | Where to send it |
+|---|---|
+| A bug or feature in three.ws Forge, including the three.ws sign-in, Publish, library and cloud nodes | [three.ws issues](https://github.com/nirholas/three.ws/issues) |
+| A bug that also exists in an unmodified Modly (the generators, the node editor, the Python engine) | [Modly issues](https://github.com/lightningpixel/modly/issues) as well, so the fix can reach both apps |
+| A new local model | Its own GitHub repository with a Modly-compatible `manifest.json`; Forge installs it from the **Models** tab |
-## Claiming a ticket
+[Your first contribution](../../docs/first-contribution.md) walks through
+claiming an issue and opening a pull request.
-Comment **`/assign`** on the issue you want to work on. A bot will assign it to
-you automatically, no repo permissions required.
+## Run it
-- Only one person can be assigned to an issue at a time. If it's already
- assigned, ask the assignee first or wait for them to release it.
-- No longer working on it? Comment **`/unassign`** to free it up for someone
- else.
+```bash
+cd apps/forge-desktop
+npm install
+npm run prepare-resources # standalone Python for your platform
+npm run dev
+```
-This keeps the [project board](https://github.com/users/lightningpixel/projects/1)
-honest: an assigned issue moves to **In progress** automatically, so anyone
-looking at the board can see what's actively being worked on.
+The app has three layers: the Electron main process in `electron/main/`, the
+React renderer in `src/`, and the FastAPI engine in `api/` on
+`127.0.0.1:8765`. The [user guide](../../docs/forge-desktop.md) describes what
+each screen does.
-## Submitting your work
+## Before you open a pull request
-1. **Fork** the repository and create a branch for your change.
-2. Make your change. Keep it focused, one issue, one PR.
-3. Run the checks locally before opening a PR:
- ```bash
- npm run lint
- npm run test
- ```
-4. Open a **pull request** against `dev`. Include `Closes #<issue-number>` in
- the PR description so it's linked to the ticket and closes it automatically
- on merge.
+```bash
+npm run lint
+npm run test # Node tests, then the Python engine tests
+npm run build # typechecks and bundles main, preload and renderer
+```
-Opening a PR from your fork moves the linked issue to **Ready to review** on
-the board. Once a maintainer approves the review, it moves to **Ready to
-test**; once merged, it moves to **Done**.
+From the repo root, `npm run check:rules -- --paths <files you changed>` checks
+your added lines against the house rules the pre-push hook enforces.
-## Getting help
+Open the pull request against `main` with `Closes #<issue-number>` in the
+description. Keep it to one change: a fix to the three.ws integration and an
+upstream sync are reviewed separately.
-If something in an issue is unclear, ask in a comment on the issue itself
-before starting, it's cheaper to clarify scope up front than to redo work
-later.
+## License
+
+Forge is based on [Modly](https://github.com/lightningpixel/modly) by Lightning
+Pixel, used under the MIT license ([LICENSE](./LICENSE), [NOTICE](./NOTICE)).
+Keep both files and the About screen credit intact.
diff --git a/apps/forge-desktop/README.md b/apps/forge-desktop/README.md
index 0a6798ea3..f316e5921 100644
--- a/apps/forge-desktop/README.md
+++ b/apps/forge-desktop/README.md
@@ -4,11 +4,11 @@
# three.ws Forge
-**Local, open source, AI-powered image-to-3D mesh generation.**
-Turn any photo into a 3D model using open source AI models running entirely on your GPU.
+**The desktop 3D studio for three.ws.**
+Turn any photo into a 3D model with open-source AI models running entirely on your GPU, or with the three.ws cloud when you have no GPU. Chain mesh tools in node workflows, import free CC0 models from the three.ws library, and publish to your three.ws account in one click.
three.ws Forge is a desktop application for Windows, Linux, and Apple Silicon macOS.
-> Created by [Lightning Pixel](https://github.com/lightningpixel)
+> Based on [Modly](https://github.com/lightningpixel/modly) by [Lightning Pixel](https://github.com/lightningpixel), used under the MIT license.
<p align="center">
<img src="docs/app-screenshot.png" alt="three.ws Forge screenshot" />
@@ -19,9 +19,9 @@ three.ws Forge is a desktop application for Windows, Linux, and Apple Silicon ma
## Download
-Head to the [Releases](../../releases/latest) page to download the latest installer for Windows, Linux, or Apple Silicon macOS.
+Get the installer for Windows, Linux, or Apple Silicon macOS from [three.ws/forge-desktop](https://three.ws/forge-desktop). The page lists every build with its size and SHA-256, and the release notes. The user guide is at [three.ws/docs/forge-desktop](https://three.ws/docs/forge-desktop).
-Alternatively, you can clone the repository and run the app directly without installing:
+Alternatively, you can run the app from this directory without installing:
```bash
# Windows
@@ -33,7 +33,21 @@ launch.bat
---
+## three.ws integration
+<p align="center">
+ <img src="docs/forge-library.png" width="32%" alt="The three.ws library popover with chair search results" />
+ <img src="docs/forge-publish.png" width="32%" alt="The Publish to three.ws popover" />
+ <img src="docs/forge-settings.png" width="32%" alt="The three.ws section of Settings" />
+</p>
+
+- **Account.** Settings, then three.ws: sign in through your browser (the same device flow as the three.ws CLI) or paste an `sk_live_` API key from [three.ws/dashboard/developers](https://three.ws/dashboard/developers). The key is encrypted with Electron `safeStorage` and synced to the Python engine so the three.ws workflow nodes are signed in too ([electron/main/three-ws-account.ts](electron/main/three-ws-account.ts), [api/routers/settings.py](api/routers/settings.py)).
+- **Publish.** The Publish button on the Generate toolbar uploads the open model to your account as a three.ws page, with a name, tags and visibility ([src/areas/generate/components/PublishPopover.tsx](src/areas/generate/components/PublishPopover.tsx)).
+- **Library.** Import, then three.ws library: search the [CC0 object library](https://three.ws/objects) and open a model in the viewport ([src/areas/generate/components/ThreeWsLibraryPopover.tsx](src/areas/generate/components/ThreeWsLibraryPopover.tsx)).
+- **Cloud nodes.** The bundled three.ws extensions add image, text and sketch to 3D, rigging, remeshing and a Publish node that run on three.ws GPUs.
+- **Releases.** Builds publish to `https://three.ws/releases/forge/` through [cloudbuild.yaml](cloudbuild.yaml) and [scripts/release-mac.sh](scripts/release-mac.sh); the in-app updater reads the same feed. Release history lives in [releases.json](releases.json).
+
+---
## Getting started
@@ -43,16 +57,14 @@ launch.bat
npm install
```
-### 2. Set up Python backend
+### 2. Stage the bundled Python
```bash
-cd api
-python -m venv .venv
-.venv\Scripts\activate # Windows
-source .venv/bin/activate # Linux / macOS
-pip install -r requirements.txt
+npm run prepare-resources
```
+This downloads a standalone Python for your platform into `resources/python-embed/`. On first launch the app builds its virtual environment from it and installs `api/requirements.txt`, so Forge never depends on the Python your system ships (Debian and Ubuntu leave out `ensurepip`, which breaks `python -m venv`).
+
### 3. Run in development
```bash
@@ -315,14 +327,14 @@ See `tools/forge-cli/SKILL.md` for the agent workflow and output contract.
### Community
-Join the [Discord server](https://discord.gg/BvjDCvS3yr) to stay up to date with the latest news, report bugs, and share feedback.
+Report three.ws Forge bugs in the [three.ws repository](https://github.com/nirholas/three.ws/issues). For the upstream Modly app, its extensions and model support, join the [Modly Discord server](https://discord.gg/BvjDCvS3yr).
---
-## Sponsors
+## Modly sponsors
<p align="center">
- Thanks to our early sponsors for believing in three.ws Forge and helping make local AI 3D generation more accessible.
+ three.ws Forge is built on Modly. Thanks to Modly's early sponsors for believing in it and helping make local AI 3D generation more accessible.
</p>
<p align="center">
@@ -353,6 +365,8 @@ MIT License: see [LICENSE](LICENSE) for details.
**If you fork this project and build your own app from it, you must credit the original project and its creator:**
-> Based on [three.ws Forge](https://github.com/lightningpixel/modly) by [Lightning Pixel](https://github.com/lightningpixel)
+> Based on [Modly](https://github.com/lightningpixel/modly) by [Lightning Pixel](https://github.com/lightningpixel)
+
+three.ws Forge keeps this credit in its About screen, on [three.ws/forge-desktop](https://three.ws/forge-desktop) and in [NOTICE](NOTICE). three.ws is not affiliated with Lightning Pixel.
This is a requirement of the MIT license attribution clause. Please keep this credit visible in your app's UI or documentation.
diff --git a/apps/forge-desktop/docs/app-screenshot.png b/apps/forge-desktop/docs/app-screenshot.png
index c59c1320b..7603745ce 100644
Binary files a/apps/forge-desktop/docs/app-screenshot.png and b/apps/forge-desktop/docs/app-screenshot.png differ
diff --git a/apps/forge-desktop/docs/forge-library.png b/apps/forge-desktop/docs/forge-library.png
new file mode 100644
index 000000000..b84be21c4
Binary files /dev/null and b/apps/forge-desktop/docs/forge-library.png differ
diff --git a/apps/forge-desktop/docs/forge-publish.png b/apps/forge-desktop/docs/forge-publish.png
new file mode 100644
index 000000000..ab2561da9
Binary files /dev/null and b/apps/forge-desktop/docs/forge-publish.png differ
diff --git a/apps/forge-desktop/docs/forge-settings.png b/apps/forge-desktop/docs/forge-settings.png
new file mode 100644
index 000000000..ce5bd936e
Binary files /dev/null and b/apps/forge-desktop/docs/forge-settings.png differ
diff --git a/data/changelog.json b/data/changelog.json
index 6845d9f9b..91ac3ae07 100644
--- a/data/changelog.json
+++ b/data/changelog.json
@@ -1,6 +1,13 @@
{
"$comment": "Curated changelog entries for three.ws, the editorial layer of the public changelog. New PAGE launches are tracked automatically via the `added` field in data/pages.json; this file is for everything else holders care about: improvements, fixes, SDK releases, trading/payments capabilities, security work. scripts/build-page-index.mjs merges both sources into CHANGELOG.md, public/changelog.json, and public/changelog.xml. Newest first. Allowed tags: feature, improvement, fix, sdk, infra, docs, security, desktop (desktop entries become the desktop app's release notes). `link` is optional and must be a live three.ws path.",
"entries": [
+ {
+ "date": "2026-10-09",
+ "title": "three.ws Forge for desktop",
+ "summary": "A free desktop 3D studio for Windows, Linux and Apple silicon Macs, built on the open-source Modly app by Lightning Pixel. Turn a photo into a 3D model on your own graphics card or on the three.ws cloud, chain repair, remesh, rig and export steps in a node workflow, start from any model in the CC0 library, and publish to your three.ws account in one click after signing in with your browser. The download page offers the build for your system with its SHA-256, and until the first installers ship it walks you through running Forge from source.",
+ "tags": ["feature"],
+ "link": "/forge-desktop"
+ },
{
"date": "2026-10-09",
"title": "Claim the 3D models the bot made for you on X",
diff --git a/data/pages.json b/data/pages.json
index 068ad6127..60968b6c0 100644
--- a/data/pages.json
+++ b/data/pages.json
@@ -3472,6 +3472,14 @@
"changefreq": "monthly",
"added": "2026-07-18"
},
+ {
+ "path": "/docs/forge-desktop",
+ "title": "Docs · three.ws Forge for desktop",
+ "description": "How to install and use three.ws Forge, the desktop 3D studio: run it from source or an installer, generate on your own GPU or the three.ws cloud, build node workflows, import CC0 models, sign in and publish to three.ws, and fix common setup problems.",
+ "priority": 0.6,
+ "changefreq": "monthly",
+ "added": "2026-10-09"
+ },
{
"path": "/docs/materialize",
"title": "Docs · Materialize: turn a generation into a real object",
diff --git a/docs/forge-desktop.md b/docs/forge-desktop.md
new file mode 100644
index 000000000..d64b36c70
--- /dev/null
+++ b/docs/forge-desktop.md
@@ -0,0 +1,137 @@
+# three.ws Forge for desktop
+
+three.ws Forge is a free desktop 3D studio for Windows, Linux and Apple silicon
+Macs. It turns a photo into a 3D model with open-source generators running on
+your own graphics card, or with the three.ws cloud when you have no GPU. It
+chains mesh tools in a visual node workflow, imports free CC0 models from the
+three.ws library, and publishes the result to your three.ws account in one
+click.
+
+It is based on [Modly](https://github.com/lightningpixel/modly) by
+[Lightning Pixel](https://github.com/lightningpixel), used under the MIT
+license. The source lives in [`apps/forge-desktop/`](../apps/forge-desktop/README.md).
+
+Download page: [three.ws/forge-desktop](https://three.ws/forge-desktop).
+
+## Get it
+
+[three.ws/forge-desktop](https://three.ws/forge-desktop) offers the build for
+your operating system, every other build with its size and SHA-256, and the
+release notes. Until the first signed installers ship, the page leads with
+running from source, which takes five commands:
+
+```bash
+git clone --depth 1 https://github.com/nirholas/three.ws
+cd three.ws/apps/forge-desktop
+npm install
+npm run prepare-resources
+npm run dev
+```
+
+You need Node.js 20 or later and Git. `prepare-resources` downloads a
+standalone Python for your platform, so Forge never depends on the one your
+system ships (Debian and Ubuntu leave out `ensurepip`, which breaks
+`python -m venv`).
+
+**First launch.** Forge asks where to keep its data (models, workflows, the
+Python environment), then builds its Python environment and starts its local
+engine on `127.0.0.1:8765`. That takes a few minutes once; later launches start
+in seconds.
+
+**Unsigned builds.** If a download on the page is marked *unsigned*, your OS
+warns the first time you open it. On macOS, open System Settings, then Privacy
+& Security, and choose **Open Anyway**. On Windows, choose **More info**, then
+**Run anyway** in SmartScreen. Compare the SHA-256 on the page with
+`shasum -a 256 <file>` (macOS), `Get-FileHash <file>` (PowerShell) or
+`sha256sum <file>` (Linux) first.
+
+## Generate
+
+The **Generate** screen takes an image (drop it on the panel or pick a file) and
+runs the selected workflow. Two kinds of generator are available:
+
+- **On your GPU.** Install Hunyuan3D, TripoSG, TRELLIS or another model from the
+ **Models** tab (any GitHub repository with a Modly-compatible `manifest.json`
+ works too) and run it locally with no queue and no upload. NVIDIA GPUs use
+ CUDA, AMD Radeon GPUs use ROCm on Windows and Linux, and Apple silicon uses
+ Metal. Each model lists its VRAM needs.
+- **On the three.ws cloud.** The built-in three.ws nodes generate from a photo,
+ a text prompt or a sketch on three.ws GPUs, and add auto-rigging and
+ remeshing. They work on any laptop.
+
+The finished model opens in the viewport. The toolbar has **Import** (a file
+from disk, or the three.ws library), **Export** (GLB, OBJ, STL, PLY),
+**Publish**, **Smooth** and **Decimate**.
+
+## Node workflows
+
+The **Workflows** tab is a visual graph editor. Connect an image input to a
+generator, then to repair, remeshing, smoothing, optimization, auto-rigging or
+export nodes, save the workflow, and run it again on the next image from the
+Generate screen. Graphs are validated before a run: a broken wire shows inline
+instead of discarding the current model.
+
+## The three.ws library
+
+**Import, then three.ws library** opens the [CC0 object library](https://three.ws/objects):
+hundreds of public-domain models you may use, remix and sell. Search by name
+(chairs, trees, cars), click a thumbnail, and the model downloads and opens in
+the viewport as a starting point, a reference or a workflow input. No account
+is needed.
+
+## Your three.ws account
+
+**Settings, then three.ws** connects Forge to your account. There are two ways:
+
+- **Sign in with your browser** (recommended). Forge shows a short code and
+ opens [three.ws](https://three.ws) to approve it, the same device flow as the
+ three.ws CLI. When you approve, Forge receives a key scoped to this device.
+- **Paste an API key** for managed machines or CI. Create one at
+ [three.ws/dashboard/developers](https://three.ws/dashboard/developers); it
+ starts with `sk_live_` and needs the `avatars:write` scope to publish.
+
+The key is encrypted with the operating system's secure storage (Keychain on
+macOS, DPAPI on Windows, the desktop keyring on Linux) through Electron's
+`safeStorage`, and the screen only ever shows who is signed in. On a Linux
+machine with no keyring at all, Forge logs a warning and keeps the key
+unencrypted in its settings file, so prefer a keyring there. **Sign out**
+deletes it. The three.ws workflow nodes read the same key, so they are signed
+in as soon as the app is.
+
+## Publish
+
+**Publish** sends the model in the viewport to your account as a shareable 3D
+page (`three.ws/avatars/<id>`) you can embed, rig or give to an agent. Give it
+a name and tags, choose who can see it (private, unlisted or public), and Forge
+uploads the GLB. When it is done, the popover links to the new page and copies
+its URL in a click. If you are not signed in, the popover offers sign-in
+first.
+
+## Command line and agents
+
+A running Forge can be driven without the UI through the stdlib-only CLI in
+[`apps/forge-desktop/tools/forge-cli/`](../apps/forge-desktop/tools/forge-cli/SKILL.md):
+
+```bash
+python apps/forge-desktop/tools/forge-cli/agent.py health
+python apps/forge-desktop/tools/forge-cli/agent.py generate --image ./input.png --output ./export.glb
+```
+
+## Troubleshooting
+
+| You see | Do this |
+|---|---|
+| First-run setup stops at "Creating Python environment" | Run `npm run prepare-resources` in `apps/forge-desktop`, then relaunch. It stages a Python that includes `ensurepip`. |
+| "Could not reach three.ws" in Settings | Check your connection and press **Retry**. A rejected API key shows **Dismiss** instead: create a new key and paste it again. |
+| The library lists models but shows no thumbnails, or a model will not open | Your network blocks `*.r2.dev`, where the library's models and previews are hosted. Allow it, or download the model from [three.ws/objects](https://three.ws/objects) on another network and open it with **Import**. |
+| A local model runs out of memory | Pick a smaller variant in the Models tab (Mini or Turbo), or use the three.ws cloud nodes. |
+| Something else failed | **Settings, then Logs** shows the Errors, Runtime (the Python engine) and App logs for this session and earlier ones, with a Copy button for bug reports. |
+
+## Related
+
+- [/forge-desktop](https://three.ws/forge-desktop): the download page.
+- [Modly and three.ws](./modly.md): every way three.ws and Modly work together,
+ including the three.ws nodes for an unmodified Modly.
+- [Forge](./forge.md): generating 3D in the browser on three.ws servers.
+- [Workbench](./workbench.md): the same kind of node workflow in a browser tab.
+- Maintainers cut releases with the runbook at `docs/ops/forge-desktop-release.md` in the repository (operator docs are not published on the site).
diff --git a/docs/nav.json b/docs/nav.json
index 52666fd61..6f129317e 100644
--- a/docs/nav.json
+++ b/docs/nav.json
@@ -177,6 +177,10 @@
"label": "Modly (your own GPU)",
"path": "modly"
},
+ {
+ "label": "three.ws Forge for desktop",
+ "path": "forge-desktop"
+ },
{
"label": "Scene Studio",
"path": "scene-studio"
diff --git a/docs/ops/README.md b/docs/ops/README.md
index 7b5468f0d..4c725f525 100644
--- a/docs/ops/README.md
+++ b/docs/ops/README.md
@@ -16,6 +16,7 @@ Start with [gcp-production.md](gcp-production.md); it is the complete operationa
| [production-log-triage.md](production-log-triage.md) | Known error/warning signature map: what each recurring log signature means and the fix. |
| [forge-error-triage.md](forge-error-triage.md) | `npm run forge:errors`: which 3D generation failures actually recur, ranked by class and lane over a real window. |
| [forge-funnel.md](forge-funnel.md) | The Forge funnel board (`GET /api/ops/forge-funnel`, `npm run forge:funnel`): useful-output rate, first and second asset rates, retention, what each model was for, attempts per kept model by engine, and x402 revenue per kept model. |
+| [forge-desktop-release.md](forge-desktop-release.md) | Cutting a three.ws Forge desktop release: version and notes, the Cloud Build Linux and Windows build, the Mac build, signing secrets, publish order, verification and rollback of the `/releases/forge/` feed. |
| [cron-auth.md](cron-auth.md) | The two locks on `/api/cron/*`: the handler gate, the edge gate, and the header trap that makes attaching Cloud Scheduler OIDC take the whole fleet down if done naively. |
| [materialize-fulfillment.md](materialize-fulfillment.md) | Running physical print fulfillment: the operator console, its authorization doors, the adapter contract for wiring a partner, webhook idempotency, and the stall sweep. |
| [payment-outcomes.md](payment-outcomes.md) | The payment-outcome board (`GET /api/ops/payment-outcomes`): verify-reject, settle-fail, replay, and sponsor-runway signals and how to read them in an incident. |
diff --git a/docs/ops/forge-desktop-release.md b/docs/ops/forge-desktop-release.md
new file mode 100644
index 000000000..701846cfc
--- /dev/null
+++ b/docs/ops/forge-desktop-release.md
@@ -0,0 +1,116 @@
+# 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](https://three.ws/forge-desktop) and to the
+in-app updater. User guide: [docs/forge-desktop.md](../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`](../../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`](../../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`](../../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`](../../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`](../../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`](../../pages/forge-desktop.html), [`src/forge-desktop.js`](../../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`](../../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.
+
+```bash
+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
+
+1. Bump `version` in `apps/forge-desktop/package.json`.
+2. Add the matching entry at the top of `apps/forge-desktop/releases.json`
+ (version, date, notes with `title`, `summary`, `tags`). The notes are what
+ the download page shows, so write them for users.
+3. Commit both.
+
+## Build Linux and Windows
+
+From the repo root:
+
+```bash
+# 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
+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:
+
+1. Binaries, under versioned names, cached for a year (`immutable`).
+2. `versions/<version>.json`, a permanent copy of this release's manifest.
+3. `release.json` and the `latest*.yml` updater feeds, uncached.
+
+## Verify
+
+```bash
+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](https://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:
+
+```bash
+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.
diff --git a/docs/start-here.md b/docs/start-here.md
index d1d5eaa14..4669d2e2c 100644
--- a/docs/start-here.md
+++ b/docs/start-here.md
@@ -66,7 +66,7 @@ Generations don't need a babysitter, either: start a forge job, close the tab, a
Want to choose the steps yourself? [Workbench](./workbench.md) runs a photo through a visual workflow you can edit (background removal, generation, remeshing, rigging, material restyle), then lets you smooth, decimate and export GLB, OBJ, STL or PLY from a desktop-style viewport.
-Have a graphics card? [Modly and three.ws](./modly.md) covers generating on your own GPU through the free Modly app (from [/modly](https://three.ws/modly) or the Forge's **Use your GPU** panel), plus the three.ws nodes for Modly that bring cloud generation, auto-rigging, remeshing and publishing into Modly itself.
+Have a graphics card? [Modly and three.ws](./modly.md) covers generating on your own GPU through the free Modly app (from [/modly](https://three.ws/modly) or the Forge's **Use your GPU** panel), plus the three.ws nodes for Modly that bring cloud generation, auto-rigging, remeshing and publishing into Modly itself. Prefer a desktop app? [three.ws Forge for desktop](./forge-desktop.md) is a full 3D studio for Windows, Linux and Apple silicon Macs with local and cloud generation, node workflows, the CC0 library and one-click publishing ([download](https://three.ws/forge-desktop)).
Curious what happens between the prompt and the model? [How the Forge works](./how-forge-works.md) tells the story in plain language; [the Forge pipeline](./forge-pipeline.md) is the full engineering deep dive.