# Remote Bridge

## Prerequisites[​](#prerequisites "Direct link to Prerequisites")

* [Node.js](https://nodejs.org) v22+ environment with `npm`
* Databricks CLI (v1.0.0 or higher): install and configure it according to the [official tutorial](https://docs.databricks.com/aws/en/dev-tools/cli/tutorial).
* A new Databricks app with AppKit installed. See [Bootstrap a new Databricks app](./docs.md#quick-start-options) for more details.

Remote bridge allows you to develop against a deployed backend while keeping your UI and queries local. This is useful for testing against production data or debugging deployed backend code without redeploying your app.

## When to use Remote Bridge[​](#when-to-use-remote-bridge "Direct link to When to use Remote Bridge")

Use remote bridge when:

* Testing against production data
* Debugging deployed backend code
* Developing UI without running backend locally
* Collaborating with team members on the same backend

## Starting and stopping Remote Bridge[​](#starting-and-stopping-remote-bridge "Direct link to Starting and stopping Remote Bridge")

To start the remote bridge, run the following command:

```bash
databricks apps dev-remote

```

The command will:

1. Obtain app name from the context (either `app.yml` file or user input in the CLI)

2. Start a local Vite development server

3. Establish a WebSocket bridge to your deployed app

4. Provide two URLs:

   * **App URL**: Direct link for your own use (`<app-url>?dev=true`)
   * **Shareable URL**: Link with tunnel ID for sharing with team members (`<app-url>?dev=<tunnelId>`)

note

For all available options, run:

```bash
databricks apps dev-remote --help

```

To stop the remote bridge, press `Ctrl+C` in the terminal.

## Connection approval[​](#connection-approval "Direct link to Connection approval")

When you start remote bridge, every time you open the URL in your browser from a new device, you'll be prompted to approve the connection.

You can provide the URL to your team members to allow them to see the app in their browser. You will still need to approve the connection from your side.

## How it works[​](#how-it-works "Direct link to How it works")

Remote bridge creates a WebSocket bridge between your local Vite dev server and the deployed backend, allowing you to develop UI locally while using the deployed backend.

<!-- -->

### Details[​](#details "Direct link to Details")

* The **Browser** connects to the deployed app backend with `?dev=true` or `?dev=<tunnelId>` query parameter
* The **Deployed Backend** proxies UI requests through a WebSocket tunnel (`/dev-tunnel`) to your local machine
* The **WebSocket Bridge** (running locally) receives fetch requests and file read requests from the backend
* The **Local Vite Dev Server** serves the UI files and provides hot module replacement (HMR)
* The bridge sends responses back through the WebSocket to the backend, which serves them to the browser

### What gets hot-reloaded[​](#what-gets-hot-reloaded "Direct link to What gets hot-reloaded")

With remote bridge you get instant hot-reload for:

* **UI Changes** - Any changes to your React/TypeScript/CSS files in the `client/` directory
* **Query Files** - SQL files in the `config/queries/` directory (`.sql` files only)

Backend code is **not** hot-reloaded. You need to redeploy your app to see changes in the backend code.