> ## Documentation Index
> Fetch the complete documentation index at: https://docs.omni.co/llms.txt
> Use this file to discover all available pages before exploring further.

# App settings

> Configure per-app security and functionality settings to enable features like map rendering and link navigation in Apps.

[Apps](/visualize-present/apps) run in a sandboxed iframe with strict security controls by default. App-level settings let you enable specific features on a per-app basis, giving you fine-grained control over what each app can do.

## Requirements

**Editor permissions** or higher on a document are required to edit app settings.

## How it works

By default, apps can't make outbound network requests, such as navigating to another page or website or loading external images — the iframe's Content Security Policy (CSP) blocks them to prevent data exfiltration.

Allowed hosts - enabled by turning on specific app settings - are third-party services that the app author doesn't control, so they can't be used as a channel to exfiltrate query data. This is unlike a bring-your-own-key provider where the author could read request logs. The app never gains access to `'self'`, `https:`, or wildcard origins.

<h2 id="access-settings">
  Accessing app settings
</h2>

To access an app's settings:

1. In an app, click **Edit** to enter draft mode.
2. Near the top left corner of the page, click the <Icon icon="gear" /> icon (located next to <Icon icon="code" /> **Code**).

## Allow map providers

The **Allow map providers** setting allows maps in your app by enabling it to render tiles from keyless map providers. Along with enabling this setting yourself, the Omni Agent can enable it automatically when you ask it to add a map to your app.

When enabled, Omni widens the CSP to permit image and network requests to the following map providers' tile servers and the CDNs their libraries load from. No additional setup is needed.

| Provider      | Type                 | Library     |
| ------------- | -------------------- | ----------- |
| OpenStreetMap | Raster tiles         | Leaflet     |
| Carto         | Raster tiles         | Leaflet     |
| Carto         | Vector tiles (WebGL) | MapLibre GL |

## Safe domains

**Safe domains** lets you optionally extend the app's security model by specifying additional trusted hosts for loading images, scripts, stylesheets, fonts, and network connections.

By default, apps can load resources from a curated list of trusted CDNs (e.g., Google Fonts, jsDelivr) and Omni's bundled charting, styling, and utility libraries. These are available regardless of your safe domain configuration.

<h3 id="configure-safe-domains">
  Configuring Safe domains
</h3>

To configure safe domains for an app:

