This release is a pre-release and may not be stable for production use.
Refgenie 1.0
⚠️ 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.
Links
- Source code
- Issue tracker
- Changelog
- Documentation
- Data channel registry
- Upgrade guide (for refgenie 0.x users)
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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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 logRelease 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 logSecurity 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.
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 logA 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.