Skip to main content
Pre-release

This release is a pre-release and may not be stable for production use.

Refgenie 1.0

Run tests PyPI Python versions License: BSD-2-Clause

⚠️ This is an alpha release

Refgenie 1.0 is an alpha. It works, but commands and data can still change, so pin the version in production pipelines (for example, refgenie==1.0.0a2). A future alpha may require you to rebuild your assets. Please do try it and report what breaks.

Refgenie is a reference genome asset manager. It organizes, builds, and serves the reference genome files that bioinformatics workflows use, such as FASTA files, aligner indexes, and annotations, and gives each one a stable identifier you can resolve from a script.

Features

  • Modular asset system: manage different types of reference genome assets (FASTA, BWA index, etc.)
  • Content-addressed assets: an asset's digest is derived from the files it contains
  • Seqcol genome identity: genomes are identified by GA4GH refget sequence-collection digests
  • Database backend: SQLite or PostgreSQL for asset metadata, with alembic migrations
  • Data channels: register and sync asset classes and recipes from external sources
  • Server and web UI: a REST API (with GA4GH DRS endpoints) and a local web UI
  • MCP server: expose refgenie to LLM agents over the Model Context Protocol
  • Self-describing to agents: every instance serves /SKILL.md, a capability doc that teaches an assistant this instance's HTTP API
  • Command-line interface: build, seek, pull, push, and manage genome assets

Installation

Refgenie 1.0 is a pre-release, so tell pip to accept it:

pip install "refgenie>=1.0.0a2"

Without the version, pip install refgenie installs the legacy 0.13 release.

Optional extras

The base install gives you the CLI and the Python API. Everything else is an extra:

Extra Install What it enables Adds
(none) pip install "refgenie>=1.0.0a2" CLI, Python API, building, pulling, staging —
dash pip install "refgenie[dash]>=1.0.0a2" refgenie dash, the local web UI fastapi, uvicorn
server pip install "refgenie[server]>=1.0.0a2" refgenie serve, the public REST API + DRS + /mcp endpoint (includes dash and mcp) apscheduler, mcp
mcp pip install "refgenie[mcp]>=1.0.0a2" refgenie-mcp, the stdio MCP server for LLM agents mcp
snakemake pip install "refgenie[snakemake]>=1.0.0a2" snakemake-based bulk asset building snakemake, peppy

Running refgenie serve, refgenie dash, or refgenie-mcp without its extra prints which extra to install. PostgreSQL support is included in the base install.

Quick Start

pip install "refgenie>=1.0.0a2"
refgenie init                                # create the database; subscribe to api.refgenie.org
refgenie pull hg38/fasta_index               # about 12 KB: hg38's .fai and chrom sizes
refgenie seek hg38/fasta_index.chrom_sizes   # print the local path

refgenie listr lists everything you can pull, and refgenie seek gives your pipelines a path that works on any machine.

Build assets for your own genome

Building needs recipes from a data channel:

refgenie data-channel add refgenie https https://refgenie.github.io/refgenie-registry/index.yaml
refgenie data-channel sync refgenie --exists-ok
refgenie genome init --fasta genome.fa.gz --name genome_name   # also builds its fasta asset
refgenie build genome_name/bowtie2_index                       # needs bowtie2 installed
refgenie seek genome_name/fasta

refgenie list then prints something like:

                      Refgenie assets. Source: local
┏━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━┳━━━━━━━━━┓
┃ Aliases     ┃ Genome digest                    ┃ Asset group ┃ Asset   ┃
┡━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━╇━━━━━━━━━┩
│ genome_name │ jthDpfNIgzM5AGJlOkRtfnky4rXMBIUP │ fasta       │ default │
└─────────────┴──────────────────────────────────┴─────────────┴─────────┘

Environment variables

All are optional. Refgenie uses defaults under ~/.refgenie/ when they are unset.

Variable Default Purpose
REFGENIE_HOME_PATH ~/.refgenie Root directory for refgenie files. Auto-created at first import.
REFGENIE_DB_CONFIG_PATH $REFGENIE_HOME_PATH/refgenie_db_config.yaml Path to the database connection YAML.
REFGENIE_GENOME_FOLDER $REFGENIE_HOME_PATH/genomes Where built asset files live. Auto-created on refgenie init.
REFGENIE_GENOME_STAGE_FOLDER $REFGENIE_HOME_PATH/archives Where staged/archived assets live before push. Auto-created on refgenie init.
REFGENIE_SUBSCRIBE_DEFAULT_SERVER true Whether refgenie init subscribes a new configuration to https://api.refgenie.org.
REFGENIE_BRIDGE_MODE read Localhost bridge policy for refgenie dash. off = no cross-origin access; read = allowlisted public origins may read /ping, /v4, /v1/jobs; full = additionally allows POST /v1/actions/pull. refgenie dash --bridge overrides it for one run.
REFGENIE_BRIDGE_ORIGINS https://refgenie.org Comma-separated exact origins the bridge admits. Replaces the default rather than appending.
REFGENIE_BRIDGE_ORIGIN_REGEX unset Origin regex, for SPA dev servers and preview deployments only. Wildcard-equivalent patterns are refused at startup.
REFGENIE_BRIDGE_EXPOSE_PATHS false Whether /ping may report the genome folder path. Off by default: a home-directory path leaks the OS username to every allowlisted origin.
REFGENIE_WEB_DIST unset Override the built web UI directory. Default is the packaged refgenie/server/webui/.
REFGENIE_LOG_LEVEL WARNING Python logging level.
REFGENIE_ENCRYPTION_KEY (auto-generated, dev only) Fernet key for encrypting credentials. Set explicitly in production.
REFGENIE_DISABLE_PLUGINS unset 1/true/all turns off every plugin; a comma-separated list of plugin names turns off those. Wins over everything else.
REFGENIE_SERVER_PLUGINS false Run plugins in server mode (refgenie serve). Off by default; local mode and refgenie dash always run them.
REFGENIE_CONTAINER_ENGINE auto What runs a recipe's container image: docker, apptainer, or auto (Docker when its daemon answers, else Apptainer).
REFGENIE_APPTAINER_CACHEDIR unset Passed to Apptainer as APPTAINER_CACHEDIR, so image pulls land there instead of under $HOME.

