# Connections

**TL;DR:** A **connection** is a reusable pointer to an external track hub or
data directory. Point JBrowse at a hub once and its tracks become available in
the track selector.

JBrowse supports three built-in connection types:

- UCSC Track Hub - any
  [UCSC Genome Browser track hub](https://genome.ucsc.edu/goldenPath/help/hgTrackHubHelp.html)
  reachable over the network
- JB2 Track Hub - a track hub based on a
  [JBrowse 2 config file](https://jbrowse.org/jb2-staging/docs/config_guides/from_config)
- JBrowse 1 data directory - a legacy JBrowse 1 data directory with a
  `trackList.json`

## Connections in the track selector

Every connection appears as its own **category** in the track selector, listed
below your regular tracks and named after the connection.

A connection is loaded **lazily**: expanding its category fetches the hub's
track list. This keeps large hubs (which can contain thousands of tracks) out of
the way until you want them. Once expanded, its tracks appear underneath and you
open them with their checkboxes like any other track.

Because loading only happens on expand, adding several connections is cheap.
Expand the one you want; leave the rest collapsed.

## Opening a connection

Open the form from either route:

- Menu bar: `File` → `Open connection...`
- Track selector's hamburger menu → `Connections...` → `Add connection...`

Paste the hub URL (see below for the format), choose the connection type, and
submit. A newly added connection loads right away, so its tracks appear
immediately.

## Connections and saved sessions

Opening a track from a connection remembers it in your session, so after a page
reload it reopens immediately without re-fetching the whole hub. The
connection's category shows collapsed; expand it again to browse the rest.

Only the tracks you opened are stored, so sharing or saving a session that uses
a connection stays lightweight even when the underlying hub is huge.

## Removing a connection

Open the track selector's hamburger menu → `Connections...` →
`Delete connections...` and choose the connection to remove.

## UCSC track hub URL format

The URL must point directly to the `hub.txt` file of the hub, for example:

```
https://hgdownload.soe.ucsc.edu/hubs/GCA/009/914/755/GCA_009914755.4/hub.txt
```

Public hubs are listed in the
[UCSC Public Hub directory](https://genome.ucsc.edu/cgi-bin/hgHubConnect); paste
the URL from its "URL" column into the connection form.

JBrowse matches hub tracks to assemblies by genome ID. Tracks targeting an
assembly not configured in your JBrowse instance will not appear. You can filter
by assembly name in the connection form.

## JBrowse 1 connection URL format

For the legacy JBrowse 1 connection type, point the URL at the JBrowse 1 data
directory containing `trackList.json` (e.g. `https://myhost/jbrowse1/data/`) and
supply the assembly name it corresponds to. See the
[JBrowse1Connection config docs](https://jbrowse.org/jb2-staging/docs/config/jbrowse1connection) for details.

## Adding a connection via the CLI

```bash
# UCSC track hub
jbrowse add-connection https://example.com/hub.txt \
  --type UCSCTrackHubConnection \
  --name "My Hub"

# JBrowse 1 data directory
jbrowse add-connection https://myhost/jbrowse1/data/ \
  --type JBrowse1Connection \
  --assemblyNames hg19 \
  --name "JBrowse 1 data"
```

See `jbrowse add-connection --help` or the
[CLI reference](https://jbrowse.org/jb2-staging/docs/cli#jbrowse-add-connection) for all options.

## See also

- [](https://jbrowse.org/jb2-staging/docs/user_guides/hub_url)
- [Configuring connections](https://jbrowse.org/jb2-staging/docs/config_guides/connections)
- [Basic usage: opening tracks](https://jbrowse.org/jb2-staging/docs/user_guides/basic_usage#opening-tracks)
- [](https://jbrowse.org/jb2-staging/docs/user_guides/plugin_store)
- [Text searching configuration](https://jbrowse.org/jb2-staging/docs/config_guides/text_searching)
- [Gallery: track hubs](https://jbrowse.org/jb2-staging/gallery/#hubs)