1. Open the [app's settings](#access-settings).
2. In the **Safe domains** section, toggle **Allow safe domains** on.
3. Enter one or more domains in the **Safe domains** field. Add one domain per line or separate using spaces or commas:

   <CodeGroup>
     ```text One domain per line theme={null}
      cdn.example.com
      *.assets.acme.co
     ```

     ```text Comma-separated theme={null}
     cdn.example.com, *.assets.acme.co
     ```

     ```text Space-separated theme={null}
     cdn.example.com *.assets.acme.co
     ```
   </CodeGroup>

   See [Domain formats](#domain-formats) for formatting requirements.
4. Click outside the text area to save. The domains are validated when you save.

Along with configuring safe domains yourself, the Omni Agent can configure safe domains when building or editing an app. For example, you can tell it *"load images from cdn.example.com"* and it will enable **Allow safe domains** and add the specified domain.

### Disabling Allow safe domains

If you disable **Allow safe domains**, all external access (excluding map providers if [**Allow map providers**](#allow-map-providers) is enabled) for the app will be disabled. Specified domains will be saved and can be re-enabled by toggling the setting back to on.

### Domain formats

<Tabs>
  <Tab title="Valid formats">
    **Safe domains** accepts the following formats:

    | Pattern                  | Examples                                                                                 |
    | ------------------------ | ---------------------------------------------------------------------------------------- |
    | Specific hosts           | `cdn.example.com`, `maps.acme.co`                                                        |
    | Subdomains with wildcard | `*.example.com` (matches `cdn.example.com`, `images.example.com`, but not `example.com`) |
    | Hosts with ports         | `assets.example.com:8080`                                                                |

    Each domain must:

    * Have at least two labels (e.g., `example.com` is valid, but `localhost` or `com` alone is not)
    * Use only lowercase letters, digits, hyphens, dots, and optionally a leading `*.` wildcard
    * Be 253 characters or fewer
    * Include a valid port (5 digits or fewer, numeric) if a port is specified

    For example:

    ```text Valid domains theme={null}
    cdn.example.com
    *.assets.acme.co
    tiles.mapserver.org:8080
    fonts.googleapis.com
    ```
  </Tab>

  <Tab title="Disallowed domain patterns">
    To prevent sandbox escape and injection attacks, **Safe domains** enforces strict validation rules. The following are explicitly disallowed:

    | What's blocked                       | Examples                                                                                                                                            | Why                                |
    | ------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------- |
    | CSP keywords                         | `'self'`, `'none'`, `'unsafe-inline'`, `'unsafe-eval'`                                                                                              | Could bypass security restrictions |
    | Bare wildcards / too-broad wildcards | `*`, `*.com`, `*.io`                                                                                                                                | Not specific enough to be safe     |
    | Schemes / scheme-sources             | `data:`, `blob:`, `https:`, `ws:`, `filesystem:`                                                                                                    | Could enable injection attacks     |
    | Injection characters                 | `evil.com"><script>`, `a.com;b`, domains with spaces, quotes, semicolons, angle brackets                                                            | Could escape the CSP directive     |
    | Non-specific hosts                   | `localhost`, `com`, `internal`                                                                                                                      | Must have at least two labels      |
    | Omni-owned domains                   | `omniapp.co`, `embed-omniapp.co`, `exploreomni.dev`, `embed-exploreomni.dev`, `thundersalmon.com`, `embed-thundersalmon.com` (including subdomains) | Would allow sandbox breakout       |
    | Invalid labels                       | `foo..com`, `.acme.com`, `acme.com.`, `foo_bar.com` (underscore), `café.com` (non-ASCII)                                                            | Malformed domain format            |
    | Oversized domains                    | Domains longer than 253 characters                                                                                                                  | Exceeds DNS length limits          |

    If you enter an invalid domain, it will be rejected when you save, and an error message will explain why. For example:

    ```text Invalid domains theme={null}
    localhost                # single label
    *.com                    # too broad
    https://example.com      # schemes not allowed
    omniapp.co               # Omni-owned domain
    'self'                   # CSP keywords not allowed
    data:                    # scheme-sources not allowed
    ```
  </Tab>
</Tabs>

## Navigation

**Navigation** settings let you control whether and where an app can open links, covering both external websites and pages inside Omni.

Along with enabling these settings yourself, the [Omni Agent](/ai/chat) can enable these settings automatically when you ask it to add links or navigation to your app.

<h3 id="allow-opening-links">
  Allow opening links
</h3>

**Allow opening links** allows the app to open external links. When enabled, you can also configure the [**Open external links in a new tab**](#open-links-new-tab) and [**Allow navigation domains**](#allow-navigation-domains) settings.

When this setting is enabled but navigation domains aren't configured, the app can open links to - and send data to - any site. Restrict where it can navigate by turning on [**Allow navigation domains**](#allow-navigation-domains) and listing trusted hosts.

<h4 id="open-links-new-tab">
  Open external links in a new tab
</h4>

**Open external links in a new tab** forces external links to open in a new tab, keeping the app on the current page. This is the default, and it applies even if the app requests otherwise. The [Allow opening links](#allow-opening-links) setting must be enabled to configure this setting.

<Warning>
  **Heads up!** Turning this setting off lets the app replace the current page with an external site — potentially a phishing site that imitates a login page or another trusted site. If you turn it off, consider also enabling [Allow navigation domains](#allow-navigation-domains) so the app can only navigate to hosts you trust.
</Warning>

<h4 id="allow-navigation-domains">
  Allow navigation domains
</h4>

**Allow navigation domains** limits where the app can open links:

* **When disabled**, the app can open links to any site
* **When enabled**, the app can only open links to the hosts listed in the **Navigation domains** field. The [**Allow opening links**](#allow-opening-links) setting must be enabled to specify **Navigation domains**.

To restrict where an app can open links:

1. Open the [app's settings](#access-settings).
2. Enable [**Allow opening links**](#allow-opening-links).
3. Enable **Allow navigation domains**.
4. In the **Navigation domains** field, enter one or more hosts. Add one host per line, or separate them with commas or spaces. Wildcards like `*.example.com` are allowed:

   <CodeGroup>
     ```text One host per line theme={null}
     docs.example.com
     *.example.com
     ```

     ```text Comma-separated theme={null}
     docs.example.com, *.example.com
     ```

     ```text Space-separated theme={null}
     docs.example.com *.example.com
     ```
   </CodeGroup>

   Navigation domains follow the same formatting and validation rules as safe domains. See [Domain formats](#domain-formats) for accepted and disallowed patterns.
5. Click outside the text area to save.

<h3 id="allow-internal-navigation">
  Allow internal navigation
</h3>

**Allow internal navigation** lets the app navigate to other pages inside Omni — for example, a link that opens a dashboard.

This setting is independent of [**Allow opening links**](#allow-opening-links): you can allow internal navigation without allowing the app to open external links, and vice versa.

## Related

* [App overview](/visualize-present/apps)
* [Styling apps](/visualize-present/apps/styling)
* [App inspector](/visualize-present/apps/inspect)