> For the complete documentation index, see [llms.txt](https://documentation.dnanexus.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://documentation.dnanexus.com/developer/apps/isolated-browsing-for-https-apps.md).

# Isolated Browsing for HTTPS Apps

Restrict data transfer between HTTPS apps and the user's local computer.

## What is Isolated Browsing?

Isolated Browsing is a project-level security feature that restricts data transfer between [HTTPS apps](https://documentation.dnanexus.com/developer/apps/https-applications.md) and the user's local computer. It prevents direct communication between the httpsApp Web Application and the user's local web browser.

Isolated Browsing applies to all httpsApp-enabled jobs in the project, such as jobs running [JupyterLab](https://platform.dnanexus.com/app/dxjupyterlab), [ttyd](https://platform.dnanexus.com/app/ttyd), [LocusZoom](https://platform.dnanexus.com/app/locuszoom), or any other httpsApp-enabled app or applet.

{% hint style="info" %}
Isolated Browsing is a limited-access feature requiring a separate license. [Contact DNAnexus Sales](mailto:sales@dnanexus.com) for more information.
{% endhint %}

## Enable Isolated Browsing

To enable Isolated Browsing in a project you have ADMIN access to:

1. Ensure the project's `billTo` has the `httpsAppIsolatedBrowsingControl` license.
2. Set the project's `httpsAppIsolatedBrowsing` [data access control](https://documentation.dnanexus.com/getting-started/key-concepts/projects.md#project-data-access-controls) flag to `true`.

You can set the project's data access control flags using the DNAnexus CLI.

```shell
# As a project admin, set a project's 'httpsAppIsolatedBrowsing' flag to 'true'
dx api project-xxxx update '{"httpsAppIsolatedBrowsing":true}'
```

You can also use the CLI to check whether the `httpsAppIsolatedBrowsing` flag is set.

```shell
# Show a project's 'httpsAppIsolatedBrowsing' flag
dx describe project-xxxx
# Show a job's 'httpsApps.isolatedBrowsing' flag
dx describe job-xxxx
```

{% hint style="info" %}
To run apps and applets in projects with Isolated Browsing enabled, the httpsApp-enabled executables must have [`httpsApp.shared_access`](https://documentation.dnanexus.com/developer/apps/https-applications.md#dxappjson) set to `NONE`.
{% endhint %}

## How Isolated Browsing Works

Isolated Browsing adds an extra layer to interacting with HTTPS apps. It restricts data transfers between your computer and all httpsApp Web Applications exposed by a job.

Instead of your local web browser directly interacting with the httpsApp Web Application, a separate remote browser handles this communication. Your local browser receives visual updates (screen encodings) from the remote browser, and your actions (keyboard and mouse input) are sent to the remote browser, which then forwards them to the application.

```mermaid
flowchart LR
    subgraph dnanexus["DNAnexus"]
        direction TB
        remote["<b>Remote browser</b><br/>in full-screen mode,<br/>in a minimal Linux OS"]
        app["<b>httpsApp web application</b><br/>e.g. JupyterLab server"]
    end
    local["<b>Local browser</b><br/>on user's laptop"]
    local -->|"https: keyboard, mouse events"| remote
    remote -->|"https: graphical screen<br/>encoding of the remote browser"| local
    remote -->|http| app
    app -->|"html, json, images,<br/>javascript, etc."| remote

    %% Styling
    classDef userNode fill:#F6F7FA,stroke:#121249,stroke-width:2px,color:#121249
    classDef platformNode fill:#18ADF1,stroke:#121249,stroke-width:2px,color:#121249
    classDef appNode fill:#61BA00,stroke:#121249,stroke-width:2px,color:#121249
    classDef workflowGroup fill:#F6F7FA,stroke:#121249,stroke-width:2px,color:#121249

    class local userNode
    class remote platformNode
    class app appNode
    class dnanexus workflowGroup
```

The remote browser starts in full screen mode, focusing the user's attention on the job's httpsApp Web Application, such as the JupyterLab interface. This hides the remote browser's navigation elements from view.

You can exit the remote browser's full screen mode by hovering your mouse pointer near the top of the window and selecting the floating "X" that appears.

![Exit the remote browser's full screen mode by clicking the Exit button in the top middle.](https://3410363935-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FS1s2UHuAFgrsxnijuHMc%2Fuploads%2Fgit-blob-5d6f6d26ba48032d674f0d1733a2f3c32df761ce%2Fisolated-browsing-exit-full-screen.webp?alt=media)

When you exit the full screen mode, you can see the tabs opened in the remote browser. You can also open another remote browser tab to visit another httpsApp application on a different httpsApp port.

![Exiting the remote browser's full screen mode reveals remote browser tabs and the navigation bar](https://3410363935-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FS1s2UHuAFgrsxnijuHMc%2Fuploads%2Fgit-blob-0c7d0218f39a78704bc8b2189937bc73807ed7ad%2Fisolated-browsing-remote-browser-navigation.png?alt=media)

For example, to see JupyterLab's Spark UI interface, visit `http://job:8081/` in the remote browser's navigation bar after executing Spark code.

![Access to Spark UI after executing spark code in the remote browser's navigation bar](https://3410363935-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FS1s2UHuAFgrsxnijuHMc%2Fuploads%2Fgit-blob-42fcf293a211b98a42594ceba05dae16b1bfa342%2Fisolated-browsing-spark-ui.png?alt=media)

To re-enter the full screen mode, click the vertical three-dot menu in the remote browser's top right corner, and then in the Zoom menu item, click the rectangle-corners icon. You can also use the Zoom controls to enlarge or reduce the size of your app.

![Re-entering the full screen mode in the remote browser.](https://3410363935-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FS1s2UHuAFgrsxnijuHMc%2Fuploads%2Fgit-blob-3fa3638dbcd877e7126927220991d73a88fce136%2Fisolated-browsing-resume-full-screen.png?alt=media)

If you close the remote browser window, the remote browser is automatically restarted.

To minimize the risk of unauthorized data transfers, the remote browser is configured to disallow the following:

* Access sites other than the httpsApp Web Applications.
* Open or save remote desktop files.
* Install Chrome extensions.
* Access the remote browser's DevTools.

## Data Transfer Restrictions Enforced by Isolated Browsing

Data transfers over the httpsApp interface between your local computer and the job via APIs exposed by an httpsApp Web Application are disabled.

For example, with Isolated Browsing, you cannot perform the following actions via the httpsApp interface against a job running JupyterLab:

* Download a file to your local computer from the job, or save a Jupyter notebook to your local computer.
* Upload a file from your local computer to the job.
* Invoke JupyterLab API requests using cURL against an httpsApp endpoint of the job.
* Observe JSON and text information transferred between your local computer and the JupyterLab web application in the developer console of your local web browser.

## Copy and Paste Restrictions Enforced by Isolated Browsing

Isolated Browsing restricts clipboard operations (copy and paste) between your local computer and the remote browser to prevent data exfiltration.

* Copying from the remote browser to the local computer is *limited*. You can copy text from the httpsApp Web Application and paste it into an application on your local computer, subject to a size limit configured by a project administrator. If the limit is set to 0, copying is disabled.
* Pasting from the local computer to the remote browser is *limited*. You can copy text from your local computer and paste it into the httpsApp Web Application, subject to a size limit configured by a project administrator. If the limit is set to 0, pasting is disabled.
* Copying and pasting within the remote browser is *allowed*. Copying and pasting text entirely within the remote browser (for example, from one JupyterLab notebook cell to another) is allowed without restriction.

| Copy From      | Paste To            | Allowed                                                                                                                                                                      |
| -------------- | ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Remote browser | Local computer      | <p>Yes, if the <a href="#configuring-the-copy-limit">copy limit</a> is enabled. Text that exceeds the limit is shortened to the limit.<br>No, if the limit is disabled</p>   |
| Local computer | Remote browser      | <p>Yes, if the <a href="#configuring-the-paste-limit">paste limit</a> is enabled. Text that exceeds the limit is shortened to the limit.<br>No, if the limit is disabled</p> |
| Remote browser | Same remote browser | Yes                                                                                                                                                                          |

Isolated Browsing doesn't prevent you from taking screenshots or photographs of the httpsApp Web Application interface.

### Configuring the Copy Limit

A project administrator can set the maximum number of bytes allowed for copying from the remote browser to the local clipboard by using the [`/project-xxxx/update` API method](https://documentation.dnanexus.com/developer/api/data-containers/projects.md#api-method-project-xxxx-update) and setting the `httpsAppIsolatedBrowsingOptions` field.

The value for `copyToLocalClipboardMaxBytes` must be between 0 and 262,100 bytes, where `0` disables copying entirely.

The `httpsAppIsolatedBrowsingOptions` mapping replaces the existing options mapping. Include both limit keys in each update request to preserve the settings for both directions. The request must also set `httpsAppIsolatedBrowsing` to `true`.

```shell
# Example: Set the copy limit to 1,024 bytes and disable pasting
dx api project-xxxx update '{"httpsAppIsolatedBrowsing": true, "httpsAppIsolatedBrowsingOptions": {"copyToLocalClipboardMaxBytes": 1024, "pasteFromLocalClipboardMaxBytes": 0}}'
```

### Configuring the Paste Limit

A project administrator can set the maximum number of bytes allowed for pasting from the local clipboard to the remote browser by using the [`/project-xxxx/update` API method](https://documentation.dnanexus.com/developer/api/data-containers/projects.md#api-method-project-xxxx-update) and setting the `httpsAppIsolatedBrowsingOptions` field.

The value for `pasteFromLocalClipboardMaxBytes` must be between 0 and 262,100 bytes, where `0` disables pasting entirely.

```shell
# Example: Set the paste limit to 1,024 bytes and disable copying
dx api project-xxxx update '{"httpsAppIsolatedBrowsing": true, "httpsAppIsolatedBrowsingOptions": {"copyToLocalClipboardMaxBytes": 0, "pasteFromLocalClipboardMaxBytes": 1024}}'
```

To enable both directions, set both limits in the same request.

```shell
# Example: Set both limits to 1,024 bytes
dx api project-xxxx update '{"httpsAppIsolatedBrowsing": true, "httpsAppIsolatedBrowsingOptions": {"copyToLocalClipboardMaxBytes": 1024, "pasteFromLocalClipboardMaxBytes": 1024}}'
```

### Copy and Paste Behavior and Limitations

When copying from the remote browser or pasting from your local computer into the remote browser, be aware of the following behaviors and limitations:

#### Browser Support and Permissions

* **Supported Browsers**: The copy and paste functionality works on local Chrome, Chromium, and Microsoft Edge browsers. It does not work on Firefox or Safari.
* **Required Permissions**: When you paste text from your local clipboard into the remote browser, your local browser asks permission to "See text and images copied to the clipboard". Select *Allow* to enable pasting. This read permission is not needed to copy text from the remote browser to your local clipboard.

#### Content and Formatting

* Only plain text can be copied between the remote browser and your local computer.
* If you copy formatted text, only the text is transferred and formatting is lost.
* Images and files cannot be copied between the remote browser and your local computer.

#### Clipboard Synchronization

When you switch focus from another tab or application on your local computer back to the tab running the Isolated Browsing httpsApp Web Application, the remote clipboard is updated with text from your local clipboard if the paste limit is enabled.

* If text in your local clipboard exceeds the paste limit, only text up to the limit is sent to the remote browser. Your local clipboard remains unchanged.
* When you copy text in the remote browser, it is synchronized to your local clipboard. If the text exceeds the copy limit, only text up to the limit is copied. A copy limit of `0` disables this transfer and leaves your local clipboard unchanged.

## Key Bindings

Because the remote browser runs in a Linux environment, httpsApp Web Applications behave as if a Linux user were interacting with them and accept Linux key bindings.

Windows users experience minimal differences. On macOS, most key bindings can be converted to the Linux ones by using the control key (<kbd>^</kbd>) instead of the command key (<kbd>⌘</kbd>).

For example, with macOS, this means you need to use <kbd>Control</kbd> + <kbd>C</kbd> instead of <kbd>Command</kbd> + <kbd>C</kbd> when copying selected text in the remote browser.

### Key binding tips

* If you have difficulties entering the hashtag symbol `#` for comments in a notebook cell, use <kbd>Ctrl</kbd>+<kbd>/</kbd> instead. On macOS with a British keyboard, use <kbd>Option</kbd>+<kbd>3</kbd> (the right Option key).
* To navigate within a JupyterLab cell in edit mode on macOS, use <kbd>Fn</kbd>+<kbd>Left arrow</kbd>, <kbd>Fn</kbd>+<kbd>Right arrow</kbd>, <kbd>Fn</kbd>+<kbd>Up arrow</kbd>, or <kbd>Fn</kbd>+<kbd>Down arrow</kbd>.
* To zoom in or out, use <kbd>Ctrl</kbd>+<kbd>+</kbd> or <kbd>Ctrl</kbd>+<kbd>-</kbd>.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://documentation.dnanexus.com/developer/apps/isolated-browsing-for-https-apps.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
