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(ipfs): document the filebase, 4everland, pinata gateway ladder that replaced the rate-limited public gateways, with a regression test for the rewrite
nirholas70038dead66b
diff --git a/docs/agent-manifest.md b/docs/agent-manifest.mdindex fbf0b1fcc..f8d9153d3 100644--- a/docs/agent-manifest.md+++ b/docs/agent-manifest.md@@ -320,7 +320,7 @@ Each element must be an object with a `uri` field:Three URI forms:- **Relative** (`skills/wave/`) — bundled in the manifest directory.-- **IPFS** (`ipfs://bafy.../`), resolved via the IPFS gateway cascade (dweb.link, then ipfs.io, then flk-ipfs.xyz).+- **IPFS** (`ipfs://bafy.../`), resolved via the IPFS gateway cascade (ipfs.filebase.io, then 4everland.io, then gateway.pinata.cloud).- **HTTPS** (`https://skills.3d-agent.io/...`) — centrally hosted.The `version` field is metadata; the runtime uses it for display and conflict detection but does not enforce semver constraints at load time.@@ -457,11 +457,11 @@ ISO 8601 timestamps. Informational; not validated by the runtime.`ipfs://` URIs are resolved to HTTPS gateway URLs. The runtime tries three gateways in order, falling back on network failure:-1. `https://dweb.link/ipfs/<CID>`-2. `https://ipfs.io/ipfs/<CID>`-3. `https://flk-ipfs.xyz/ipfs/<CID>`+1. `https://ipfs.filebase.io/ipfs/<CID>`+2. `https://4everland.io/ipfs/<CID>`+3. `https://gateway.pinata.cloud/ipfs/<CID>`-Cloudflare retired its public IPFS gateways (cf-ipfs.com, cloudflare-ipfs.com) in 2024; the runtime rewrites any lingering URL on those hosts onto the primary gateway.+Some public gateways no longer serve programmatic reads. Cloudflare retired cf-ipfs.com and cloudflare-ipfs.com in 2024, flk-ipfs.xyz no longer resolves, and since October 2026 ipfs.io, dweb.link, w3s.link and nftstorage.link answer script and image requests with HTTP 429 and a pointer to a service-worker gateway. The runtime rewrites any URL on those hosts onto the primary gateway, so a manifest that hardcodes one of them still loads. The list lives in [src/ipfs.js](../src/ipfs.js) (`IPFS_GATEWAYS`) and the server-side copy in [api/_lib/ipfs-pin.js](../api/_lib/ipfs-pin.js) (`IPFS_READ_GATEWAYS`).### Arweave@@ -496,13 +496,13 @@ Same rule applies on IPFS: the gateway URL of the manifest's directory is used a→ "ipfs://bafy.../manifest.json"│▼- resolveURI() → https://dweb.link/ipfs/bafy.../manifest.json+ resolveURI() → https://ipfs.filebase.io/ipfs/bafy.../manifest.json│▼- fetchWithFallback() (dweb.link → ipfs.io → flk-ipfs.xyz)+ fetchWithFallback() (filebase → 4everland → pinata)│▼- normalize(json, { baseURI: "https://dweb.link/ipfs/bafy.../" })+ normalize(json, { baseURI: "https://ipfs.filebase.io/ipfs/bafy.../" })│├── load body.glb → Viewer├── load instructions.md → LLM runtimediff --git a/docs/api-reference.md b/docs/api-reference.mdindex d44de9ee8..e78d8c694 100644--- a/docs/api-reference.md+++ b/docs/api-reference.md@@ -414,7 +414,7 @@ The agent's full configuration, system prompt included, canonicalized, ed25519-s"issuer": "6Yb...","signed_at": "2026-08-11T12:00:00.000Z","verified": true,- "gatewayUrls": ["https://ipfs.io/ipfs/bafy..."],+ "gatewayUrls": ["https://ipfs.filebase.io/ipfs/bafy..."],"verifyUrl": "/api/manifest-verify?cid=bafy...","envelope": { "spec": "threews.agent.manifest.v1", "manifest": {} }}@@ -8113,9 +8113,8 @@ curl -X POST https://three.ws/api/pinning/pin \"cid": "QmYazpLPRXtuBsCQk64LpXohMxSGJa3RoQTx9fckJgPY9o","gatewayUrl": "https://ipfs.io/ipfs/QmYazpLPRXtuBsCQk64LpXohMxSGJa3RoQTx9fckJgPY9o","gatewayUrls": [- "https://ipfs.io/ipfs/QmYazpLPRXtuBsCQk64LpXohMxSGJa3RoQTx9fckJgPY9o",- "https://dweb.link/ipfs/QmYazpLPRXtuBsCQk64LpXohMxSGJa3RoQTx9fckJgPY9o",- "https://w3s.link/ipfs/QmYazpLPRXtuBsCQk64LpXohMxSGJa3RoQTx9fckJgPY9o",+ "https://ipfs.filebase.io/ipfs/QmYazpLPRXtuBsCQk64LpXohMxSGJa3RoQTx9fckJgPY9o",+ "https://4everland.io/ipfs/QmYazpLPRXtuBsCQk64LpXohMxSGJa3RoQTx9fckJgPY9o","https://gateway.pinata.cloud/ipfs/QmYazpLPRXtuBsCQk64LpXohMxSGJa3RoQTx9fckJgPY9o"],"provider": "pinata"@@ -8157,7 +8156,7 @@ curl "https://three.ws/api/pinning/status?cid=QmYazpLPRXtuBsCQk64LpXohMxSGJa3RoQ"pinned": true,"provider": "pinata","unreachableProviders": [],- "gatewayUrls": ["https://ipfs.io/ipfs/QmYazpLPRXtuBsCQk64LpXohMxSGJa3RoQTx9fckJgPY9o"]+ "gatewayUrls": ["https://ipfs.filebase.io/ipfs/QmYazpLPRXtuBsCQk64LpXohMxSGJa3RoQTx9fckJgPY9o"]}```diff --git a/docs/architecture.md b/docs/architecture.mdindex 49682429a..4cf137f37 100644--- a/docs/architecture.md+++ b/docs/architecture.md@@ -153,7 +153,7 @@ The manifest is a JSON document that fully describes an embodied agent. It's intKey fields:- **`name`, `description`, `creator`** — display metadata.-- **`body.uri`**: GLB / glTF / VRM URL. Resolution is deliberately polymorphic: `agent://chain/id` (resolved on-chain), `ipfs://CID/path`, `ar://TXID`, or plain `https://`. The resolver in `ipfs.js` walks gateway fallbacks (dweb.link → ipfs.io → flk-ipfs.xyz) so a single broken gateway never breaks an embed.+- **`body.uri`**: GLB / glTF / VRM URL. Resolution is deliberately polymorphic: `agent://chain/id` (resolved on-chain), `ipfs://CID/path`, `ar://TXID`, or plain `https://`. The resolver in `ipfs.js` walks gateway fallbacks (ipfs.filebase.io → 4everland.io → gateway.pinata.cloud) so a single broken gateway never breaks an embed.- **`skills[]`** — pointers to skill bundles. Each skill is loaded and validated by the registry. Trust mode determines whether unsigned/foreign skills are allowed.- **`memory.mode`**: `local`, `remote`, `ipfs`, `encrypted-ipfs`, or `none`.- **`identity.chainId` / `identity.registryAddress`** — pin this manifest to an on-chain agent id.diff --git a/docs/erc8004.md b/docs/erc8004.mdindex acad6781d..8503336c1 100644--- a/docs/erc8004.md+++ b/docs/erc8004.md@@ -372,8 +372,8 @@ const agent = await resolveOnchainAgent('/a/8453/42');// metadata: { ... full agent card ... },// name: 'Coach Leo',// description: '...',-// image: 'https://ipfs.io/ipfs/...',-// glbUrl: 'https://ipfs.io/ipfs/...',+// image: 'https://ipfs.filebase.io/ipfs/...',+// glbUrl: 'https://ipfs.filebase.io/ipfs/...',// services: [ ... ]// }```@@ -396,7 +396,7 @@ The `<agent-3d>` element boots the full agent runtime — 3D rendering, memory,### IPFS fallbacks-`resolveUrl(uri)` turns an `ipfs://` URI into a single URL on the primary gateway (`ipfs.io`). `resolveUrlCandidates(uri)` returns the full ordered chain for the same content, and it no longer keeps a gateway list of its own: it delegates to `uriCandidates()` in [src/ipfs.js](../src/ipfs.js), which owns the one live, dead-host-free list for the whole platform. Today that chain is `ipfs.io` (the primary, kept at the head), then `dweb.link`, `flk-ipfs.xyz`, `w3s.link`, and `nftstorage.link`. `uriCandidates()` also re-extracts the CID from a URL whose gateway was already baked in upstream, so a card that hardcodes one gateway is still rotatable.+`resolveUrl(uri)` turns an `ipfs://` URI into a single URL on the primary gateway (`ipfs.filebase.io`, the head of the shared list). `resolveUrlCandidates(uri)` returns the full ordered chain for the same content, and it no longer keeps a gateway list of its own: it delegates to `uriCandidates()` in [src/ipfs.js](../src/ipfs.js), which owns the one live, dead-host-free list for the whole platform. Today that chain is `ipfs.filebase.io` (the primary, kept at the head), then `4everland.io` and `gateway.pinata.cloud`. ipfs.io, dweb.link, w3s.link and nftstorage.link were dropped in October 2026 when they began answering programmatic reads with HTTP 429, and a URL already baked onto one of them is rewritten onto the primary. `uriCandidates()` also re-extracts the CID from a URL whose gateway was already baked in upstream, so a card that hardcodes one gateway is still rotatable.The manifest `toManifest(resolved)` builds keeps `image` and `body.uri` as single URLs (nothing that consumes them changes), and alongside them carries `_gatewayCandidates.body` and `_gatewayCandidates.image`: the ordered chain for each, starting with that same single URL. A consumer that can retry (an `<img>` fallback chain, a GLB loader) walks those instead of giving up on one dead gateway.@@ -421,7 +421,7 @@ GET /api/erc8004/metadata?uri=<registration uri><!-- runnable: no the CID is illustrative; substitute a real registration uri -->```shcurl -s 'https://three.ws/api/erc8004/metadata?uri=ipfs://bafyExampleAgentCard'-# → { "data": { ...the agent card... }, "resolvedUrl": "https://ipfs.io/ipfs/bafyExampleAgentCard" }+# → { "data": { ...the agent card... }, "resolvedUrl": "https://ipfs.filebase.io/ipfs/bafyExampleAgentCard" }```Public, keyless, and rate-limited per IP. `ipfs://` and `ar://` are resolved todiff --git a/docs/sdk.md b/docs/sdk.mdindex 27fcb9696..6544e2663 100644--- a/docs/sdk.md+++ b/docs/sdk.md@@ -129,12 +129,12 @@ import { resolveURI, fetchWithFallback } from './src/lib.js';// Resolve ipfs:// or ar:// to an HTTPS gateway URLconst url = resolveURI('ipfs://QmXyz...');-// → "https://dweb.link/ipfs/QmXyz..."+// → "https://ipfs.filebase.io/ipfs/QmXyz..."const url = resolveURI('ar://txId123');// → "https://arweave.net/txId123"-// Fetch with automatic gateway fallback (dweb.link → cloudflare-ipfs → ipfs.io)+// Fetch with automatic gateway fallback (filebase → 4everland → pinata)const res = await fetchWithFallback('ipfs://QmXyz...');const json = await res.json();```diff --git a/docs/skills.md b/docs/skills.mdindex a49e368f0..ab62cbd6f 100644--- a/docs/skills.md+++ b/docs/skills.md@@ -78,7 +78,7 @@ Reference skills by URI in the agent's `manifest.json`. The runtime fetches andThe URI points at any host serving the four-file bundle. The repo ships a copyable starter at `examples/skills/wave/` (the same bundle Coach Leo's manifest references); host it on your own site or pin it to IPFS and reference that URI.-URIs can be HTTPS, IPFS (`ipfs://`), or Arweave (`ar://`). IPFS URIs are resolved through a gateway fallback chain (dweb.link → ipfs.io → flk-ipfs.xyz, see `src/ipfs.js`).+URIs can be HTTPS, IPFS (`ipfs://`), or Arweave (`ar://`). IPFS URIs are resolved through a gateway fallback chain (ipfs.filebase.io → 4everland.io → gateway.pinata.cloud, see `src/ipfs.js`).### Via the web component attributediff --git a/tests/src/ipfs.test.js b/tests/src/ipfs.test.jsindex 841317991..ac2a89945 100644--- a/tests/src/ipfs.test.js+++ b/tests/src/ipfs.test.js@@ -100,8 +100,18 @@ describe('normalizeGatewayURL', () => {expect(out).toMatch(/\/ipfs\/QmCID$/);});+ // ipfs.io and its sibling hosts answer every programmatic read with 429 and+ // a pointer to a service-worker gateway, so they are retired like Cloudflare's.+ it('rewrites ipfs.io and dweb.link onto a working gateway', () => {+ for (const host of ['ipfs.io', 'dweb.link']) {+ const out = normalizeGatewayURL(`https://${host}/ipfs/QmCID/meta.json`);+ expect(out).not.toContain(host);+ expect(out).toMatch(/\/ipfs\/QmCID\/meta\.json$/);+ }+ });+it('leaves live gateways and arbitrary URLs untouched', () => {- expect(normalizeGatewayURL('https://ipfs.io/ipfs/QmCID')).toBe('https://ipfs.io/ipfs/QmCID');+ expect(normalizeGatewayURL('https://4everland.io/ipfs/QmCID')).toBe('https://4everland.io/ipfs/QmCID');expect(normalizeGatewayURL('https://example.com/x.png')).toBe('https://example.com/x.png');});