Container Quickstart¶

The published image runs the whole of Codaris: the web studio on port 3000, the REST API on port 8000, and the toolchain the compiler calls.

Nextflow 25.10.4 on Java 17 (OpenJDK, default-jre-headless)
nf-core 4.1.0 and nf-test 0.9.5
Python 3.11 with the backend dependencies and a CPU build of PyTorch
Primeomicx/nf-pilot decision-model weights, cached for offline use
samtools, seqtk, pigz, and the Docker CLI
The five versioned stores (container index, process registry, tool parameters, RAG store, test-asset cache), verified against stores_manifest.json when the image is built

Images are published for linux/amd64 and linux/arm64, so the same tag runs on x86_64 servers and on Apple Silicon.

1. Pull the image¶

docker pull ghcr.io/primeomicx/codaris:latest

Release tags (ghcr.io/primeomicx/codaris:v1.0.0) pin a version; latest follows the newest release.

2. Run the web studio¶

docker run -d --name codaris \
  -p 127.0.0.1:3000:3000 -p 127.0.0.1:8000:8000 \
  -e HOME="${HOME}" \
  -v "${HOME}/.codaris:${HOME}/.codaris" \
  -v "${HOME}/projects:${HOME}/projects" \
  -v /var/run/docker.sock:/var/run/docker.sock \
  ghcr.io/primeomicx/codaris:latest

Flag	Purpose
`-e HOME="${HOME}"`	The backend keeps chats, settings, keys, runs, and session workspaces under `~/.codaris`. Passing `HOME` makes that the mounted directory, so the state survives `docker rm`. `CODARIS_HOME=/some/path` names the directory explicitly instead.
`-v "${HOME}/.codaris:${HOME}/.codaris"`	The state directory, at the same path inside and outside the container.
`-v "${HOME}/projects:${HOME}/projects"`	The folder the agent may read and write pipelines in. Mount your whole home (`-v "${HOME}:${HOME}"`) when you want every project reachable.
`-v /var/run/docker.sock:/var/run/docker.sock`	The host Docker engine. The build → run → fix loop runs every test with `-profile docker` on it, so without the socket each test run stops at the readiness check (the container's startup log says so). Compile, lint, and `-stub-run` checks work without it.

Then open http://localhost:3000 and add a model API key under Customizations. Each key is checked against its provider and saved to ~/.codaris/settings.json. Keys can also be passed as environment variables (OPENAI_API_KEY, ANTHROPIC_API_KEY, GEMINI_API_KEY, PERPLEXITY_API_KEY).

Endpoint	URL
Web studio	http://localhost:3000
In-app documentation	http://localhost:3000/docs
OpenAPI reference	http://localhost:8000/docs
Health and version	http://localhost:8000/health

The startup log prints the resolved state directory (==> State directory: …) and a hint when HOME was left at /root.

3. The command line inside the image¶

The image's entrypoint starts the web studio and the API. The CLI is the same code, so run it with python -m app.cli and an overridden entrypoint. The host directory holding your pipelines is mounted at the same path it has on the host, which keeps the paths in the output usable:

docker run --rm -it \
  --entrypoint python \
  -e HOME="${HOME}" \
  -v "${HOME}/.codaris:${HOME}/.codaris" \
  -v "${PWD}:${PWD}" -w /app \
  -e OPENAI_API_KEY="${OPENAI_API_KEY}" \
  ghcr.io/primeomicx/codaris:latest \
  -m app.cli plan "ChIP-seq with Bowtie2 and MACS3 for paired-end reads" --out "${PWD}/chipseq_plan.json"

docker run --rm -it \
  --entrypoint python \
  -e HOME="${HOME}" \
  -v "${HOME}/.codaris:${HOME}/.codaris" \
  -v "${PWD}:${PWD}" -w /app \
  -e OPENAI_API_KEY="${OPENAI_API_KEY}" \
  ghcr.io/primeomicx/codaris:latest \
  -m app.cli build "${PWD}/chipseq_plan.json" --output-dir "${PWD}/pipelines" --use-defaults

docker run --rm -it \
  --entrypoint python \
  -e HOME="${HOME}" \
  -v "${HOME}/.codaris:${HOME}/.codaris" \
  -v "${PWD}:${PWD}" -w /app \
  -v /var/run/docker.sock:/var/run/docker.sock \
  ghcr.io/primeomicx/codaris:latest \
  -m app.cli test "${PWD}/pipelines/chipseq"

doctor, review, remediate, lint, and judge run the same way. Replace OPENAI_API_KEY with the key for the provider you use; the CLI commands page lists every option. The REPL (python -m app.cli chat) talks to the API, so it runs best from a shell on the host or with docker exec -it codaris python -m app.cli chat against a running studio container.

4. Docker Compose¶

The repository ships docker/docker-compose.unified.yml, which sets HOME, the symmetric mounts, the Docker socket, and the ports for you. From a clone:

git clone https://github.com/PrimeOmicX/codaris.git
cd codaris
cp backend/.env.example backend/.env    # optional: keys as environment variables
docker compose -f docker/docker-compose.unified.yml up -d

backend/.env is optional; the Compose file loads it when it exists and starts without it. The variables the file reads:

Variable	Default	Purpose
`CODARIS_IMAGE_TAG`	`latest`	The image tag to run; set it to a release tag such as `v1.0.0` to pin one.
`CODARIS_PROJECTS_DIR`	`${HOME}`	The host folder mounted for pipelines.
`CODARIS_HOST_DOCKER_SOCKET`	`/var/run/docker.sock`	The host Docker socket.

Stop and remove the stack with docker compose -f docker/docker-compose.unified.yml down; the state in ~/.codaris stays.

5. Platform notes¶

macOS and Docker Desktop¶

The host socket lives in your user directory. Point the mount at it:

docker run -d --name codaris \
  -p 127.0.0.1:3000:3000 -p 127.0.0.1:8000:8000 \
  -e HOME="${HOME}" \
  -v "${HOME}/.codaris:${HOME}/.codaris" \
  -v "${HOME}/projects:${HOME}/projects" \
  -v "${HOME}/.docker/run/docker.sock:/var/run/docker.sock" \
  ghcr.io/primeomicx/codaris:latest

With Compose, set CODARIS_HOST_DOCKER_SOCKET="${HOME}/.docker/run/docker.sock" before docker compose up.

Local models¶

The container reaches a model server on the host (Ollama, vLLM, LM Studio) through host.docker.internal. Set the base URL under Customizations, or pass it at start:

-e CODARIS_LOCAL_LLM_BASE_URL="http://host.docker.internal:11434/v1"

Hardware¶

The decision model runs on the CPU in the container. A GPU is not required for any part of Codaris; the heavy compute happens inside the biocontainers that Nextflow launches for a pipeline run.