# Whitelist network access in Sage

> Declare every external host your app contacts and scope network-specific services to the active Chia network.

Sage runs installed apps behind a Content Security Policy. Every external host the app wants to contact must be present in its effective network whitelist; otherwise Sage blocks the request before it reaches the destination.

## 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.

**Shared network whitelist**

```json
{
  "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.

**Shared and network-specific hosts**

```json
{
  "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.

**Optional host for mainnet**

```json
{
  "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.

## Builder's note

Bridge APIs and client behavior can evolve. Verify implementation details against the Sage version you support, then test in both Sage and a normal browser.

---

Human-readable page: https://fancybudgie.com/sage/guides/sage-network-whitelist

Guide index: [llms.txt](https://fancybudgie.com/llms.txt)