| title | IPIP-0280: Conventions for HTTP Gateway Detection | ||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| date | 2025-12-16 | ||||||||||||||||||
| ipip | ratified | ||||||||||||||||||
| editors |
|
||||||||||||||||||
| relatedIssues | |||||||||||||||||||
| order | 280 | ||||||||||||||||||
| tags |
|
This IPIP creates conventions for how applications can identify available IPFS gateway, and how IPFS gateway implementations can signal own endpoint.
This convention has been implemented and in use since 2022 (Kubo 0.15, ffmpeg, curl 8.4).
Applications wanting to leverage IPFS Gateways are, without a common convention, left to invent their own ways of finding a gateway, including naive approaches such as localhost port scanning.
This IPIP introduces specification that defines how an application wanting to implement IPFS support can find a local or user-preferred gateways.
We introduce two ways of hinting user-preferred gateway URL to cover the majority of runtimes and use cases:
IPFS_GATEWAYenvironment variablegatewayfile and filesystem paths to look for it
See: :cite[gateway-detection] for details.
End users can define their preferred gateway once, and benefit from opportunistic support in applications they use.
Application developers save time as they only need to implement support for vendor-agnostic convention to be able to read user preferred gateway.
Kubo (>0.15.0)
creates a hint file in $IPFS_PATH/gateway (default being $HOME/.ipfs/gateway, see kubo#8847).
The file contains a single line being the local HTTP gateway URL. For example: http://localhost:8080.
Every time ipfs daemon starts, it updates the the content of $IPFS_PATH/gateway or creates the file if it doesn't exist.
ipfs-chromium uses IPFS_GATEWAY environment variable
(ipfs-chrompium#29).
It can be a single URL, or a whitespace-separated URLs to be used as the initial gateway pool.
Ref. https://blog.ipfs.tech/2023-05-multigateway-chromium-client/
FFMPEG's libavformat supports both $HOME/.ipfs/gateway file and IPFS_GATEWAY environment variable
(ffmpeg.git/commit/f889837).
Ref. https://ffmpeg.org/ffmpeg-protocols.html#ipfs, https://blog.ipfs.tech/2022-08-01-ipfs-and-ffmpeg/
Curl (>8.4.0, curl#8805)
will try the IPFS_GATEWAY environment variable first, and then look for
$IPFS_PATH/gateway or $HOME/.ipfs/gateway, if present.
It expects a single URL.
Ref. https://curl.se/docs/ipfs.html
See "Security" section of :cite[gateway-detection].
Detection via browser APIs (e.g., localStorage.getItem('IPFS_GATEWAY')) was
considered but is explicitly out of scope. Any JavaScript running on a page
could overwrite such values and hijack gateway requests. Browser-based detection
requires a separate IPIP with proper security review.
This specification does not mandate health checking of detected gateways. Implementations MAY verify that a gateway is responsive before using it, but the specific approach is left to implementers.
If a daemon crashes without removing the gateway file, it may contain a stale
URL. This specification does not mandate specific handling. Implementations MAY
implement timeout-based health checks or other recovery mechanisms.
Copyright and related rights waived via CC0.