Upgrading from refgenie 0.x? See the upgrade guide.

Usage

For a complete list of commands:

refgenie --help

Longer walkthroughs:

Data Channels

Refgenie ships with no recipes or asset classes. A data channel is an index of them that you register and sync; the canonical one is published by refgenie-registry.

You need a data channel to build assets. To pull assets, refgenie pull gets each asset's class from the server it pulls from.

# Add a data channel: <name> <type> <index url>
refgenie data-channel add refgenie https https://refgenie.github.io/refgenie-registry/index.yaml

# Sync its asset classes and recipes into your local database
refgenie data-channel sync refgenie --exists-ok

# See what you have
refgenie recipe list
refgenie asset-class list

Recipes contain commands, and building an asset runs them. Only sync channels you trust.

Server, dashboard, and MCP

# Local web UI (needs the 'dash' extra)
refgenie dash

# Public REST API, including GA4GH DRS endpoints and an /mcp endpoint
# (needs the 'server' extra)
refgenie serve --port 8000

# stdio MCP server for LLM agents (needs the 'mcp' or 'server' extra)
refgenie-mcp

With the server running, interactive API docs are at /docs and the OpenAPI document is at /openapi.json. /SKILL.md is the same API written for an AI assistant; both modes serve it. refgenie serve also serves an HTTP MCP endpoint (Streamable HTTP transport) at /mcp.

refgenie dash and refgenie serve are the same application in two modes: the same JSON API under /v4, the same web UI, and a local-only command surface under /v1 that only the dash has. The UI asks /service-info which mode it is talking to and shows only what that mode can do. refgenie dash binds 127.0.0.1 only; use refgenie serve for anything reachable over a network.

A wheel ships the built web UI. In a source checkout, build it once with npm --prefix frontend run build. Until then the API works and / explains what to run.

Development

This project uses uv for package management and Task for development tasks. See docs/refgenie/development.md for the full developer quickstart.

# Clone and install
git clone https://github.com/refgenie/refgenie.git
cd refgenie
uv sync

# Run tests
task test

# Format code
task reformat

# Run refgenie CLI
uv run refgenie <command>

Contributing

Contributions are welcome. Please read CONTRIBUTING.md for branch conventions, what a reviewable pull request looks like, and how to run both test suites, and docs/refgenie/development.md for the environment setup.

License

Refgenie is released under the BSD 2-Clause License. See LICENSE.txt.

Metadata

Release files for refgenie 1.0.0a2

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for refgenie 1.0.0a2
File Size Uploaded Provenance Actions
refgenie-1.0.0a2.tar.gz 3.1 MB With provenance Details for refgenie-1.0.0a2.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for refgenie 1.0.0a2
File Interpreter ABI Platform Actions
refgenie-1.0.0a2-py3-none-any.whl Python 3 none any Details for refgenie-1.0.0a2-py3-none-any.whl

Total release size: 6.2 MB

Release files / refgenie-1.0.0a2.tar.gz

Download URL refgenie-1.0.0a2.tar.gz
Size 3.1 MB
Tags Source
SHA-256 checksum
How to use checksums
8409382da567023a1229b648bdc85569b272a9b8939ea5b6bc5a4a3632f282fa
BLAKE2b-256 checksum
How to use checksums
c9307d3e27f47882afdcf0f7d324fe10ac274010484645f027abe67ebaa9be37
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 14, 2026.

Transparency log

Release files / refgenie-1.0.0a2-py3-none-any.whl

Download URL refgenie-1.0.0a2-py3-none-any.whl
Size 3.1 MB
Tags Python 3
SHA-256 checksum
How to use checksums
a6836aa8fc0e7807ec7d7b1d12dbbdc27de217fafe5bd059a6b0c89841c44063
BLAKE2b-256 checksum
How to use checksums
472e70dddd09bca87badc97c6e141679886a296aeeb4c1e6e0d39fcc58fa5106
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 14, 2026.

Transparency log

Security for refgenie 1.0.0a2

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for refgenie-1.0.0a2.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 14, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page