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 ↗

Open this view in JBrowse Desktop ↗

Opens JBrowse Desktop (JBrowse Desktop 5.0+) at this view and saves it as a reopenable session.

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

With your own data, the steps behind the figure:

    Open this view in JBrowse Web ↗

    Its genome and tracks are hosted, so File → Open track... there adds your own files beside them.

    With your own data, the steps behind the figure:

      This session spec draws the figure from test_data/empty.json: paste it after &session=spec- on a JBrowse Web link that loads that config.

      {
  "views": []
}

      The same view with jbrowse-anywidget, from the config the figure loads. Swap a track's uri for your own file.

      from jbrowse_anywidget import JBrowseApp, fetch_hub

config = fetch_hub("https://jbrowse.org/code/jb2/main/test_data/empty.json")
app = JBrowseApp(
    assemblies=config["assemblies"],
    tracks=config.get("tracks", []),
    views=[],
)
app  # 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": []
}
JSON

npx @jbrowse/capture --instance https://jbrowse.org/code/jb2/main/ \
  --config https://jbrowse.org/code/jb2/main/test_data/empty.json \
  --width 1000 --height 540 \
  --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; the rest of this page uses that name.

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

      Open this view in JBrowse Desktop ↗

      Opens JBrowse Desktop (JBrowse Desktop 5.0+) at this view and saves it as a reopenable session.

      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

      With your own data, the steps behind the figure:

        Open this view in JBrowse Web ↗

        Its genome and tracks are hosted, so File → Open track... there adds your own files beside them.

        With your own data, the steps behind the figure:

          This session spec draws the figure from test_data/hg38_only.json: paste it after &session=spec- on a JBrowse Web link that loads that config.

          {
  "views": []
}

          The same view with jbrowse-anywidget, from the config the figure loads. Swap a track's uri for your own file.

          from jbrowse_anywidget import JBrowseApp, fetch_hub

config = fetch_hub("https://jbrowse.org/code/jb2/main/test_data/hg38_only.json")
app = JBrowseApp(
    assemblies=config["assemblies"],
    tracks=config.get("tracks", []),
    views=[],
)
app  # 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": []
}
JSON

npx @jbrowse/capture --instance https://jbrowse.org/code/jb2/main/ \
  --config https://jbrowse.org/code/jb2/main/test_data/hg38_only.json \
  --width 1000 --height 540 \
  --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 ↗

          Open this view in JBrowse Desktop ↗

          Opens JBrowse Desktop (JBrowse Desktop 5.0+) at this view and saves it as a reopenable session.

          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

          With your own data, the steps behind the figure:

            Open this view in JBrowse Web ↗

            Its genome and tracks are hosted, so File → Open track... there adds your own files beside them.

            With your own data, the steps behind the figure:

              This session spec draws the figure from test_data/config_demo.json: paste it after &session=spec- on a JBrowse Web link that loads that config.

              {
  "views": []
}

              The same view with jbrowse-anywidget, from the config the figure loads. Swap a track's uri for your own file.

              from jbrowse_anywidget import JBrowseApp, fetch_hub

config = fetch_hub("https://jbrowse.org/code/jb2/main/test_data/config_demo.json")
app = JBrowseApp(
    assemblies=config["assemblies"],
    tracks=config.get("tracks", []),
    views=[],
)
app  # 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": []
}
JSON

npx @jbrowse/capture --instance https://jbrowse.org/code/jb2/main/ \
  --config https://jbrowse.org/code/jb2/main/test_data/config_demo.json \
  --width 1500 --height 800 \
  --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 ↗

              Open this view in JBrowse Desktop ↗

              Opens JBrowse Desktop (JBrowse Desktop 5.0+) at this view and saves it as a reopenable session.

              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

              With your own data, the steps behind the figure:

              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 Web ↗

              Its genome and tracks are hosted, so File → Open track... there adds your own files beside them.

              With your own data, the steps behind the figure:

              1. Put your genome in your JBrowse Web's config.json: jbrowse add-assembly adds it.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.

              This session spec draws the figure from test_data/config_demo.json: paste it after &session=spec- on a JBrowse Web link that loads that config.

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

              The same view with jbrowse-anywidget, from the config the figure loads. Swap a track's uri for your own file.

              from jbrowse_anywidget import JBrowseApp, fetch_hub

