> For the complete documentation index, see [llms.txt](https://help.connected.illumina.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.connected.illumina.com/annotation/v4.0/introduction/getting-started.md).

# Getting Started with local download

DRAGEN Annotation is written in C# using [.NET Core](https://www.microsoft.com/net/download/core) runtime environment, which is compatible with Windows, Linux, Mac OS X, and Docker images. Once .NET Core has been downloaded, all you need to do is obtain the compiled software and download the data files. Please see detailed instructions in the following sections.

{% hint style="info" %}
DRAGEN Annotation requires .NET8.0. Ensure that you have the required runtime installed from the [.NET Core downloads](https://www.microsoft.com/net/download/core) page.
{% endhint %}

{% hint style="info" %}
Refer to the [Prerequisite](/annotation/v4.0/introduction/prerequisite.md) section for instructions on generating the credential file required to run DRAGEN Annotation.
{% endhint %}

### Getting DRAGEN Annotation

#### Latest Release

Please visit [DRAGEN Annotation](https://developer.illumina.com/illumina-connected-annotations) to obtain the latest release. Place the downloaded ZIP file in the DragenAnnotation folder.

```bash
mkdir -p DragenAnnotation/Data
cd DragenAnnotation
unzip DragenAnnotation-4.0.0-net8.0.zip
```

#### Quick Start

Once setup and download are complete (see [Command Line Parameters](/annotation/v4.0/software-functionality/command-line-parameters.md)), run annotation on a test VCF:

```bash
dotnet Annotator.dll annotate \
  --config <dataDirectory>/runConfigs/<assembly>.<version>.premium.json \
  --input.file test.vcf.gz \
  --output.directory ./output
```

#### Docker

Obtain the docker image as a ZIP file (e.g. DragenAnnotation-4.0.0-net8.0-docker.tar.gz), and load it as follows:

```bash
docker load < DragenAnnotation-4.0.0-net8.0-docker.tar.gz
```

To build your own docker image, download the DRAGEN Annotation ZIP file, Dockerfile, docker image creation script (Dockerfile and script below):

{% file src="/files/S7fr0GLPvbboPxnzWfHH" %}

{% file src="/files/dnMLdwv2fL9kNFgLPbQu" %}

Place both files (`create_docker_image.sh` and `Dockerfile`) in the same directory.

In the terminal, navigate to the directory containing the scripts and execute the following commands:

```bash
chmod +x create_docker_image.sh
./create_docker_image.sh [path to zip file] [image tag]
```

After you run the script, the docker image will be available in your local machine with image name `dragen-annotations:[image tag specified]`.

We have special instructions for running DragenAnnotation (Here's a toy VCF in case you need it):

{% file src="/files/7jopM7mKd1Tfsc2hJPv7" %}

```bash
docker run --rm -it -v local/data/folder:/scratch dragen-annotations:v4.0.0 Annotator annotate \
     --config /scratch/runConfigs/GRCh37.20260501.premium.json \
     --input.file /scratch/HiSeq.10000.vcf.gz \
     --output.directory /scratch/output
```

{% hint style="warning" %}
Please note that there is a noticeable performance penalty when running DRAGEN Annotation in Docker as our data files are accessed through a Docker volume.
{% endhint %}

{% hint style="info" %}
For convenience, the user is encouraged to create aliases for the docker commands. For example:

```bash
alias DragenAnnotation="docker run --rm -it -v local/data/folder:/scratch dragen-annotations:v4.0.0 Annotator"
```

{% endhint %}

### Downloading the data files

Refer to [Prerequisite](/annotation/v4.0/introduction/prerequisite.md) for more details on creating Illumina API key to use DRAGEN Annotation and its utilities.

To download the latest data sources (or update the ones that you already have), run the interactive `setup` command. It will guide you through configuring your data directory, credentials, catalog, and assembly selections. At the end of setup, you can proceed directly to download:

```bash
dotnet Annotator.dll setup
```

The setup wizard will offer to download all configured data at the end. If you choose to skip the download during setup, you can always run it later:

```bash
dotnet Annotator.dll download --data.directory Data
```

Description of the available data sources is available in [Data Catalogs](/annotation/v4.0/data-sources/data-catalogs.md)

Refer to [Command Line Parameters](/annotation/v4.0/software-functionality/command-line-parameters.md) for more details on managing data sources and their versions.

**Glitches in the Matrix**

Every once in a while, the download process may encounter issues due to network interruptions or insufficient disk space. The downloader will perform integrity checks against the downloaded files. If you encounter errors, try resolving any potential causes and run the download command again.

{% hint style="info" %}
From time to time, you can re-run `Annotator download` to obtain the latest annotation files. It will only download files that have changed since the last download.
{% endhint %}

### Download a test VCF file

Here's a toy VCF file you can play around with:

{% file src="/files/7jopM7mKd1Tfsc2hJPv7" %}

```bash
curl -O https://illumina.github.io/IlluminaConnectedAnnotationsDocumentation/files/HiSeq.10000.vcf.gz
```

### Running DRAGEN Annotation

Once you have set up and downloaded the data, use the following command to annotate your VCF:

```bash
dotnet Annotator.dll annotate \
     --config Data/runConfigs/GRCh37.20260501.premium.json \
     --input.file HiSeq.10000.vcf.gz \
     --output.directory output
```

* the `--config` argument specifies the RunConfig JSON file (generated by `setup`)
* the `--input.file` argument specifies the input VCF path
* the `--output.directory` argument specifies the output directory

When running DRAGEN Annotation, performance metrics are shown as it evaluates the input VCF file:

```bash
---------------------------------------------------------------------------
DRAGEN Annotation                                   (c) 2026 Illumina Inc.
                             4.0.0+ffeb8ce05ca46c9a11b1f44d44debdb707f538d9
---------------------------------------------------------------------------

Data Source              Type                     Status    Comments
---------------------------------------------------------------------------
DANN                     Score                    Loaded    20200205
Ensembl                  GeneModels               Loaded    112
...
spliceAI                 SmallVariant             Loaded    2.0_filtered
---------------------------------------------------------------------------

Summary                                                Time         Percent
---------------------------------------------------------------------------
Initialization                                      00:00:11.7       84.9 %
Annotation                                          00:00:02.0       14.4 %
---------------------------------------------------------------------------
Gross Annotation rate:                                  718.84 positions/sec

Peak memory usage: 5.867 GB
Time: 00:00:13.8
```

The output will be a JSON file in the specified output directory. Here's an example JSON file:

{% file src="/files/pYGtLBVkfgfxb6EXtvCX" %}

### Full Command Line Reference

For complete documentation of all commands (`setup`, `download`, `annotate`, `list`, `version-validate`), options, and the RunConfig JSON schema, see [Command Line Parameters](/annotation/v4.0/software-functionality/command-line-parameters.md).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://help.connected.illumina.com/annotation/v4.0/introduction/getting-started.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.