Skip to main content

JBrowse CLI admin server

Caution

The CLI quickstart is the recommended way to build a config. The admin-server is for occasional GUI editing.

The JBrowse CLI's admin-server serves JBrowse 2 locally in "admin mode", where the Assembly manager, the Add track form and the connection form write their changes back to config.json. The writes only happen while the server runs.

Warning

The admin-server is for temporary configuration, not for production.

Prerequisites

Starting JBrowse 2 admin server

From inside your JBrowse 2 directory:

jbrowse admin-server

Open the printed link in your browser:

Admin server started on port 9090

To access the admin interface, open your browser to:
http://localhost:9090?adminKey=a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6

Admin key: a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6
Config file: /path/to/config.json

To stop the server, press Ctrl+C

Adding a genome assembly

Open the Assembly manager from the menu bar. It lists, creates, edits and deletes assemblies:

Screenshot showing the assembly manager, with no assemblies loaded yet. Open this view in JBrowse ↗

The steps behind the figure above, run against your own data.

    Open this view in JBrowse Desktop ↗

    Opens JBrowse Desktop (JBrowse Desktop 5.0+) at this view and saves it as a reopenable session — swap in your own files afterwards.

    Nothing happens? Paste this link into Desktop's Open JBrowse Web link... (start screen, or File → Session):

    https://jbrowse.org/code/jb2/main/?config=test_data%2Fempty.json&session=spec-%7B%22views%22%3A%5B%5D%7D&sessionName=JBrowse+docs%3A+assembly_manager&adminKey=admin1234

    This session spec pastes after &session=spec- on any JBrowse Web instance.

    {
  "views": []
}

    Loaded against config: test_data/empty.json

    Hand this to a coding agent. It rebuilds the figure above headlessly, and the session file is then the thing to edit — swap an adapter uri for your own file and rerun.

    cat > session.json <<'JSON'
{
  "views": []
}
JSON

npx @jbrowse/capture --instance https://jbrowse.org/code/jb2/main/ \
  --config https://jbrowse.org/code/jb2/main/test_data/empty.json \
  --session session.json -o figure.png

    Using JBrowse with AI agents covers the rest: hosted genomes to point it at, and why waiting for the render is the part that goes wrong.

    To add hg38, press Add new assembly, then Open from a URL, and paste the FASTA and its two indexes, one per line:

    https://jbrowse.org/genomes/GRCh38/fasta/hg38.prefix.fa.gz
https://jbrowse.org/genomes/GRCh38/fasta/hg38.prefix.fa.gz.fai
https://jbrowse.org/genomes/GRCh38/fasta/hg38.prefix.fa.gz.gzi

    The form pairs the indexes with the FASTA and fills in a name from the filename. Set the name to hg38, which is what the rest of this page calls it.

    Assembly manager page for adding a new assembly. Open this view in JBrowse ↗

    The steps behind the figure above, run against your own data.

      Open this view in JBrowse Desktop ↗

      Opens JBrowse Desktop (JBrowse Desktop 5.0+) at this view and saves it as a reopenable session — swap in your own files afterwards.

      Nothing happens? Paste this link into Desktop's Open JBrowse Web link... (start screen, or File → Session):

      https://jbrowse.org/code/jb2/main/?config=test_data%2Fhg38_only.json&session=spec-%7B%22views%22%3A%5B%5D%7D&sessionName=JBrowse+docs%3A+hg38_assembly_table&adminKey=admin1234

      This session spec pastes after &session=spec- on any JBrowse Web instance.

      {
  "views": []
}

      Loaded against config: test_data/hg38_only.json

      Hand this to a coding agent. It rebuilds the figure above headlessly, and the session file is then the thing to edit — swap an adapter uri for your own file and rerun.

      cat > session.json <<'JSON'
{
  "views": []
}
JSON

npx @jbrowse/capture --instance https://jbrowse.org/code/jb2/main/ \
  --config https://jbrowse.org/code/jb2/main/test_data/hg38_only.json \
  --session session.json -o figure.png

      Using JBrowse with AI agents covers the rest: hosted genomes to point it at, and why waiting for the render is the part that goes wrong.

      A JBrowse with no genome in it getting one: Tools, Assembly manager, Add new assembly, and three URLs pasted into a single box, which the form answers with the adapter it recognized and a name it filled in. Open the session this video starts in ↗

      Submit puts hg38 in the list:

      The assembly manager dialog box with human assemblies available Open this view in JBrowse ↗

      The steps behind the figure above, run against your own data.

        Open this view in JBrowse Desktop ↗

        Opens JBrowse Desktop (JBrowse Desktop 5.0+) at this view and saves it as a reopenable session — swap in your own files afterwards.

        Nothing happens? Paste this link into Desktop's Open JBrowse Web link... (start screen, or File → Session):

        https://jbrowse.org/code/jb2/main/?config=test_data%2Fconfig_demo.json&session=spec-%7B%22views%22%3A%5B%5D%7D&sessionName=JBrowse+docs%3A+add_hg38_assembly

        This session spec pastes after &session=spec- on any JBrowse Web instance.

        {
  "views": []
}

        Loaded against config: test_data/config_demo.json

        Hand this to a coding agent. It rebuilds the figure above headlessly, and the session file is then the thing to edit — swap an adapter uri for your own file and rerun.

        cat > session.json <<'JSON'
{
  "views": []
}
JSON

