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.
JavaScript 3d-generationai-agentsanimationavatardigital-humangenerative-aiglbgltfimage-to-3dllmmcpmcp-servermodel-context-protocolsolanatext-to-3dthreejsweb-componentswebglwebxrx402
docs: re-measure the R2 CORS claims, unchanged as of 2026-09-09
nirholas5d6c732f58d7
diff --git a/docs/character-library.md b/docs/character-library.mdindex 319b85be3..673913cdb 100644--- a/docs/character-library.md+++ b/docs/character-library.md@@ -109,7 +109,7 @@ The gallery and API are read-only consumers of a manifest built by a local pipel3. `scripts/fetch-mixamo-avatar-thumbnails.mjs` stages the PNG thumbnails.4. `scripts/build-mixamo-avatar-library.mjs` reads `public/avatars/mixamo/catalog.json`, merges the extra CC0 characters from `public/avatars/extra/characters.json`, and PUTs `avatars/library/manifest.json` to R2 (`--dry-run` prints without uploading).-R2 CORS is configured by `scripts/set-r2-cors.mjs` so browsers can GET the GLBs cross-origin. The live bucket policy is an origin allowlist (`three.ws`, `*.vercel.app`, `localhost:3000`) that predates the world-open read rule now in that script, so a GLB loaded straight from the bucket host on any other origin fails with no `access-control-allow-origin` header (re-measured 2026-09-04). Measure the live policy yourself with `node scripts/set-r2-cors.mjs --probe`, which needs no credentials. Until the bucket is corrected, embeds on third-party origins should load the GLB from a first-party path instead: [`/cdn/<key>`](./media-api.md#how-bucket-objects-are-served-cdnkey) when you have the object key, or [`/api/glb`](./media-api.md#same-origin-glb-proxy) when all you have is the manifest URL, as [the embed tutorial](./tutorials/character-library-to-embed.md) does.+R2 CORS is configured by `scripts/set-r2-cors.mjs` so browsers can GET the GLBs cross-origin. The live bucket policy is an origin allowlist (`three.ws`, `*.vercel.app`, `localhost:3000`) that predates the world-open read rule now in that script, so a GLB loaded straight from the bucket host on any other origin fails with no `access-control-allow-origin` header (re-measured 2026-09-09). Measure the live policy yourself with `node scripts/set-r2-cors.mjs --probe`, which needs no credentials. Until the bucket is corrected, embeds on third-party origins should load the GLB from a first-party path instead: [`/cdn/<key>`](./media-api.md#how-bucket-objects-are-served-cdnkey) when you have the object key, or [`/api/glb`](./media-api.md#same-origin-glb-proxy) when all you have is the manifest URL, as [the embed tutorial](./tutorials/character-library-to-embed.md) does.## Relateddiff --git a/docs/media-api.md b/docs/media-api.mdindex e02c06a08..35e6a9927 100644--- a/docs/media-api.md+++ b/docs/media-api.md@@ -354,7 +354,7 @@ If `draco=1` comes back `500 transcode_failed` with `draco.createCompressedPrimi### When you need it, and when you do notIt depends entirely on which host serves the `.glb`, not on which origin you-are loading from. Re-measured 2026-09-04, unchanged since 2026-08-01:+are loading from. Re-measured 2026-09-09, unchanged since 2026-08-01:| Source host | Cross-origin fetch | Use the proxy? ||---|---|---|diff --git a/docs/tutorials/character-library-to-embed.md b/docs/tutorials/character-library-to-embed.mdindex ee9adf5ef..db5a06048 100644--- a/docs/tutorials/character-library-to-embed.md+++ b/docs/tutorials/character-library-to-embed.md@@ -317,7 +317,7 @@ Then use that URL in the element:Safe by construction: the upstream objects are already public and keyless, and the proxy fetch runs through an SSRF-hardened client (scheme allowlist, DNS pinning, private-address blocklist, redirect re-validation, 30 MB cap, 20 second timeout). It is a CORS shim, not an open proxy. The response is cached immutably, so the proxy costs one hop on a cold cache and nothing after.-One exception worth knowing, so you do not reach for the proxy reflexively: this applies to the `pub-*.r2.dev` bucket host, which is where every manifest GLB lives. Files served from `three.ws` itself (`https://three.ws/avatars/cesium-man.glb` and the rest of the built-in set) already answer every origin with `access-control-allow-origin: *`, re-measured 2026-09-04. So does `https://three.ws/cdn/<key>`, which serves the very same bucket objects first-party. Those load directly, no proxy. Check the host in the URL, not the symptom.+One exception worth knowing, so you do not reach for the proxy reflexively: this applies to the `pub-*.r2.dev` bucket host, which is where every manifest GLB lives. Files served from `three.ws` itself (`https://three.ws/avatars/cesium-man.glb` and the rest of the built-in set) already answer every origin with `access-control-allow-origin: *`, re-measured 2026-09-09. So does `https://three.ws/cdn/<key>`, which serves the very same bucket objects first-party. Those load directly, no proxy. Check the host in the URL, not the symptom.Use the proxied URL from the start and you never have a localhost-only success to unlearn. The same shim is what makes these GLBs loadable in a Jupyter or Colab notebook and on a dev server running on a non-standard port.diff --git a/docs/tutorials/render-avatar-images.md b/docs/tutorials/render-avatar-images.mdindex b09397b80..31d71be45 100644--- a/docs/tutorials/render-avatar-images.md+++ b/docs/tutorials/render-avatar-images.md@@ -455,7 +455,7 @@ Sometimes an image is not enough and you want the actual interactive model. LoadTwo hosts, two answers (measured 2026-08-01):- **`https://three.ws/...`**, which is where the built-in library avatars live (`/avatars/selfie-girl.glb` and friends), answers every origin with `access-control-allow-origin: *`. Load these directly. No proxy needed.-- **`https://pub-*.r2.dev/...`**, the media bucket's own host, behind every avatar you or your users generated, answers only origins on its allowlist (`three.ws`, `*.vercel.app`, `localhost:3000`; re-measured 2026-09-04). From `https://your-site.com`, from Jupyter, or from a Vite server on `localhost:5173`, a direct load fails with a CORS error and an empty canvas. That is the URL `/api/avatar/render` redirects to and the URL the avatar APIs return for user avatars.+- **`https://pub-*.r2.dev/...`**, the media bucket's own host, behind every avatar you or your users generated, answers only origins on its allowlist (`three.ws`, `*.vercel.app`, `localhost:3000`; re-measured 2026-09-09). From `https://your-site.com`, from Jupyter, or from a Vite server on `localhost:5173`, a direct load fails with a CORS error and an empty canvas. That is the URL `/api/avatar/render` redirects to and the URL the avatar APIs return for user avatars.- **`https://three.ws/cdn/<key>`** serves those same bucket objects first-party, with `access-control-allow-origin: *` on every origin. If you have the object key (everything after the bucket host), this loads directly and needs nothing below.`GET /api/glb?src=<url>` exists for the second case. It streams any public GLB back with `access-control-allow-origin: *`, and it is harmless on the first, so if you cannot tell which host a URL points at, use it. The example below proxies a `three.ws` URL that would also load directly, because it is the pattern that keeps working when you swap in a generated avatar: