cordium

Cordium is a free and open source, self-hosted, identity-based sandbox platform built on Kubernetes and Octelium. It provides isolated, reproducible general-purpose sandboxes for developers, AI agents, and automated workloads that are accessible through web terminals, SSH, CLI, and gRPC APIs.

What sets Cordium apart is how sandboxes access infrastructure. Instead of injecting credentials into the sandbox, every sandbox runs with a dedicated Octelium identity. Authorized databases, SSH servers, HTTP APIs, Kubernetes clusters, and internal services are accessed through Octelium’s identity-aware, secretless access platform, so API tokens, passwords, SSH private keys, kubeconfigs, and other long-lived credentials do not need to be placed inside the sandbox.

Table of Contents

• Main Features
• Core Concepts
• Workspace Configuration
• Access Methods
• CLI Usage
• Install CLI
• Install your First Cluster
• Comparison with Other Platforms
• License

Main Features

• Unified platform for humans and AI agents. Every sandbox (i.e. Workspace) is an isolated, rootless container sandbox running on standard Kubernetes, accessible via browser terminal, SSH, CLI, and gRPC API. Workspaces can be persistent (filesystem preserved across restarts) or ephemeral and can stop automatically when their tasks complete. The same platform can be used for long-lived coding sessions (e.g. via VSCode, Zed, etc.) and short-lived automated workloads (e.g. AI agent tasks, CI/CD, etc.).

• Declarative, reproducible environments. Workspace environments are defined in YAML specs covering the container image, repository cloning, lifecycle tasks, environment variables, resource limits (i.e. CPU, memory, storage), variable substitution, and application ports. Templates allow a single configuration to be reused across many Workspaces. Pre-built Templates capture a fully initialized filesystem as a Kubernetes VolumeSnapshot, reducing cold startup from minutes to seconds.

• Secretless access to infrastructure. Workspaces access databases, SSH servers, HTTP APIs, Kubernetes clusters, and mTLS-protected services without credentials ever reaching the Workspace. API keys, passwords, SSH private keys, and kubeconfigs are held at the Octelium identity-aware proxy and injected at the protocol layer if the Workspace identity is authorized. The Workspace itself does not hold credentials, eliminating credential sprawl for both developers and AI agents.

• Identity-based access control and observability. Every Workspace has an Octelium Session that represents its identity. Infrastructure access is governed by per-request, L7-aware attribute-based access control (ABAC) with policy-as-code using CEL and OPA, enforcing zero standing privileges by default. Authentication supports any OIDC or SAML 2.0 identity provider (IdP), GitHub OAuth2, workload OIDC assertions, and native FIDO2, WebAuthn, and TOTP.

• OpenTelemetry-native auditing and visibility. Real-time, identity-based, L7-aware visibility and access logging. Every request is logged and exported to your OpenTelemetry OTLP receivers for integration with log management and SIEM providers.

• Purpose-built for AI agents. Every agent run gets a dedicated Octelium identity and a clean, isolated Workspace with enforced resource limits and no state bleed between runs. Agents access databases, APIs, and internal services through their Workspace identity with no credential injection, so a compromised or misbehaving agent cannot exfiltrate credentials that were never present. Ephemeral storage and auto-stop on task completion require no manual cleanup. Pre-built Templates with agent frameworks pre-installed start in seconds via snapshot restoration.

• Open source and self-hosted. Cordium is fully open source under Apache-2.0. It runs on any Kubernetes cluster, from a single-node VM to production multi-node installations, cloud or on-premises. There is no proprietary control plane, no tiered feature set, and no vendor lock-in.

Concepts

• Space is the top-level namespace in Cordium. It groups Templates, Workspaces, Secrets, and GitProviders under a single organizational unit.
• Workspace (synonymous with sandbox) is the fundamental execution unit in Cordium. It is an isolated, rootless container-based environment that can be used interactively or programmatically via web-based console, cordium CLI, standard SSH, and gRPC-based APIs.
• Template defines a reusable Workspace configuration within a Space. When a Workspace is created, it is initialized from the selected Template's spec. Every Space has a default Template created automatically. A Template's spec shares most of Workspace spec (image, runtime, etc.) as well as an optional GitProvider association. Templates support pre-builds via Kubernetes VolumeSnapshot to reduce startup time from minutes to seconds for dependency-heavy Templates.
• Secrets represents a sensitive value (API keys, tokens, passwords, certificates) stored within a Space. Secrets are referenced by name in Template specs.

