Concepts

This page explains the core resource types in Cordium, how they relate to each other, and the design principles behind them. Every resource is managed through the same gRPC-based API, which is used by the cordium CLI, the web portal and the SDKs alike.

Cordium hierarchy

Here is a quick overview of how the resources relate to each other:

Space (e.g. payments.cordium)
├── Membership     (an Octelium User and their role in the Space)
├── Template       (a reusable Workspace configuration, optionally pre-built)
│   └── Workspace  (a running or stopped sandbox owned by a User)
├── Secret         (a sensitive value referenced by Templates and Workspaces)
├── Volume         (persistent storage mounted by the Space's Workspaces)
└── GitProvider    (OAuth2 configuration for GitHub, GitLab or any OAuth2 git host)

User (an Octelium User)
├── WorkspaceSnapshot  (a point-in-time copy of a Workspace's storage)
├── UserSecret         (a personal sensitive value, including Cluster-generated SSH keys)
└── UserConfig         (personal dotfiles, environment variables and tasks)

Cluster
├── Region         (an Octelium Region enabled to host Workspaces)
└── ClusterConfig  (Cluster-wide ownership rules, storage, limits, timeouts and agent settings)

Workspaces

A 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 the web portal, the cordium CLI, standard SSH, and gRPC-based SDKs.

Workspaces are automatically assigned short randomly generated names (3 to 6 lowercase alphanumeric characters, e.g. abc, x7k2) by the Cordium Cluster. Every Workspace belongs to exactly one Template and one Space and is owned by a single Octelium User. A Workspace is created in the STOPPED state and it can be started and stopped as many times as needed. Every start is called a run.

When a Workspace starts, Cordium creates a dedicated Octelium Session bound to that run. This Session is the Workspace's identity for secretless access to the Octelium Services that its owner User is authorized to access, via an octelium connect process that is automatically run inside the Workspace. When the Workspace stops, the Session is deleted.

A persistent Workspace preserves its storage, including its home directory, /workspace and every system package installed in its container, across stops and restarts. The filesystem resumes exactly where it left off and only POST_START tasks re-run on subsequent starts. An ephemeral Workspace discards its storage on stop. Every start provisions a fresh volume and runs the full initialization sequence from scratch. Ephemeral Workspaces are suited for AI agent tasks, disposable build environments, and any workload where state accumulation between runs is undesirable.

A Workspace is configured through its spec, which is merged with the spec of its Template, the runtime configuration of its Space, the owner's UserConfig and the Cluster defaults at initialization time. A rather minimal Workspace configuration can look as follows:

spec:
  image:
    registry:
      url: python:3.13-bookworm
  repository:
    url: https://github.com/myorg/api-service
  runtime:
    envVars:
      - key: SENTRY_DSN
        fromSecret: sentry-dsn.payments.cordium
    tasks:
      - name: install
        type: ON_CREATE
        workingDir: /workspace/repo
        run: pip install -r requirements.txt
        onFailure: ON_FAILURE_ABORT

You can run such YAML files via the cordium run --file and cordium create workspace --file commands. You can also use inline flags (e.g. --image) without using YAML files at all. Here are some examples:

# From a YAML file
cordium run --file workspace.yaml --space payments.cordium

# Inline specification of an image, a repository, a Secret-sourced environment variable and a port
cordium run --space payments.cordium \
  --image node:24-bookworm \
  --repository https://github.com/myorg/api-service \
  --env-from-secret DATABASE_URL=dev-db-url.payments.cordium \
  --port web:3000:default

note

Read in detail about Workspace configuration here.

A Workspace moves through the following states throughout its lifecycle:

State	Description
`STOPPED`	The Workspace is not running. Its storage is preserved unless the Workspace is ephemeral.
`INIT_REQUEST`	A start request has been accepted by the Cluster.
`INITIALIZING`	The Cluster is provisioning the underlying Kubernetes resources and waiting for the Workspace supervisor to become ready.
`PULLING_IMAGE`	The container image is being pulled from the registry.
`BUILDING_IMAGE`	The container image is being built from a Dockerfile or a devcontainer spec.
`STARTING_RUNTIME`	The Workspace's container has started and its agent is initializing.
`PREPARING`	The agent is running the lifecycle setup: cloning repositories, installing devcontainer features and dotfiles and running the `ON_CREATE` and foreground `POST_START` tasks. Terminals, `cordium exec` and SSH already work in this state.
`RUNNING`	The Workspace is fully initialized and ready to be used.
`STOPPING_REQUEST`	A stop request has been received (e.g. via `cordium stop`, an auto-stop, or an inactivity timeout).
`STOPPING`	The Workspace is shutting down gracefully and running its `PRE_STOP` tasks.

Failures at any stage are captured with a structured failure type (e.g. an image pull or build failure, a repository clone failure, an aborting task, a startup timeout, a network policy or a Volume that cannot be enforced) that is visible in the Workspace's status, the web portal, and the SDKs.

Templates

A Template defines a reusable Workspace configuration within a Space. When a Workspace is created, it is initialized from the selected Template's spec and the Workspace spec can override and extend it. Every Space has a default Template created automatically along with it. A Template's spec shares most of the Workspace spec (i.e. the image, repositories, runtime, limits and variables) and can additionally be associated with a GitProvider.

A pre-build runs a hidden build Workspace from the Template and snapshots its storage once all of its ON_CREATE and foreground tasks complete. Subsequent Workspaces of the Template are then restored from that snapshot and start with all dependencies, compiled artifacts, and cloned repositories already in place. This can reduce startup time from minutes to seconds for dependency-heavy Templates. Pre-building is triggered via cordium build <TEMPLATE>, the portal or the BuildTemplate API (read more here).

Spaces

A Space is the top-level namespace in Cordium. It groups Templates, Workspaces, Secrets, Volumes, GitProviders and Memberships under a single organizational unit. There are two types of Spaces:

USER Spaces are personal to a single User (e.g. default.alice or research.alice). A default Space is created automatically for every User upon the creation of their first Workspace.
ORGANIZATION Spaces (e.g. payments.cordium) are shared by several Users via Memberships and can additionally define default and maximum resource limits for their Workspaces.

A Space can define runtime configuration (environment variables, lifecycle tasks and Linux capabilities) that cascades down to every Workspace within it regardless of its Template (read more here).

Memberships

A Membership connects an Octelium User to a Space and assigns a role: OWNER, ADMIN, or USER. Every member can create Workspaces from the Space's Templates and mount its Volumes, while ADMIN and OWNER members can additionally manage its Templates and their pre-builds, Secrets, Volumes, GitProviders and Memberships. Members can currently only be added to ORGANIZATION Spaces.

Volumes

A Volume is persistent storage owned by a Space, with a lifecycle independent of the Workspaces that mount it. Volumes are mounted at arbitrary paths by the Workspaces of their Space, they outlive those Workspaces and they are never included in WorkspaceSnapshots. An EXCLUSIVE Volume, which is the default, is mounted by a single running Workspace at a time, while a SHARED Volume can be mounted by several running Workspaces at the same time when the storage backend supports multi-writer volumes (e.g. NFS, CephFS or EFS). Volumes belong to a single Region and can only be mounted by Workspaces running in that Region (read more here).

WorkspaceSnapshots

A WorkspaceSnapshot is a point-in-time copy of a Workspace's persistent storage that is backed by a Kubernetes CSI volume snapshot. It can be restored into any number of brand new Workspaces in the same Space. Snapshots are taken asynchronously while the source Workspace keeps running, in which case they are crash-consistent, or while the source Workspace is stopped, in which case they are clean. WorkspaceSnapshots are owned by their User and outlive both their source Workspace and the Workspaces restored from them (read more here).

Secrets

Secrets are sensitive values (API keys, tokens, passwords, certificates) stored within a Space. They are referenced by their full name (e.g. db-password.payments.cordium) from the Template and Workspace specs of the same Space and their values are never returned back by the API once created. They are mainly used as the source of environment variables, private registry passwords, repository passwords and GitProvider OAuth2 client secrets. Here is an example:

spec:
  runtime:
    envVars:
      - key: DATABASE_PASSWORD
        fromSecret: db-password.payments.cordium
  repository:
    url: https://github.com/myorg/private-repo
    authentication:
      http:
        username: oauth2
        password:
          fromSecret: github-pat.payments.cordium

note

Secrets are injected into the Workspace, which means that the processes running inside it, including AI agents, can read them. Whenever the upstream resource can be protected by an Octelium Service instead, prefer secretless access, which keeps the credential entirely out of the Workspace (read more here).

GitProviders

A GitProvider configures OAuth2 authentication against a git hosting service: GitHub, GitLab, or a generic OAuth2 provider (e.g. Gitea and Forgejo). Once a GitProvider is attached to a Template via its gitProvider field, the User signs in to the git hosting service from the web portal page of their Workspace and the User's OAuth2 token is automatically injected into that Workspace via a git credential helper. This enables git clone, git push, and other authenticated git operations without any manual credential configuration. Cordium also sets git config user.name and user.email from the provider's user profile (read more here).

UserConfig

UserConfig is a per-User configuration object that is applied to all of a User's Workspaces regardless of their Space or Template. It is created automatically on first use and it supports:

Dotfiles: a git repository that is cloned into ~/dotfiles on the first run of every Workspace, whose first install script found (e.g. install.sh, bootstrap.sh or setup.sh) is executed.
Environment variables: static values or values sourced from UserSecrets that are injected into every Workspace.
Tasks: personal lifecycle tasks that run in every Workspace (e.g. installing your favorite shell prompt).
Preferred Region: the Region in which the User's Workspaces are preferably run.

UserSecrets

UserSecrets are per-User sensitive values, scoped to the owning User rather than to a Space. They are used as the value sources of the UserConfig environment variables and for the dotfiles repository authentication. UserSecrets of the SSH_KEY type have their ECDSA key pair generated by the Cluster: the private key never leaves the Cluster and is automatically loaded into an SSH agent inside every Workspace of the User, while its public key can be registered at GitHub, GitLab or any SSH server (read more here).

Regions

A Region represents an Octelium Region that is enabled to host Cordium Workspaces. Cordium exposes its country and city so that clients can choose where a Workspace runs. Workspace storage, Volumes and WorkspaceSnapshots belong to a single Region.

Resource Names

Workspaces are named by the Cluster and their names are globally unique. All other resources are named by you and their full names encode their parents as follows:

Resource	Full name	Examples
`USER` Space	`<SPACE>.<USER>`	`default.alice`, `research.alice`
`ORGANIZATION` Space	`<SPACE>.cordium`	`payments.cordium`
Template, Secret, Volume, GitProvider	`<NAME>.<SPACE_FULL_NAME>`	`api-dev.default.alice`, `stripe-key.payments.cordium`
WorkspaceSnapshot, UserSecret	`<NAME>.<USER>`	`before-upgrade.alice`

When you refer to a Space, a Template, a Volume or a WorkspaceSnapshot (e.g. in cordium commands and in the volumeMounts of a spec), the Cluster completes short names for you based on the calling User and the Workspace's Space. For example, for the User alice:

# Refers to the Template api-dev.default.alice in alice's default Space
cordium run --template api-dev
# Refers to the Template api-dev.research.alice in alice's research Space
cordium run --template api-dev.research
# Refers to the Template api-dev of the payments ORGANIZATION Space
cordium run --template api-dev.payments.cordium

On the other hand, the fromSecret fields of the specs, the fromUserSecret fields of the UserConfig and the gitProvider field of Templates always refer to the full name of the Secret, UserSecret or GitProvider (e.g. npm-token.payments.cordium or github-token.alice). You can always see the full name of any resource via the -o yaml flag of the cordium get commands (e.g. cordium get secret npm-token.payments.cordium -o yaml).

Relationship to Octelium

Every resource in Cordium is grounded in Octelium's identity and resource system:

Users are Octelium Users authenticated through Octelium's identity providers (OIDC, SAML, GitHub OAuth2, workload OIDC assertions) or Credentials. Both HUMAN and WORKLOAD Users can own Workspaces (read more about Users here).

Sessions are Octelium Sessions. Every Workspace run creates a dedicated Session that is used by the octelium connect process running inside the Workspace as well as by the cordium and octelium CLIs inside it. That Session carries the Workspace's identity, its Space and its Template, which can be used by Octelium Policies, and it is deleted when the Workspace stops (read more about Sessions here).

Services: each protected resource (e.g. a remote internal resource, a publicly protected SaaS resource or an LLM provider) in the Octelium Cluster is represented and implemented by a Service. Workspaces access their authorized Services in a secretless way and they can also serve Services themselves (read more about Services here).

Policies: access to every Service, including Cordium's own API, portal and SSH Services, is evaluated by Octelium Policies on a per-request basis (read more here).