npx @jbrowse/capture --instance https://jbrowse.org/code/jb2/main/ \
  --config https://jbrowse.org/code/jb2/main/test_data/config_demo.json \
  --session session.json -o figure.png

        Using JBrowse with AI agents covers the rest: hosted genomes to point it at, and why waiting for the render is the part that goes wrong.

        Editing a genome assembly

        The pencil icon in the Assembly manager edits an assembly, and the same table deletes them.

        Adding a track

        Open the Add track form from the menu bar:

        JBrowse 2 file menu with the 'Add track' form Open this view in JBrowse ↗

        The steps behind the figure above, run against your own data.

        1. Open your genome: on the JBrowse Desktop start screen click Open new genome (or Show all available genomes to pick a hosted one).This figure uses hg19, loaded from a bgzip-compressed FASTA (.fa.gz + .fai + .gzi).
        2. Add your own track: File → Open track..., then paste a URL or choose a local file. This one needs a bgzip-compressed, tabix-indexed GFF3 (.gff.gz + .tbi).This figure uses “NCBI RefSeq genes (hg19)”.
        3. Type your region of interest into the location box and press Enter.This figure is at chr1:1,000,000-1,100,000.

        Open this view in JBrowse Desktop ↗

        Opens JBrowse Desktop (JBrowse Desktop 5.0+) at this view and saves it as a reopenable session — swap in your own files afterwards.

        Nothing happens? Paste this link into Desktop's Open JBrowse Web link... (start screen, or File → Session):

        https://jbrowse.org/code/jb2/main/?config=test_data%2Fconfig_demo.json&session=spec-%7B%22views%22%3A%5B%7B%22type%22%3A%22LinearGenomeView%22%2C%22assembly%22%3A%22hg19%22%2C%22loc%22%3A%22chr1%3A1%2C000%2C000-1%2C100%2C000%22%2C%22tracks%22%3A%5B%22ncbi_gff_hg19%22%5D%7D%5D%7D&sessionName=JBrowse+docs%3A+add_track_form

        This session spec pastes after &session=spec- on any JBrowse Web instance.

        {
  "views": [
    {
      "type": "LinearGenomeView",
      "assembly": "hg19",
      "loc": "chr1:1,000,000-1,100,000",
      "tracks": [
        "ncbi_gff_hg19"
      ]
    }
  ]
}

        Loaded against config: test_data/config_demo.json

        The same view with jbrowse-anywidget. Point the adapter at your own file.

        from jbrowse_anywidget import LinearGenomeView, fetch_hub

view = LinearGenomeView(
    assembly=fetch_hub("hg19"),
    location="chr1:1,000,000-1,100,000",
)

view.add_track({
    "type": "FeatureTrack",
    "trackId": "my_track",
    "name": "My track",
    "assemblyNames": ["hg19"],
    "adapter": {"type": "Gff3TabixAdapter", "uri": "https://your-server/your-file"},
})

view  # display the widget

        Hand this to a coding agent. It rebuilds the figure above headlessly, and the session file is then the thing to edit — swap an adapter uri for your own file and rerun.

        cat > session.json <<'JSON'
{
  "views": [
    {
      "type": "LinearGenomeView",
      "assembly": "hg19",
      "loc": "chr1:1,000,000-1,100,000",
      "tracks": [
        "ncbi_gff_hg19"
      ]
    }
  ]
}
JSON

