# Local bridge and token · OmniGet Docs

- URL: https://getomniget.com/docs/bridge
- Updated: 2026-10-02
- OmniGet 1.0.0

> Free, open-source yt-dlp GUI for Windows, macOS and Linux. Paste a link to save video, audio and files from 1,000+ sites, or run AI coding agents.

---

Developers

# Local bridge and token

The local bridge is a small HTTP server inside OmniGet that only listens on `127.0.0.1`, so programs on your own computer can talk to the app. The browser extension, the MCP server for AI tools and the `omniget` command line all go through it, each with its own key.

## Where it is

The bridge starts with OmniGet; there is nothing to turn on. Its settings are in **Settings › Integrations › Browser extension**:

-   **Pair the extension** with the **Pair extension** button.
-   Under **Advanced** (click **Show advanced options**): **Endpoint URL**, **Pairing token** and **Rotate token**.

## Ports

The bridge tries the port it used last time, then the first free port from 47720 to 47729. The **Endpoint URL** shows the address in use.

If every port in that range is taken, OmniGet uses any free port outside it. The extension and the connect skill only search the range, so in that case copy the **Endpoint URL** into the extension by hand.

`GET /v1/health` answers without a token, with `ok` and the app version. Use it to check that the bridge is up:

```
curl -s http://127.0.0.1:47720/v1/health
```

## Pair the browser extension

Pairing hands the extension the bridge token without copy and paste.

1.  Install the [browser extension](https://getomniget.com/docs/extension) and keep the browser open.
2.  In OmniGet, open **Settings › Integrations › Browser extension**.
3.  Click **Pair extension**. The line below reads **Window open — the extension will connect automatically**, with a countdown of 120 seconds.
4.  The extension finds OmniGet on its own. When it does, the line reads **Extension connected — you’re all set.**

The pairing window gives the token out once and closes. If the time runs out, you see **Pairing window expired — is the extension installed and the browser open?** Click **Pair extension** again.

### Pair by hand

1.  In OmniGet, click **Show advanced options** under **Browser extension**.
2.  Click **Copy** next to **Endpoint URL**, and **Reveal** or **Copy** next to **Pairing token**.
3.  Open the extension’s options page, paste both fields and click **Save**, then **Test connection**.

## Rotate the token

Rotate the token if you think another program has it.

1.  Click **Show advanced options** under **Browser extension**.
2.  Next to **Rotate token**, click **Rotate** and confirm with **Generate new token**.
3.  Restart OmniGet, then pair the extension again.

Warning

In this release, the running bridge keeps accepting the old token until OmniGet restarts, and the new one only works after the restart.

Browsers paired before lose access until you pair them again or paste the new token.

## Who uses the bridge, and with which key

| Client | Key | Where it comes from |
| --- | --- | --- |
| Browser extension | The pairing token | **Pair extension**, or copied by hand |
| AI tools through MCP (`/mcp`) | A key of its own for each tool | Written into the tool’s config when you approve the connection |
| `omniget` CLI | A CLI key of its own | Created by OmniGet in its data folder; or the `OMNIGET_TOKEN` variable |
| Scripts and webhooks | A scoped access token | **LLM › Work › Tasks › Access tokens** |

Every request except the health check sends its key as `Authorization: Bearer <key>`.

### AI tools

An AI coding tool connects by asking OmniGet first. It calls `POST /v1/connect`, and OmniGet shows **… wants to connect to OmniGet** with a short code; the tool shows the same code. Pick what it may do:

-   **Start downloads and see the ones it started**: always included.
-   **Run your AI agents as background jobs in this folder**: shown when the tool sent the folder it works in.
-   **Answer those agents’ permission questions for you**: only with the line above. Off, OmniGet asks you each time.

Click **Allow** or **Don’t allow**. On **Allow**, OmniGet turns the MCP server on, writes the tool’s own key straight into its config file and tells the tool how to reload. The key never passes through the chat. An unanswered request expires after 5 minutes.

Requests from a web page (with an `Origin` header) are refused, so a site you visit cannot ask for access. More in [OmniGet as an MCP server](https://getomniget.com/docs/mcp-server).

### The command line

The `omniget` CLI reads the port from OmniGet’s settings and uses its own scoped key, which the app creates. You can also set:

-   `OMNIGET_TOKEN`: a token from **Access tokens** with the scopes the command needs.
-   `OMNIGET_BRIDGE_URL`: the bridge address, such as `http://127.0.0.1:47721`.

Older scripts may still use the extension’s token on the agent routes. That still works while **Still accept the browser extension’s key on agent routes (deprecated)** is on in **Access tokens**; the CLI prints a warning when it falls back to it. Switch them to a scoped token. More in [Command line](https://getomniget.com/docs/cli).

## Common problems

### “Bridge unavailable. Try restarting the app.”

The bridge did not start, usually because it could not open a port on `127.0.0.1`. Restart OmniGet. If a security tool blocks local servers, allow OmniGet in it.

### The extension says “OmniGet not detected”

OmniGet is closed, or it is on a port outside the range. Open the app, then pair again or paste the **Endpoint URL** into the extension.

### The extension says “Bad pairing token”

The token changed. Pair again, or copy the current **Pairing token** into the extension.

[Previous**← FAQ**](https://getomniget.com/docs/faq)