Installation

Choose the installation method that best fits your environment.

Pip (Recommended)

The pip package is the easiest way to get CLIO Core. It ships a portable, self-contained build with everything statically linked, so no system dependencies are required beyond a standard C/C++ runtime (glibc) and Python 3.10+.

pip install iowarp-core

Verify the installation:

import iowarp_core
print(iowarp_core.get_version())

Start the Runtime

The package installs the clio_run CLI on your PATH:

clio_run start

A default ~/.clio/clio.yaml is seeded on first import so the runtime works out of the box. See the Quick Start for the next steps.

What's Included

The pip wheel ships the portable feature set:

• Python API — import iowarp_core and import clio_cee for the Context Exploration Engine
• CLI — clio_run command for runtime management
• Core engines — CLIO Runtime, CTE, CAE, CEE
• Shared libraries — every CLIO Runtime library bundled in the wheel; no system installs needed

When You'll Need a Source Build

Newer extensions and advanced/accelerated features are not in the portable wheel. Switch to one of the source-build methods below if you need:

• NVIDIA GPU (CUDA) or AMD GPU (ROCm) acceleration
• MPI for distributed multi-node deployment
• HDF5 scientific data ingestion
• ADIOS2 adapter for streaming analytics
• Compression backends (LibPressio, Blosc, etc.)
• FUSE adapter on macOS (the Linux and Windows wheels already ship clio_cte_fuse)
• Custom ChiMods you intend to compile against the C++ headers
• Sanitizer / debug builds for development

Conda

Prebuilt iowarp-core packages are published to the iowarp channel on Anaconda.org. Install Miniconda (if you don't already have conda), then install the package:

# Install Miniconda — Linux x86_64 shown; for other platforms use the matching
# installer from https://www.anaconda.com/download/success
curl -fsSL https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-x86_64.sh -o miniconda.sh
bash miniconda.sh -b -p "$HOME/miniconda3"
source "$HOME/miniconda3/etc/profile.d/conda.sh"

# Install iowarp-core (conda-forge supplies its dependencies)
conda create -n iowarp -c iowarp -c conda-forge iowarp-core
conda activate iowarp

Activate the environment in every new terminal with conda activate iowarp.

Build from source (optional)

To enable additional features (CUDA/ROCm/MPI) or build local changes, build the conda recipe yourself. IOWARP_PRESET selects a CMake preset:

git clone --recurse-submodules https://github.com/iowarp/clio-core.git
cd clio-core

# conda-build is a base-env plugin — install it there
conda install -n base -y conda-build -c conda-forge

# Common presets: release, debug, cuda-release, rocm-release
IOWARP_PRESET=release conda build installers/conda/ \
    -c conda-forge --output-folder build/conda-output

conda install -c conda-forge build/conda-output/*/iowarp-core-*.conda

Verify the installation

conda activate iowarp
clio_run --help

Docker

Pull and run the CLIO Core Docker image:

docker pull iowarp/deploy-cpu:latest

Run the container:

docker run -d -p 9413:9413 --memory=8g --name iowarp iowarp/deploy-cpu:latest clio_run start

Using Docker Compose

The image already ships the default config at /home/iowarp/.clio/clio.yaml and runs as the iowarp user, so the shortest working docker-compose.yml is just:

services:
  iowarp:
    image: iowarp/deploy-cpu:latest
    container_name: iowarp
    hostname: iowarp
    ports:
      - "9413:9413"
    mem_limit: 8g
    command: ["clio_run", "start"]
    restart: unless-stopped

In practice you want two more things: your own config, and a volume so the persistent tier, metadata log, and search index survive docker compose down (the default config writes all three under ~/.clio/).

services:
  iowarp:
    image: iowarp/deploy-cpu:latest
    container_name: iowarp
    hostname: iowarp
    volumes:
      - ./clio.yaml:/etc/iowarp/clio.yaml:ro
      - iowarp-state:/home/iowarp/.clio
    environment:
      - CLIO_SERVER_CONF=/etc/iowarp/clio.yaml
      - CTP_LOG_LEVEL=info
    ports:
      - "9413:9413"
    mem_limit: 8g
    command: ["clio_run", "start"]
    restart: unless-stopped

volumes:
  iowarp-state:

Mounting the config at /etc/iowarp/clio.yaml and pointing CLIO_SERVER_CONF at it keeps the config mount and the state volume from fighting over the same directory.

Start the service:

docker compose up -d
docker compose logs -f      # "SpawnWorkerThreads" means the runtime is up
docker compose down

info

CLIO Core uses memfd_create() for shared memory, so no special /dev/shm configuration is needed. Only mem_limit matters for resource control. See the Configuration Reference for details.

Spack

1. Install Spack (v0.22.3+ recommended):

git clone https://github.com/spack/spack.git -b v0.22.3
cd spack
. share/spack/setup-env.sh
echo ". ${PWD}/share/spack/setup-env.sh" >> ~/.bashrc

2. Add the IOWarp Spack repository (included in this repo):

git clone --recurse-submodules https://github.com/iowarp/clio-core.git
cd clio-core
spack repo add installers/spack

3. Install CLIO Core:

spack install iowarp

Next Steps

• Quick Start Tutorial — Start the runtime and run your first example
• Configuration Reference — Customize your deployment
• CLIO Kit — Explore MCP servers for AI agents