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 pre-release software. The CLI, the Python API, the REST API, and the database schema can all change without a deprecation period, and a future alpha may require you to rebuild your assets. Do not depend on it in production pipelines yet. 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 --pre refgenie

Without --pre, pip 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 --pre refgenie CLI, Python API, building, pulling, staging —
dash pip install --pre "refgenie[dash]" refgenie dash, the local web UI fastapi, uvicorn
server pip install --pre "refgenie[server]" refgenie serve, the public REST API + DRS + /mcp endpoint (includes dash) apscheduler, mcp
mcp pip install --pre "refgenie[mcp]" refgenie-mcp, the stdio MCP server for LLM agents mcp
snakemake pip install --pre "refgenie[snakemake]" snakemake-based bulk asset building snakemake

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

# 1. Create the refgenie home, database, and genome folders
refgenie init

# 2. Register and sync a data channel, which supplies asset classes and
#    recipes (including the 'fasta' recipe)
refgenie data-channel add refgenie https https://refgenie.github.io/refgenie-registry/index.yaml
refgenie data-channel sync refgenie --exists-ok

# 3. Register a genome from a FASTA file. This also builds its fasta asset.
refgenie genome init --fasta genome.fa.gz --name genome_name

# 4. Build another asset for that genome (needs bowtie2 installed)
refgenie build genome_name/bowtie2_index

# 5. Inspect what you have, and get a path to it
refgenie list
refgenie seek genome_name/fasta

To download pre-built assets instead of building them, run refgenie pull hg38/fasta after refgenie init.

refgenie list 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_STORES unset JSON array of federated refget stores registered on server boot, e.g. [{"name": "jungle", "url": "https://.../jungle/", "priority": 10}]. Lower priority wins alias ties. See deployment/stores.example.json.
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 INFO 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.0a1

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.0a1
File Size Uploaded Provenance Actions
refgenie-1.0.0a1.tar.gz 510.4 kB With provenance Details for refgenie-1.0.0a1.tar.gz

Built distribution (wheel)

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

Total release size: 1.1 MB

Release files / refgenie-1.0.0a1.tar.gz

Download URL refgenie-1.0.0a1.tar.gz
Size 510.4 kB
Tags Source
SHA-256 checksum
How to use checksums
af1341663ed5b99739aa673d2ae71a121e78e342a7fd353a60b6365296ff9650
BLAKE2b-256 checksum
How to use checksums
9546094ee85d2afefc19b53b577f90f5ee31a6a380e993505b3639a1dc236d12
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 6, 2026.

Transparency log

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

Download URL refgenie-1.0.0a1-py3-none-any.whl
Size 588.2 kB
Tags Python 3
SHA-256 checksum
How to use checksums
e826eb29fe40dd5c6f0160471c4d8f55f6d06ca2413be94cffe87b6a273cded4
BLAKE2b-256 checksum
How to use checksums
a2d63a6bf72ce8dd4af4b92a55d8087402036be3fdde4080a37de9318e14ec2b
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 6, 2026.

Transparency log

Security for refgenie 1.0.0a1

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.0a1.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 6, 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