Setup

Get Started

Choose your setup path and launch QUASAR.

Recommended

Docker

Best default for laptops and workstations. It gives you the cleanest setup story and keeps the runtime isolated from your host machine.

HPC

Singularity

Best fit for clusters and shared compute environments where container execution is available but Docker is not.

Advanced

Local Deployment

Useful when you need a custom environment on your machine, but it is less isolated and usually more fragile than container-based runs.

Prerequisites

Access to a supported model provider and a valid API key
Docker installed on your device (required for Docker-based deployments)
Node.js 18 or newer (required only if running the local interactive CLI outside of a container)

Note: QUASAR is currently optimised for Gemini-oriented setups. Other providers may work, but they are not yet the primary compatibility target.

Installation

Docker

Pull the appropriate QUASAR image for your system from Docker Hub:

docker pull fengxuyang/quasar:<tag>

Singularity

Build a .sif image from Docker Hub:

singularity build quasar.sif docker://fengxuyang/quasar:<tag>

Local Deployment

If you want to run QUASAR directly on your machine, install the Python package and the scientific software stack you need. A minimal example looks like this:

conda create -n quasar python=3.11 -y
conda activate quasar
conda install -c conda-forge qe lammps raspa3 raspalib -y
pip install --upgrade pip
pip install quasar-core

Launch QUASAR

Docker

docker run -it --rm \
  -v "<workspace_path>:/workspace" \
  fengxuyang/quasar:<tag> \
  quasar

Singularity

singularity exec --cleanenv \
  -B "<workspace_path>:/workspace" \
  --home "<workspace_path>:/workspace" \
  <tag>.sif quasar

Local Deployment

export WORKSPACE_DIR=<workspace_directory>
quasar

What to Expect on First Launch

When QUASAR starts in a new workspace for the first time, it prepares the local resources it needs for later runs.

This setup step can include:

Documentation repositories stored in docs/
A prebuilt RAG index in .rag_index/ when RAG is enabled
Embedding model files used for documentation retrieval

Because these resources are downloaded and prepared only once per new workspace, the first launch is usually slower than later runs in the same workspace.