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 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.
Links
- Source code
- Issue tracker
- Changelog
- Documentation
- Data channel registry
- Upgrade guide (for refgenie 0.x users)
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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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 logRelease 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 logSecurity 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.
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 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.