APIs and SDKs

The complete Cordium API is exposed over gRPC. This is the interface used by the cordium CLI and the web portal. Cordium provides SDKs for Golang, Python, Rust and TypeScript/JavaScript that handle authentication, Workspace lifecycle operations, command execution and file transfers.

The SDKs also support managing resources such as Spaces, Templates, Snapshots, Volumes and Secrets. They share the same Octelium authentication and authorization model as the CLI and the web portal.

Authentication

The examples below read the Cluster domain and credentials from the environment:

export CORDIUM_DOMAIN=example.com
export OCTELIUM_AUTH_TOKEN='<your authentication token>'

OCTELIUM_DOMAIN can also be used for the Cluster domain. For workload identity federation, set OCTELIUM_ASSERTION_FILE to the path of an assertion file. An existing access token can be supplied through OCTELIUM_ACCESS_TOKEN. The authenticated User must have a Policy that permits the requested operations. Read more about authentication-token Credentials here and Policies here.

Workspace Example

The following example creates a client and runs a Workspace with a container image, a Git repository, environment variables, resource limits and lifecycle Tasks. An ON_CREATE Task installs dependencies, while a background POST_START Task starts a development server exposed through a Workspace application.

Once the Workspace is running, the example writes a configuration file, uploads a local file, runs tests and builds the application, then downloads the build artifact and deletes the Workspace.

Replace the repository URL and npm commands with those used by your application. This example assumes a repository with a lockfile, test, build and dev scripts, a development server on port 3000 and build output in dist/. Create a local input.json file before running it. Resource limits use CPU millicores and megabytes for memory and storage. Read more about Workspace configuration here.

Golang

Python

Rust

TypeScript

The cordium-go SDK uses composable options and context-based cancellation. Install the module in your Go application as follows:

go get github.com/octelium/cordium/cordium-go

Here is a complete example:

package main

import (
	"context"
	"fmt"
	"os"
	"time"

	cordium "github.com/octelium/cordium/cordium-go"
)

func main() {
	ctx, cancel := context.WithTimeout(context.Background(), 10*time.Minute)
	defer cancel()
	if err := run(ctx); err != nil {
		fmt.Fprintln(os.Stderr, err)
		os.Exit(1)
	}
}

func run(ctx context.Context) error {
	client, err := cordium.New(ctx)
	if err != nil {
		return err
	}
	defer client.Close()

	workspace, err := client.Workspaces().Run(ctx,
		cordium.WithImage("node:24-bookworm"),
		cordium.WithRepo("https://github.com/myorg/orders-api"),
		cordium.WithEnv("NODE_ENV", "development"),
		cordium.WithResources(cordium.Resources{
			CPUMillicores: 2000, MemoryMB: 4096, StorageMB: 10000,
		}),
		cordium.Ephemeral(),
		cordium.WithTask("install", "npm ci",
			cordium.TaskWorkingDir("/workspace/repo"),
			cordium.TaskAbortOnFailure(),
		),
		cordium.WithPostStartTask("dev", "npm run dev -- --host 0.0.0.0",
			cordium.TaskWorkingDir("/workspace/repo"),
			cordium.TaskInBackground(),
		),
		cordium.WithApp("web", 3000, cordium.AsDefaultApp()),
	)
	if err != nil {
		return err
	}
	defer workspace.Delete(context.WithoutCancel(ctx))
	fmt.Println("Development server:", workspace.AppURL("web"))

	if err := workspace.WriteFileString(ctx, "/workspace/repo/.env", "LOG_LEVEL=debug\n"); err != nil {
		return err
	}
	if err := workspace.UploadFile(ctx, "./input.json", "/workspace/repo/input.json"); err != nil {
		return err
	}
	result, err := workspace.Exec(ctx,
		"npm test && npm run build && tar -czf /tmp/app.tar.gz dist",
		cordium.WithWorkingDir("/workspace/repo"),
		cordium.WithExecTimeout(2*time.Minute),
	)
	if err != nil {
		return err
	}
	fmt.Print(result.StdoutString(), result.StderrString())
	if err := result.Err(); err != nil {
		return err
	}
	return workspace.DownloadFile(ctx, "/tmp/app.tar.gz", "./app.tar.gz")
}

Run/run() creates the Workspace, starts it and waits for RUNNING, when foreground initialization Tasks have completed. Use Create/create() to create a stopped Workspace and start it later. Background Tasks do not delay readiness; an application may still need a health check before it is ready to serve requests.

note

An ephemeral Workspace discards its storage when stopped, but its resource object remains until explicitly deleted. Closing a client releases its connections without stopping or deleting Workspaces. The examples delete a successfully started Workspace even when a subsequent command or file transfer fails.

