Cluster

A Cordium Cluster runs on top of an existing Octelium Cluster. Before installing Cordium, you must have a working Octelium Cluster running on Kubernetes. See the Octelium installation guide here for production multi-node installations, or the quick installation guide here to install both Octelium and Cordium on a single machine in one step.

Preparing Kubernetes Nodes

Cordium Workspaces run inside ordinary Kubernetes pods managed by the Cordium controllers. Nodes that are allowed to host Workspaces must be explicitly labeled. For example, to allow a node named node-1 to host Cordium Workspaces:

kubectl label nodes node-1 octelium.com/node-mode-cordium=

In other words, Cordium only schedules Workspaces onto nodes explicitly labeled with octelium.com/node-mode-cordium. You can repeat this operation for multiple nodes or node pools if you want to dedicate several nodes to Workspaces. This separation is intentional and allows operators to isolate Workspaces from the Cordium control plane components, as well as from the Octelium control-plane and data-plane components running on the same Kubernetes cluster.

Since Workspaces run rootless nested containers with their own cgroup limits, we recommend nodes that run a recent Linux kernel with cgroup v2 enabled (e.g. Ubuntu 24.04 LTS or later, Debian 12+, or the default images of the major managed Kubernetes services).

Installing the Cordium Package

After preparing the Kubernetes nodes, you can install Cordium as an Octelium package using the octops install-package command as follows:

octops install-package <DOMAIN> --package cordium

You can override the kubeconfig path and pin a specific version explicitly:

octops install-package <DOMAIN> --package cordium --kubeconfig /path/to/kubeconfig --version <VERSION>

The package installs the Cordium components (read more here) and creates the following Octelium Services in the cordium Namespace along with the Cordium API in the octelium-api Namespace:

Service	Description
`default.cordium`	The web portal at `https://cordium.<DOMAIN>`, which also serves the Workspace applications at `https://<WORKSPACE>.cordium.<DOMAIN>`.
`default-ssh.cordium`	The SSH endpoint used by `cordium ssh` and `cordium cp`.
`default-cordium.octelium-api`	The Cordium gRPC API, reachable via `octelium-api.<DOMAIN>`.

Once installed, make sure that your Users are authorized to access these Services (read more here).

Upgrading

You can upgrade an already installed Cordium package to the latest version or to a specific version as follows:

octops install-package <DOMAIN> --package cordium --upgrade
# Or to a specific version
octops install-package <DOMAIN> --package cordium --upgrade --version <VERSION>

Storage

Cordium uses Kubernetes persistent storage for Workspace filesystems, Volumes, Template pre-builds and WorkspaceSnapshots. Storage is provisioned via a CSI driver and its StorageClass and VolumeSnapshotClass resources. Here is an overview of the requirements:

Feature	Requirement
Workspaces (persistent and ephemeral)	A `StorageClass` capable of dynamically provisioning `ReadWriteOnce` volumes. Required.
`EXCLUSIVE` Volumes	The same as above.
`SHARED` Volumes	A `StorageClass` capable of dynamically provisioning `ReadWriteMany` volumes (e.g. NFS, CephFS, AWS EFS, Azure Files or Longhorn RWX). Optional.
Template pre-builds and WorkspaceSnapshots	A CSI driver that implements the Kubernetes `VolumeSnapshot` API and a corresponding `VolumeSnapshotClass`. Optional.

StorageClass

Every Workspace, persistent or ephemeral, uses its own PersistentVolumeClaim. Since each Workspace attaches its claim to a single pod, block storage drivers such as Longhorn, AWS EBS CSI, GCP Persistent Disk CSI, Azure Disk CSI, Rook-Ceph RBD, and OpenEBS are a great fit. If the cluster has multiple StorageClasses, Cordium selects the one to use for a given Workspace or Volume via CEL rules configured in the ClusterConfig. This allows different storage tiers to be assigned to different Workspace types. For example, you can use fast NVMe-backed storage for interactive development Workspaces and standard block storage for ephemeral agent runs (read more here).

VolumeSnapshotClass

Template pre-builds work by snapshotting the fully initialized storage of a completed build Workspace and restoring from that snapshot on subsequent Workspace starts. WorkspaceSnapshots work the same way for any Workspace. Both require a CSI driver that implements the Kubernetes VolumeSnapshot API, the CSI snapshot controller and a corresponding VolumeSnapshotClass installed in the cluster.

Without snapshot support, Cordium installs and operates normally but pre-builds and WorkspaceSnapshots are unavailable. Block storage drivers that support VolumeSnapshot include Longhorn, AWS EBS CSI, GCP Persistent Disk CSI, Azure Disk CSI, and Rook-Ceph RBD. As with StorageClass, you can select the VolumeSnapshotClass dynamically via CEL rules in the ClusterConfig; otherwise Kubernetes picks the default VolumeSnapshotClass of the volume's CSI driver.

Post-Installation

Once Cordium is installed, we recommend the following steps:

Authorize your Users and Groups to use Cordium via Octelium Policies (read more here).
Review the ClusterConfig, especially the Space ownership rules, the per-User limits, the inactivity timeouts and the storage rules (read more here).
Optionally, configure an Octelium LLM Service for the Cordium Agent so that your Users can chat with it without bringing their own LLM subscriptions (read more here).
Install the CLI and follow the first steps guide.