Workspace Configuration

Workspace and Template specs are defined in YAML and applied via cordium run --file spec.yaml or cordium create template --file spec.yaml. Here is a minimal example:

spec:
  image:
    registry:
      url: python:3.12-bookworm

  repository:
    url: https://github.com/myorg/my-project

  runtime:
    tasks:
      - name: install
        type: ON_CREATE
        workingDir: /workspace/repo
        run: pip install -r requirements.txt
        onFailure: ON_FAILURE_ABORT

Here is a more comprehensive example:

spec:
  image:
    dockerfile:
      inline: |
        FROM node:22-bookworm

        ENV DEBIAN_FRONTEND=noninteractive

        RUN apt-get update -qq && \
            apt-get install -y --no-install-recommends \
              podman \
              postgresql-client \
              curl \
              git \
            && rm -rf /var/lib/apt/lists/*

        RUN npm install -g @anthropic-ai/claude-code

  repository:
    url: https://github.com/myorg/api-service
    cloneOptions:
      branch: ${{ vars.BRANCH }}
      depth: 1

  vars:
    - name: BRANCH
      value: main
    - name: TASK
      value: "Review the codebase and fix any failing tests."

  runtime:
    autoStop: true
    envVars:
      - key: NODE_ENV
        value: test
      - key: SENTRY_DSN
        fromSecret: sentry-dsn

    tasks:
      - name: install-dependencies
        type: ON_CREATE
        workingDir: /workspace/repo
        run: npm ci
        onFailure: ON_FAILURE_ABORT

      - name: start-postgres
        type: POST_START
        runAsRoot: true
        run: |
          podman rm -f workspace-postgres 2>/dev/null || true
          podman run \
            --name workspace-postgres \
            --net host \
            -e POSTGRES_PASSWORD=password \
            -e POSTGRES_DB=app \
            -d docker.io/postgres:16

          for i in $(seq 1 30); do
            pg_isready -h localhost -p 5432 -U postgres && break
            sleep 2
          done

      - name: run-tests
        type: POST_START
        workingDir: /workspace/repo
        run: npm test
        onFailure: ON_FAILURE_CONTINUE

      - name: run-agent
        type: POST_START
        workingDir: /workspace/repo
        run: claude "${{ vars.TASK }}"

  limit:
    cpu:
      millicores: 4000
    memory:
      megabytes: 8192
    storage:
      megabytes: 20480

Access Methods

Web Portal

The Cordium web portal is a browser-based interface for managing and interacting with Workspaces without installing any software. It is the primary interface for users and teams who want clientless access to their Workspaces. The Octelium web portal authenticates users through Octelium's IdentityProviders, including GitHub OAuth2 or any OpenID Connect or SAML 2.0 IdP (read more here) or directly via Passkeys (read more here).

[!NOTE]
You can a watch a short demo video for the Cordium web portal here.

CLI Usage

The cordium CLI provides full command-line access to Workspace management. Here are some examples:

export OCTELIUM_DOMAIN=example.com
# Create from the default Template and attach a terminal
cordium run

# Attach to an existing Workspace (starts it if stopped)
cordium run abc

# Create from a specific Template
cordium run --template ml-env.my-project

# Create from a YAML configuration file
cordium run --file workspace.yaml

# Create from a container image
cordium run --image python:3.11-slim

# Create from a Dockerfile
cordium run --dockerfile ./Dockerfile

# Create from a git repository, cloning a specific branch
cordium run --repository https://github.com/myorg/my-project --branch develop

# Create in a specific Space using that Space's default Template
cordium run --space my-project

# Create an ephemeral Workspace
cordium run --ephemeral

# Create an ephemeral Workspace that is deleted when the terminal session ends
cordium run --ephemeral --rm

# Ephemeral AI agent sandbox with resource limits and a secret
cordium run --ephemeral --rm \
  --image python:3.11-slim \
  --env-from-secret ANTHROPIC_API_KEY=anthropic-key \
  --cpu 2000 --memory 4096

# Set environment variables
cordium run --image node:20 -e NODE_ENV=development -e PORT=3000

# Source a variable from a Space Secret
cordium run --template backend.my-project \
  --env-from-secret DATABASE_URL=staging-db-url

# Clone the primary repository and an additional repository with vars
cordium run --repository https://github.com/myorg/api-service \
  --additional-repo shared-lib=https://github.com/myorg/shared-lib \
  --var SERVICE=services/payments \
  --var BRANCH=main


# Open a Workspace terminal
cordium terminal abc
cordium term abc          # short alias

# Run a command and propagate exit code
cordium exec abc -- make test

# Run in a specific working directory
cordium exec abc -w /workspace/repo -- go build ./...

# Run as root
cordium exec abc --root -- apt-get install -y ripgrep

# Set per-command environment variables
cordium exec abc -e GOOS=linux -e GOARCH=amd64 -- go build ./...

# Capture remote output locally
cordium exec abc -- cat /workspace/repo/output.json > local.json

# Interactive SSH session via an embedded SSH client in the cordium CLI
cordium ssh abc

# Run a remote command via SSH
cordium ssh abc -- uptime

# Local port forwarding
cordium ssh abc -L 5432:localhost:5432

# Multiple port forwards without a shell
cordium ssh abc -N -L 5432:localhost:5432 -L 6379:localhost:6379

# Dynamic SOCKS5 proxy
cordium ssh abc -D 1080 -N

# Connect to the Octelium Cluster for native SSH
octelium connect -d

# Generate an SSH config block for use with VS Code, JetBrains, Zed, rsync
cordium ssh abc --print-config >> ~/.ssh/config

# Then use VS Code Remote SSH
code --remote ssh-remote+cordium-abc /workspace/repo

# You can also use other tools such as rsync
rsync -avz ./dist/ cordium-abc:/workspace/repo/dist/

# Copy a local file to a Workspace
cordium cp ./config.json abc:/workspace/repo/config.json

# Copy a file from a Workspace to local
cordium cp abc:/workspace/repo/output.csv ./output.csv

# Copy directories recursively
cordium cp -r ./src/ abc:/workspace/repo/src/

# Copy between two Workspaces
cordium cp abc:/workspace/repo/model.pt def:/workspace/repo/model.pt


# Stream Workspace logs
cordium logs abc

# Start a Workspace
cordium start abc

# Stop a Workspace
cordium stop abc
cordium delete workspace abc

# Create a Space
cordium create space my-project

# Create a Template with inline configuration
cordium create template ml-env.my-project \
  --image python:3.11 \
  --repository https://github.com/myorg/ml-project \
  --env-from-secret WANDB_API_KEY=wandb-secret \
  --cpu 8000 --memory 16384

# Build a Template pre-build snapshot
cordium build ml-env.my-project

# Create a Workspace from a Template with variable overrides
cordium run --template go-build.my-project \
  --var SERVICE=services/payments \
  --var BRANCH=main \
  --ephemeral

Install your First Cluster

Read this quick guide here to install a single-node Cordium Cluster on top of any cheap cloud VM/VPS instance (e.g. DigitalOcean Droplet, Hetzner server, AWS EC2, Vultr, etc...) or a local Linux machine/Linux VM inside a MacOS/Windows machine with at least 4GB of RAM and 20GB of disk storage running a recent Linux distribution (Ubuntu 24.04 LTS or later, Debian 12+, etc...), which is good enough for most development, personal or undemanding production use cases that do not require highly available multi-node Clusters. Once you SSH into your VPS/VM as root, you can install the Cluster as follows:

curl -o install-cluster.sh https://octelium.com/install-cluster.sh
chmod +x install-cluster.sh

# Replace <DOMAIN> with your actual domain
./install-cluster.sh --domain <DOMAIN> --cordium

Once the Cluster is installed. You can run your first Workspace as follows:

cordium run

Install CLI

Install the cordium CLI as follows:

For Linux and MacOS

curl -fsSL https://octelium.com/install.sh | bash
curl -fsSL https://octelium.com/install-cordium.sh | bash

For Windows in Powershell

iwr https://octelium.com/install.ps1 -useb | iex
iwr https://octelium.com/install-cordium.ps1 -useb | iex

You can also install the CLIs via Homebrew as follows:

brew install octelium/tap/octelium
brew install octelium/tap/cordium

Comparison with Other Platforms

License

Cordium-owned source code is licensed under the Apache License 2.0.

Cordium is built on top of Octelium. Some Cordium components or complete deployments may include Octelium Cluster components, which are publicly licensed under AGPLv3. Octelium Labs, LLC owns the relevant copyrights for both projects.

Copyright © Octelium Labs, LLC. All rights reserved.