Startup failures retain the Workspace for inspection. Golang returns its handle alongside the error, Python and TypeScript expose the resource through error.workspace, and Rust uses Error::RunFailed with a Workspace handle. Inspect the failed Workspace and delete it when it is no longer needed.

Forking Workspaces from a Snapshot

WorkspaceSnapshots make it cheap to fork the exact state of a Workspace (e.g. a repository with its dependencies installed and its build cache warm) into several brand new Workspaces that run in parallel, which is useful for sharding test suites, trying several fixes at once, or best-of-N AI agent attempts. The following example snapshots the running Workspace k3x9, waits for the snapshot to be ready, restores it into three Workspaces in parallel, runs a different test shard in each of them and deletes them afterwards (read more about snapshots here):

Golang

Python

TypeScript

package main

import (
	"context"
	"fmt"
	"os"
	"sync"
	"time"

	cordium "github.com/octelium/cordium/cordium-go"
)

func main() {
	ctx, cancel := context.WithTimeout(context.Background(), 45*time.Minute)
	defer cancel()
	if err := run(ctx); err != nil {
		fmt.Fprintln(os.Stderr, err)
		os.Exit(1)
	}
}

func run(ctx context.Context) error {
	c, err := cordium.New(ctx)
	if err != nil {
		return err
	}
	defer c.Close()

	source, err := c.Workspaces().Get(ctx, "k3x9")
	if err != nil {
		return err
	}
	if _, err := source.Snapshot(ctx, "ledger-baseline"); err != nil {
		return err
	}
	if _, err := c.Snapshots().WaitUntilReady(ctx, "ledger-baseline"); err != nil {
		return err
	}

	shards := []string{"./internal/...", "./pkg/...", "./cmd/..."}
	results := make([]string, len(shards))

	var wg sync.WaitGroup
	for i, pattern := range shards {
		wg.Add(1)
		go func() {
			defer wg.Done()
			results[i] = runShard(ctx, c, pattern)
		}()
	}
	wg.Wait()

	for _, line := range results {
		fmt.Println(line)
	}
	return nil
}

func runShard(ctx context.Context, c *cordium.Client, pattern string) string {
	ws, err := c.Workspaces().Run(ctx, cordium.FromSnapshot("ledger-baseline"))
	if ws != nil {
		defer ws.Delete(context.WithoutCancel(ctx))
	}
	if err != nil {
		return fmt.Sprintf("%s: could not run: %v", pattern, err)
	}

	res, err := ws.Exec(ctx, "go test "+pattern,
		cordium.WithWorkingDir("/workspace/repo"),
		cordium.WithExecTimeout(30*time.Minute),
	)
	if err != nil {
		return fmt.Sprintf("%s: could not exec: %v", pattern, err)
	}
	return fmt.Sprintf("%s: exit code %d", pattern, res.ExitCode)
}

note

Snapshots require a storage backend that supports Kubernetes CSI volume snapshots. Restored Workspaces are created from the Template of the snapshotted Workspace and run in the Region that holds the snapshot.

Other SDK Capabilities

The same clients can be used for interactive sessions, application access and resource management. See each SDK's README and examples for complete usage:

Capability	Usage
Commands	Capture stdout, stderr and exit status, or stream output as a command runs. Set a working directory, environment variables and a deadline.
Files	Read and write text or binary data in memory, or stream uploads and downloads between the local filesystem and the Workspace.
Terminals and logs	Create and attach to persistent terminals, stream initialization logs and watch Workspace changes.
Applications	Obtain authenticated application URLs and share ports with Space members or authenticated Cluster Users.
Templates and storage	Build Templates, create and restore Snapshots, and manage persistent Volumes.
Resource management	List and manage Spaces, Secrets, UserSecrets, GitProviders and memberships.

Command strings are interpreted by the Workspace shell. For literal arguments, use cordium.Argv in Golang, a list of strings in Python, Command::argv in Rust or argv in TypeScript. Nonzero exit codes are returned in the command result by default; result.Err() in Golang and the check option in the other SDKs turn them into errors.

File transfers use the command execution API and require standard POSIX tools such as sh, base64 and head in the Workspace image. Read more about Workspace applications and port sharing here.

Full API and Resource Schemas

Each SDK also exposes the generated gRPC APIs for operations and configuration fields outside its convenience helpers. Use MainService(), WorkspaceService() and ManagementService() in Golang, AsyncCordium.raw and the cordium.proto module in Python, main_service(), workspace_service() and management_service() with cordium::proto in Rust, or client.raw and @octelium/cordium/proto in TypeScript. The blocking Python client provides client.call() for advanced async operations.

Cordium resource JSON Schemas are published under /schemas/cordium/latest/, with filenames such as cordium.v1.Workspace.schema.json. Use them to look up exact fields, types and enum values, for example the Workspace JSON Schema and Template JSON Schema. The resource concepts and Cluster configuration pages include interactive schema viewers.