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(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.md
index 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 runtime
diff --git a/docs/api-reference.md b/docs/api-reference.md
index 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.md
index 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 int
Key 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.md
index 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 -->
```sh
curl -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 to
diff --git a/docs/sdk.md b/docs/sdk.md
index 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 URL
const 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.md
index 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 and
The 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 attribute
diff --git a/tests/src/ipfs.test.js b/tests/src/ipfs.test.js
index 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');
});