npx @jbrowse/capture --instance https://jbrowse.org/code/jb2/main/ \
  --config https://jbrowse.org/code/jb2/main/test_data/config_demo.json \
  --session session.json -o figure.png

        Using JBrowse with AI agents covers the rest: hosted genomes to point it at, and why waiting for the render is the part that goes wrong.

        The circular "+" button in the track selector opens the same form:

        The 'Add track' form can be launched from the circular '+' button in the bottom righthand corner Open this view in JBrowse ↗

        The steps behind the figure above, run against your own data.

        1. Open your genome: on the JBrowse Desktop start screen click Open new genome (or Show all available genomes to pick a hosted one).This figure uses volvox, loaded from a .2bit genome.
        2. Add your own track: File → Open track..., then paste a URL or choose a local file. This one needs a BAM file (.bam + .bai).This figure uses “volvox-sorted.bam”.
        3. Type your region of interest into the location box and press Enter.This figure is at ctgA:1-20000.

        Open this view in JBrowse Desktop ↗

        Opens JBrowse Desktop (JBrowse Desktop 5.0+) at this view and saves it as a reopenable session — swap in your own files afterwards.

        Nothing happens? Paste this link into Desktop's Open JBrowse Web link... (start screen, or File → Session):

        https://jbrowse.org/code/jb2/main/?config=test_data%2Fvolvox%2Fconfig.json&session=spec-%7B%22views%22%3A%5B%7B%22type%22%3A%22LinearGenomeView%22%2C%22assembly%22%3A%22volvox%22%2C%22loc%22%3A%22ctgA%3A1-20000%22%2C%22tracks%22%3A%5B%22volvox_bam%22%5D%7D%5D%7D&sessionName=JBrowse+docs%3A+add_track_tracklist

        This session spec pastes after &session=spec- on any JBrowse Web instance.

        {
  "views": [
    {
      "type": "LinearGenomeView",
      "assembly": "volvox",
      "loc": "ctgA:1-20000",
      "tracks": [
        "volvox_bam"
      ]
    }
  ]
}

        Loaded against config: test_data/volvox/config.json

        The same view with jbrowse-anywidget. Point the adapter at your own file.

        from jbrowse_anywidget import LinearGenomeView, make_assembly

view = LinearGenomeView(
    assembly=make_assembly("volvox", "https://your-server/your-genome.fa.gz"),
    location="ctgA:1-20000",
)

view.add_track({
    "type": "AlignmentsTrack",
    "trackId": "my_track",
    "name": "My track",
    "assemblyNames": ["volvox"],
    "adapter": {"type": "BamAdapter", "uri": "https://your-server/your-file"},
})

view  # display the widget

        Hand this to a coding agent. It rebuilds the figure above headlessly, and the session file is then the thing to edit — swap an adapter uri for your own file and rerun.

        cat > session.json <<'JSON'
{
  "views": [
    {
      "type": "LinearGenomeView",
      "assembly": "volvox",
      "loc": "ctgA:1-20000",
      "tracks": [
        "volvox_bam"
      ]
    }
  ]
}
JSON

npx @jbrowse/capture --instance https://jbrowse.org/code/jb2/main/ \
  --config https://jbrowse.org/code/jb2/main/test_data/volvox/config.json \
  --session session.json -o figure.png

        Using JBrowse with AI agents covers the rest: hosted genomes to point it at, and why waiting for the render is the part that goes wrong.

        Provide a URL or select a local file. Supported formats and index types: Supported file types. Plugins add further formats; see the plugin store.

        Editing a track

        In a Linear Genome View, click "Select tracks". Each track's three-dot (...) menu has a "Settings" button that opens the configuration editor. Edits apply live and, through the admin-server, persist to the config file.

        Setting a default session

        The default session is what a visitor sees first. Open the Set default session form from the Admin menu:

        The 'Set default session' will persist your current session into the config file so any subsequent visitors to the app will see this session. Open this view in JBrowse ↗

        The steps behind the figure above, run against your own data.

          Open this view in JBrowse Desktop ↗

          Opens JBrowse Desktop (JBrowse Desktop 5.0+) at this view and saves it as a reopenable session — swap in your own files afterwards.

          Nothing happens? Paste this link into Desktop's Open JBrowse Web link... (start screen, or File → Session):

          https://jbrowse.org/code/jb2/main/?config=test_data%2Fempty.json&session=spec-%7B%22views%22%3A%5B%5D%7D&sessionName=JBrowse+docs%3A+default_session_form&adminKey=admin1234

          This session spec pastes after &session=spec- on any JBrowse Web instance.

          {
  "views": []
}

          Loaded against config: test_data/empty.json

          Hand this to a coding agent. It rebuilds the figure above headlessly, and the session file is then the thing to edit — swap an adapter uri for your own file and rerun.

          cat > session.json <<'JSON'
{
  "views": []
}
JSON

npx @jbrowse/capture --instance https://jbrowse.org/code/jb2/main/ \
  --config https://jbrowse.org/code/jb2/main/test_data/empty.json \
  --session session.json -o figure.png

          Using JBrowse with AI agents covers the rest: hosted genomes to point it at, and why waiting for the render is the part that goes wrong.

          The form clears the default session, or sets it to the current session or any previously saved one.

          See also