User-Preferred Gateway Detection

2.1 IPFS_GATEWAY Environment Variable

When the IPFS_GATEWAY environment variable is set, the value SHOULD be interpreted as the URL of the IPFS Gateway to use. The value holds a single URL, following the same rules as the first line of the gateway file.

Applications SHOULD give this variable precedence over gateway URLs from internal application configuration. Explicit per-invocation user input, such as a command-line argument, MAY take precedence over this variable.

2.2 The gateway Configuration File

Client application SHOULD check if file is present at specific filesystem paths, in order:

1. If IPFS_PATH is set, try $IPFS_PATH/gateway
2. Otherwise, if HOME is set, try $HOME/.ipfs/gateway (the default IPFS_PATH location)
3. Try OS-specific paths:
   • Linux/Unix:
     1. $XDG_CONFIG_HOME/ipfs/gateway (only if XDG_CONFIG_HOME is set)
     2. $HOME/.config/ipfs/gateway (default XDG location)
     3. /etc/ipfs/gateway (system-wide)
   • Windows:
     1. %LOCALAPPDATA%/ipfs/gateway (local user)
     2. %APPDATA%/ipfs/gateway (roaming user)
     3. %PROGRAMDATA%/ipfs/gateway (system-wide)
   • macOS:
     1. $HOME/Library/Application Support/ipfs/gateway (user)
     2. /Library/Application Support/ipfs/gateway (system-wide)

When gateway file is present, the file contents MUST be interpreted as an ASCII text file with one URL per line (separated by \n or \r\n).

The first line MUST be a valid http:// or https:// URL consisting only of a scheme, host, and optional port, with no path, query, or fragment (e.g., http://127.0.0.1:8080). The gateway at this URL MUST support [trustless-gateway], SHOULD support [path-gateway] when deserialized responses are required, and SHOULD support [subdomain-gateway] when Origin isolation is required.

Implementations MAY support additional lines for gateway pools or failover. Additional lines, when present, MUST follow the same URL rules, and empty lines MUST be ignored. Implementations that do not support multiple URLs SHOULD read only the first line and ignore the rest of the file.

2.3 Security

Applications that integrate IPFS support via HTTP gateways:

• SHOULD NOT hard-code a non-localhost URL as a default fallback. Instead, they SHOULD ask the user to define a preferred IPFS gateway using one of the methods defined in this document.
• SHOULD either warn the user when a non-localhost gateway is used for deserialized responses (risk of MITM), or (preferred) limit HTTP use outside of localhost to verifiable response types defined in [trustless-gateway].
• When running in a web browser, SHOULD use a gateway URL that qualifies as a secure context: either https://, or localhost (e.g., http://127.0.0.1:8080), which browsers treat as potentially trustworthy.
• When Origin isolation is required, SHOULD use a [subdomain-gateway] (e.g., http://{cid}.ipfs.localhost:8080), so each content root is loaded from its own origin.

2.4 Privacy and User Control

Applications SHOULD NOT default to public gateways (see Security above). Instead, applications SHOULD suggest to the user how to run a local node.

2.5 Compatibility and Testing

Implementers SHOULD test against implementations mentioned in ipip-0280 as the baseline for making decisions around maximizing interoperability.