Skip to content
Refgenie

Connect the public web UI to your local refgenie

The public refgenie web UI at https://ui.refgenie.org can connect to a refgenie dash running on your own computer. When connected, the page shows which catalog assets you already have on disk (“Local” badges), lets you browse your local genomes, and can hand a pull directly to your local refgenie — without you switching to a terminal.

This connection is called the localhost bridge. Everything stays on your machine: the public page talks to http://localhost:8080 directly from your browser, and no data about your local instance is sent anywhere else.

Using it

Section titled “Using it”

  1. Start your dashboard locally:

     refgenie dash

  2. Open https://ui.refgenie.org, and click Connect local refgenie (in the sidebar, or the card on the Genomes page).

  3. Confirm the port (default 8080, matching refgenie dash) and click Connect.

Chrome (version 142 and later) will show a one-time permission prompt asking whether the site may access devices on your local network — that prompt is about your own refgenie dash, and the connection only works if you allow it. If you denied it by accident, re-enable it from the site settings icon in the address bar.

Once connected, the page remembers the connection and re-checks it silently on later visits. Click Disconnect in the sidebar to forget it.

Bridge modes

Section titled “Bridge modes”

How much the public page may do is controlled by the bridge mode on your local refgenie:

ModeWhat an allowlisted page may do
offNothing. No cross-origin access at all.
read (default)See that your refgenie is running, and read what it has (genomes, assets, job status).
fullAdditionally submit a pull (“Pull to my refgenie” on asset pages).

Set it for one run:

refgenie dash --bridge full

or persistently with the environment variable REFGENIE_BRIDGE_MODE.

Even under full, only pull is available cross-origin. Deleting assets, managing aliases, building, and every other state change can only be done from the local dashboard itself (http://localhost:8080) — the remote page links you there instead.

Related settings:

  • REFGENIE_BRIDGE_ORIGINS — comma-separated origins allowed to connect (default https://ui.refgenie.org).
  • REFGENIE_BRIDGE_ORIGIN_REGEX — optional regex for extra origins (for UI development and preview deployments). A careless regex here disables the origin allowlist entirely — leave it unset unless you know why you need it.
  • REFGENIE_BRIDGE_EXPOSE_PATHS — default false; when true, the connection handshake reveals your genome folder path to allowlisted origins (paths can leak your OS username, so this is off by default).

Safari

Section titled “Safari”

Safari blocks HTTPS pages from talking to servers on your own computer (WebKit bug 171934), so the bridge does not work there and the page will say so instead of trying. Open your local dashboard directly at http://localhost:8080 — it runs the same interface.

Troubleshooting

Section titled “Troubleshooting”

If the page cannot connect, check:

  • Is refgenie dash actually running?
  • Did you allow the browser’s local-network permission prompt?
  • Is the dash on a different port? Enter it in the connect dialog.
  • Is your refgenie too old? The bridge needs a version that serves /ping.
  • Is the bridge disabled? Check REFGENIE_BRIDGE_MODE (or --bridge).

Security notes (what the bridge does and does not protect)

Section titled “Security notes (what the bridge does and does not protect)”

The bridge is designed so that visiting a random website never gives that website control over your local refgenie:

  • Only allowlisted origins can read anything (CORS); everything else is refused, and a Host-header guard blocks DNS-rebinding tricks.
  • State-changing requests additionally require a custom header (which forces a browser preflight) and are refused cross-origin unless you opted into --bridge full — and even then, only pull.
  • No cookies, tokens, or credentials exist anywhere in the exchange.

Two honest non-goals to be aware of:

  • The local dashboard is unauthenticated. The trust boundary is your machine: anyone with shell access to it controls your refgenie regardless of bridge settings. Do not run refgenie dash on a shared multi-user machine.
  • The page cannot verify what answers on the port. Any local process could impersonate a refgenie; local data is therefore always displayed clearly labeled as local, never silently merged into catalog results.