config = fetch_hub("https://jbrowse.org/code/jb2/main/test_data/config_demo.json")
app = JBrowseApp(
    assemblies=config["assemblies"],
    tracks=config.get("tracks", []),
    views=[
        {
            "type": "LinearGenomeView",
            "assembly": "hg19",
            "loc": "chr1:1,000,000-1,100,000",
            "tracks": [
                "ncbi_gff_hg19"
            ]
        }
    ],
)
app  # display the widget

              jbrowse-img draws the same view as an SVG, from the command line and without a browser. Point --config at your own config, or swap a track for your own file with --bam, --vcfgz and the other file flags.

              npx @jbrowse/img --config https://jbrowse.org/code/jb2/main/test_data/config_demo.json \
  --assembly hg19 --loc chr1:1,000,000-1,100,000 \
  --track ncbi_gff_hg19 \
  --width 1200 --out figure.svg

              --out figure.png writes a PNG instead, through rsvg-convert (apt install librsvg2-bin, brew install librsvg).

              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 \
  --width 1200 --height 620 \
  --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 ↗

              Open this view in JBrowse Desktop ↗

              Opens JBrowse Desktop (JBrowse Desktop 5.0+) at this view and saves it as a reopenable session.

              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

              With your own data, the steps behind the figure:

              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 Web ↗

              Its genome and tracks are hosted, so File → Open track... there adds your own files beside them.

              With your own data, the steps behind the figure:

              1. Put your genome in your JBrowse Web's config.json: jbrowse add-assembly adds it.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.

              This session spec draws the figure from test_data/volvox/config.json: paste it after &session=spec- on a JBrowse Web link that loads that config.

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

              The same view with jbrowse-anywidget, from the config the figure loads. Swap a track's uri for your own file.

              from jbrowse_anywidget import JBrowseApp, fetch_hub

config = fetch_hub("https://jbrowse.org/code/jb2/main/test_data/volvox/config.json")
app = JBrowseApp(
    assemblies=config["assemblies"],
    tracks=config.get("tracks", []),
    views=[
        {
            "type": "LinearGenomeView",
            "assembly": "volvox",
            "loc": "ctgA:1-20000",
            "tracks": [
                "volvox_bam"
            ]
        }
    ],
)
app  # display the widget

              jbrowse-img draws the same view as an SVG, from the command line and without a browser. Point --config at your own config, or swap a track for your own file with --bam, --vcfgz and the other file flags.

              npx @jbrowse/img --config https://jbrowse.org/code/jb2/main/test_data/volvox/config.json \
  --assembly volvox --loc ctgA:1-20000 \
  --track volvox_bam \
  --width 1000 --out figure.svg

              --out figure.png writes a PNG instead, through rsvg-convert (apt install librsvg2-bin, brew install librsvg).

              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 \
  --width 1000 --height 600 \
  --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 are held in your session, where undo and Reset track settings reach them. Admin → Save track settings to config writes them into the config file every visitor is served.

              Setting a default session

              A new visitor sees the default session 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 ↗

              Open this view in JBrowse Desktop ↗

              Opens JBrowse Desktop (JBrowse Desktop 5.0+) at this view and saves it as a reopenable session.

              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

              With your own data, the steps behind the figure:

                Open this view in JBrowse Web ↗

                Its genome and tracks are hosted, so File → Open track... there adds your own files beside them.

                With your own data, the steps behind the figure:

                  This session spec draws the figure from test_data/empty.json: paste it after &session=spec- on a JBrowse Web link that loads that config.

                  {
  "views": []
}

                  The same view with jbrowse-anywidget, from the config the figure loads. Swap a track's uri for your own file.

                  from jbrowse_anywidget import JBrowseApp, fetch_hub

config = fetch_hub("https://jbrowse.org/code/jb2/main/test_data/empty.json")
app = JBrowseApp(
    assemblies=config["assemblies"],
    tracks=config.get("tracks", []),
    views=[],
)
app  # 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": []
}
JSON

npx @jbrowse/capture --instance https://jbrowse.org/code/jb2/main/ \
  --config https://jbrowse.org/code/jb2/main/test_data/empty.json \
  --width 1000 --height 480 \
  --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