Skip to content

CLI and Local Setup

Run Codaris from a source checkout when you want the command line or the web studio on your own Python, Java, and Nextflow. The container quickstart is the shorter route when Docker is available.

Prerequisites

  • Python 3.11 (the version the image and CI use)
  • Java 17 or newer for Nextflow
  • Nextflow: the validated version is 25.10.4; codaris doctor reports any other version with the known risks and keeps working
  • nf-core tools 4.1.0 (pip install "nf-core==4.1.0"); the scaffold, module installs, and lint call it
  • Docker (or Singularity or Apptainer) for the biocontainers a pipeline run launches
  • Git

seqtk is optional; codaris doctor lists it because test-data subsampling uses it when present.

1. Install the backend

git clone https://github.com/PrimeOmicX/codaris.git
cd codaris/backend
python3.11 -m venv .venv && source .venv/bin/activate
pip install torch --index-url https://download.pytorch.org/whl/cpu
pip install -r requirements.txt
pip install "nf-core==4.1.0"

The CPU build of PyTorch comes first so the decision model installs without the CUDA libraries. pip install -e . from the repository root installs only the codaris entry point; the CLI imports the backend package, so the requirements above are what make it run.

2. Install Nextflow

java -version
curl -s https://get.nextflow.io | bash
sudo mv nextflow /usr/local/bin/
nextflow -version

Pin the validated version with export NXF_VER=25.10.4 when you want the same Nextflow as the container.

3. Check the environment

cd ..            # the repository root
./bin/codaris doctor

bin/codaris finds the virtual environment and runs python -m app.cli with the backend on PYTHONPATH. doctor prints four sections: the binaries on PATH (nextflow, nf-core, docker, seqtk), the toolchain container state, the toolchain versions against the validated set, and the versioned stores. The exit code is 1 when Nextflow is missing or a store is absent or invalid; a version outside the validated set is a warning with the documented risk and the remedy, and it leaves the exit code alone.

Codaris doctor

Binaries on PATH:
  nextflow   /usr/local/bin/nextflow
  nf-core    /home/you/codaris/backend/.venv/bin/nf-core
  docker     /usr/bin/docker
  seqtk      — not found

Toolchain container: off (CODARIS_TOOLCHAIN_CONTAINER unset) — using host PATH

Toolchain versions:
  nextflow   25.10.4      ok  validated
  ...

codaris doctor --json prints the same findings as one JSON object.

The versioned stores (the container index and the knowledge stores) are release artifacts rather than files in the repository. Fetch them once:

./bin/codaris stores fetch

The release is public, so the download needs no credentials. With GH_TOKEN or GITHUB_TOKEN set, each asset is resolved through the GitHub API with the token, which raises the API rate limit. codaris stores check verifies the local copies against the manifest's sha256 values.

4. Start the web studio

./bin/codaris web                     # the API on http://127.0.0.1:8000
cd frontend && pnpm install && pnpm dev   # the studio on http://localhost:3000

web starts the FastAPI backend with uvicorn (--host, --port, and --reload are accepted). The studio is a Next.js app; in development it proxies /api and /health to the backend named by CODARIS_BACKEND_URL (default http://127.0.0.1:8000), so the browser talks to one origin. Open http://localhost:3000 and add a model API key under Customizations.

5. Use the command line

./bin/codaris plan "Bulk RNA-seq for human paired-end FASTQ with STAR, Salmon, and MultiQC" \
  --interactive --out build_plan.json
./bin/codaris build build_plan.json --output-dir ./pipelines
./bin/codaris test ./pipelines/rnaseq
./bin/codaris review ./pipelines/rnaseq

./bin/codaris with no arguments opens the REPL, which streams turns to the running API (CODARIS_API_URL, default http://127.0.0.1:8000). The CLI commands and REPL pages describe every verb and slash command.

6. Keep state in one place

Everything Codaris remembers lives under one directory: chats, settings.json with the keys and routing, runs.db, the unpacked test-asset cache, and session workspaces. The directory is ~/.codaris, or the path in CODARIS_HOME when that is set. The versioned stores sit beside the code in backend/app/engine/.

export CODARIS_HOME="$HOME/work/codaris-state"