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: re-measure the R2 CORS claims, unchanged as of 2026-09-09

nirholas5d6c732f58d7
diff --git a/docs/character-library.md b/docs/character-library.md
index 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 pipel
3. `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.
## Related
diff --git a/docs/media-api.md b/docs/media-api.md
index 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 not
It 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.md
index 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.md
index 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. Load
Two 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: