Whitelist network access in Sage

Whitelist every external host

Put hosts the app may use on every Chia network under permissions.network.whitelist. This includes your own API, RPC services, WebSocket servers, analytics, third-party SDK endpoints, and remote images requested at runtime.

Declare an origin, not a complete URL: scheme, host, and an optional port. Do not include a path, query, or fragment. If a request redirects to a different host, that destination also needs to be allowed.

{
  "permissions": {
    "network": {
      "whitelist": {
        "required": [
          "https://api.example.com",
          "wss://events.example.com"
        ]
      }
    }
  }
}

Use HTTPS and secure WebSockets only

Sage accepts only https and wss network entries. An https entry covers secure HTTP requests such as fetch(). A wss entry covers secure WebSocket connections. Plain http and ws entries are rejected, including for local services.

Granting wss access also grants https access for the same host. If an app uses both a secure WebSocket and HTTPS endpoints on that domain, declare the wss origin rather than listing both. The host includes an explicit port when one is present, so different ports are separate targets.

• Use https://api.example.com for HTTPS only
• Use wss://api.example.com when the same host needs WSS and HTTPS
• Include :port when the service does not use its protocol’s default port

Scope services to the selected Chia network

Use permissions.network.whitelistByNetwork when a host should be reachable only while a particular Chia network is selected. Sage currently accepts the network IDs mainnet and testnet11.

The effective whitelist combines the shared whitelist entries with the entries for the active network. In the example below, status.example.com is always reachable, while only the matching mainnet or testnet API is reachable at one time.

{
  "permissions": {
    "network": {
      "whitelist": {
        "required": ["https://status.example.com"]
      },
      "whitelistByNetwork": {
        "mainnet": {
          "required": ["https://mainnet-api.example.com"]
        },
        "testnet11": {
          "required": ["https://testnet-api.example.com"]
        }
      }
    }
  }
}

Choose required or optional access

Both shared and network-specific whitelist buckets support required and optional. Use required when the app cannot provide its core experience without the host. Use optional when the app can open without it and request access only after the user chooses the related feature.

An optional network target must still be declared in the manifest before the running app can request it. When requesting a whitelistByNetwork entry, include its networkId so Sage grants it in the correct bucket.

{
  "permissions": {
    "network": {
      "whitelistByNetwork": {
        "mainnet": {
          "optional": ["https://quotes.example.com"]
        }
      }
    }
  }
}

Rebuild and test the effective policy

Finalize and reinstall or update the app after changing its source manifest. Sage builds the app’s network policy from the granted entries and the currently selected Chia network.

Changing the selected Chia network or the effective network grants forces the app to reload so Sage can rebuild that policy. Test on both mainnet and testnet11, confirm the intended shared and network-specific hosts work, and confirm an undeclared host is blocked.

A browser console error mentioning connect-src means the destination is missing from the effective whitelist or the installed app still has an older manifest.