Expand description
§Cordium Rust SDK
The async Rust SDK for Cordium: create isolated workspaces, run commands, move files, attach to persistent terminals, and manage the resources around them. Built on Tokio, tonic, and the shared Octelium authentication client. Rust 2024 edition; minimum supported Rust version (MSRV) 1.88.
§Installation
Add the crate from crates.io:
[dependencies]
cordium = "0.3"
tokio = { version = "1", features = ["macros", "rt-multi-thread"] }
futures-util = "0.3" # for StreamExtFor local development, use cordium = { path = "/path/to/sdk-rust/crates/cordium" }.
Generated protobuf files are included: applications need neither protoc nor the
protobuf source repository to compile.
§A usable workspace in one call
use cordium::{Client, Command, WorkspaceOptions};
let client = Client::builder().domain("example.com").build().await?;
let workspace = client.workspaces().run(
WorkspaceOptions::new().image("python:3.14").ephemeral(true),
).await?;
let result = workspace.exec(Command::argv(["python", "--version"])).await?;
println!("{}", result.stdout_text());
workspace.files().write_text("/tmp/hello.txt", "Hello from Rust!\n").await?;
workspace.delete().await?;create returns a stopped workspace with a cluster-assigned name. run creates,
starts, and waits for RUNNING under a five-minute total deadline. Use run_with
for start-time variable overrides, placement, or a different wait deadline.
Once the workspace exists, a failure of a later step is reported as
Error::RunFailed, which carries the workspace so that it can be inspected or
deleted; deleting it is explicit. start on a starting or running workspace is
a no-op, and wait_stopped reports a failed run as Error::WorkspaceFailed.
Dropping a client or workspace does not stop or delete remote workspaces.
For cleanup after a command error, store its result, call delete, then propagate
the result. The quickstart example shows this pattern.
§Authentication and connection settings
Explicit credentials take precedence over the environment:
use cordium::{Assertion, AuthenticationToken, Client};
let client = Client::builder()
.domain("example.com")
.authenticator(AuthenticationToken::new("<one-time authentication token>"))
.build().await?;
let workload_client = Client::builder()
.domain("example.com")
.authenticator(Assertion::from_file("/var/run/identity/token"))
.build().await?;Client::from_env() reads CORDIUM_DOMAIN, falling back to OCTELIUM_DOMAIN.
Credentials follow this order:
| Variable | Behavior |
|---|---|
OCTELIUM_ACCESS_TOKEN | Externally managed bearer token, used directly. |
OCTELIUM_ASSERTION_FILE | Assertion file re-read on every authentication. |
OCTELIUM_ASSERTION | Fixed assertion, exchanged once. |
OCTELIUM_AUTH_TOKEN | One-time authentication token. |
Use access_token_provider for rotating externally managed tokens, and
Assertion::from_fn for renewable signed assertions. Authenticator and
AccessTokenProvider remain extensible for new cluster authentication methods.
Authentication is lazy. Concurrent callers share token state and serialize
exchanges. Canceling an individual request does not discard an ongoing exchange;
it can complete for other callers. Authentication has its own default 30-second
bound, customizable through configure_transport. One-time exchanges are never
replayed after failure or expiry. Session refresh uses a separate connection and
starts before token expiry. Credentials have redacted Debug implementations;
access_token() deliberately returns a sensitive string.
The default endpoint is https://octelium-api.<domain>:443, with certificate
verification. api_endpoint overrides it, including a plain HTTP endpoint for
local testing. OCTELIUM_API_ENDPOINT and OCTELIUM_TLS_SERVER_NAME also apply.
Advanced transport settings are exposed through the shared builder:
let client = cordium::Client::builder().domain("example.com")
.configure_transport(|builder| {
builder
.add_root_ca_pem(b"<PEM CA certificate>".to_vec())
.configure_endpoint(|endpoint| {
endpoint.connect_timeout(std::time::Duration::from_secs(10))
})
})
.build().await?;Client::from_transport reuses an existing octelium::Client. Both clients
share credentials and connections; the caller keeps ownership of that transport,
so Cordium shutdown leaves it open.
§Workspace configuration
Consuming builders provide common settings; full generated specs cover the rest:
use cordium::{Application, EnvValue, Resources, Task, TaskPhase, WorkspaceOptions};
let options = WorkspaceOptions::new()
.template("dev.team")
.display_name("API development")
.image("node:24")
.repository("https://github.com/myorg/api.git")
.branch("main")
.env("NODE_ENV", "development")
.env("API_TOKEN", EnvValue::secret("api-token.team"))
.variable("VERSION", "v2")
.resources(Resources::new().cpu_millicores(2000).memory_mb(4096))
.application(Application::new("web", 3000).default_app())
.task(Task::new("install", "npm ci"))
.task(Task::new("serve", "npm run dev").phase(TaskPhase::Start).background(true))
.mount("cache.team", "/cache", false);Template and snapshot sources are mutually exclusive. Snapshot restoration needs
persistent storage. Environment values can resolve Space Secrets without placing
their content in the specification. Compute units are millicores and MB.
Variables use the cluster’s ${{ vars.NAME }} substitution syntax. Mount paths
must be absolute, canonical and non-overlapping; server policy checks reserved
paths and storage compatibility.
WorkspaceOptions::from_spec, image_spec, repository_spec, and the proto
module support private registries, repository credentials, devcontainers,
additional repositories, capabilities, networking, and future configuration.
Template creation accepts the same builder, while rejecting workspace-only
applications, ephemeral storage, and source references. Set git_provider on a
Template to obtain authenticated git operations in its workspaces.
Cloned Workspace handles share a cache. Accessors perform no network operations
and return owned values. refresh, lifecycle methods, and modify update that
cache; watch events are independent. watch yields typed WorkspaceEvents and
logs yields LogEntry values (timestamp, stage, stream and bytes). proto(),
spec(), and status() return owned copies. Unknown enum values remain
accessible through their raw protobuf integer fields.
§Commands and streaming
String commands use remote shell syntax. Use Command::argv when arguments
should be literal; every argument is POSIX-quoted without interpolation.
use cordium::{Command, Error};
let result = workspace.exec(Command::argv(["printf", "%s", "$(literal text)"]))
.cwd("/workspace/repo")
.env("MODE", "test")
.timeout(Some(std::time::Duration::from_secs(60)))
.await?;
match workspace.exec("exit 7").check(true).await {
Err(Error::CommandFailed(result)) => {
println!("exit {}: {}", result.exit_code, result.stderr_text());
}
other => { other?; }
}Nonzero exit codes are normal results by default; .check(true), or
ExecResult::check afterwards, turns them into Error::CommandFailed. Output is binary Bytes; text accessors use
UTF-8 replacement while retaining the original bytes. Capture defaults to
1 MiB per stdout/stderr stream. Overflow sets truncated; streaming events
still carry complete output. Zero capture size disables capture.
use cordium::ExecEvent;
use futures_util::StreamExt;
let mut session = workspace.exec("printf 'hello\n'").stream().await?;
while let Some(event) = session.next().await {
match event? {
ExecEvent::Stdout(bytes) => print!("{}", String::from_utf8_lossy(&bytes)),
ExecEvent::Stderr(bytes) => eprint!("{}", String::from_utf8_lossy(&bytes)),
ExecEvent::Exit(code) => println!("exit: {code}"),
_ => {},
}
}
let result = session.wait().await?;Streams implement futures_core::Stream, are Send, and use backpressure instead
of background output tasks or unbounded SDK queues. An Exit releases the RPC even
if the server leaves it open. Dropping a session cancels its RPC; use
session.input().kill().await for an explicit remote termination request. A
killed command that the cluster does not report as exited within 10 seconds
(.kill_grace(...)) ends the session with the exit code -1 and killed set.
For interactive stdin, call .stdin_enabled(true).stream().await, clone
session.input(), and write while another task consumes output. Writes are
serialized and chunked to 32 KiB through a bounded queue. For collected execution,
.stdin(bytes) sends initial input while draining output. Cordium’s exec
protocol has no stdin EOF message: commands must read a known amount or finish
independently. Closing a write handle does not signal EOF. File upload handles
this with exact-length base64 framing.
§Files and terminals
workspace.files() provides binary/text reads and writes, uploads, downloads,
mkdir, and remove. Paths are literal: no $HOME, glob or tilde expansion.
Reads cap memory at 64 MiB and reject larger files. max_read_bytes adjusts that
bound; uploads, upload_reader, and download_to stream with bounded chunks.
Text reads use strict UTF-8. as_root and timeout customize transfer commands.
Transfers require POSIX sh, head, base64, cat, mkdir, and rm in the
image. Remote writes may leave partial content after failure. Local downloads
use a private temporary file in the destination directory and replace an existing
destination only after successful execution and flushing. Use repositories,
object storage, or SSH/SFTP for bulk data.
use cordium::{TerminalOptions, TerminalEvent};
use futures_util::StreamExt;
let mut terminal = workspace.terminals().create(TerminalOptions::default().size(120, 40)).await?;
let input = terminal.input(); // can move to another task while consuming events
input.write("printf 'hello\n'\n").await?;
if let Some(Ok(TerminalEvent::Output(bytes))) = terminal.next().await {
print!("{}", String::from_utf8_lossy(&bytes));
}
terminal.remove().await?; // terminate the persistent remote shellTerminal Drop or detach ends only the local subscription. The shell survives
and can be found with list and reattached with attach. remove explicitly
terminates it. Several clients can attach to one terminal. Input and resize
operations are available on a clonable TerminalInput; local raw terminal mode
is the caller’s responsibility.
§Resources and pagination
| Collection | Capabilities |
|---|---|
workspaces | Create/run, get/update/delete, list/all, watch; handle lifecycle, logs, sharing, exec, files, terminals. |
spaces | Create/update/delete, list/all, edit full specs, leave. |
templates | Create/update/delete, list/all, build/cancel, wait for an explicit build ID. |
snapshots | Create/get/delete, list/all, wait for READY. |
volumes | Create/update/delete, list/all, monotonic capacity growth, wait for READY. |
secrets | Write-only text/binary/JSON creation, metadata reads/list/all, delete. |
user_secrets | Personal text/binary/JSON secrets, updates, cluster-generated SSH keys. |
git_providers | GitHub/GitLab/generic OAuth2 creation, get/update/delete, list/all. |
memberships | Add by User reference or email, read own membership, role edits, delete, list/all. |
regions | List/all hosting Regions. |
user_config | Get/update/modify preferences, preferred Region, dotfiles. |
management | Administrator get/update/modify of the sole ClusterConfig. |
Collection operations return complete generated resource types, preserving
advanced server fields. modify fetches, invokes a synchronous edit callback,
and updates exactly once; errors in the callback abort the update. There are no
automatic mutation retries or conflict-resolution guesses. Full resource updates
can race other writers; applications should handle any server conflict response.
use cordium::{ListOptions, Reference};
use futures_util::StreamExt;
let workspace = client.workspaces().get(Reference::uid("workspace-uid")).await?;
let mut all = client.workspaces().all(ListOptions::new().in_space("team.cordium").page_size(100));
while let Some(workspace) = all.next().await { println!("{}", workspace?.name()); }
client.spaces().modify("team.cordium", |space| {
space.metadata.as_mut().expect("server metadata").display_name = "Team".into();
Ok(())
}).await?;Pages are zero-based, carry server pagination metadata, and all fetches lazily.
Unsupported filters and pagination without progress fail explicitly. References
encode exactly one name or UID. Organization Space creation qualifies short names
with .cordium through SpaceOptions::organization.
Snapshots are taken online without stopping a Workspace. Wait for READY, then
create with WorkspaceOptions::snapshot. A Volume is independent persistent
storage, belongs to one Space and Region, and may require its first mount before
provisioning. Shared volumes require a shared storage backend. Capacity cannot
shrink. Template pre-build waits take an explicit ID to avoid mistaking a prior
successful build for the requested one.
§Deadlines, cancellation, and errors
| Operation | Default deadline |
|---|---|
| Unary SDK call, including authentication | 30 seconds, configurable on ClientBuilder. |
| Authentication/refresh exchange | 30 seconds, configured on the transport builder. |
| Workspace run or readiness wait | 300 seconds total, configured with WaitOptions. |
| File transfer | 300 seconds total. |
| Execution and server streams | Unlimited; set their total deadline explicitly. |
Durations are std::time::Duration; None disables a deadline. Positive finite
representable durations are required. Composite waits and stream deadlines cover
all their work rather than restarting on each event. Polling is used for resources
that do not publish readiness events; workspace watch streams are also exposed.
Drop a pending future/stream to cancel, or use tokio::select! with your own
cancellation signal. Streams progress when polled.
Client::close() cancels high-level SDK calls and subscriptions across clones,
clears local credentials, and prevents new calls. Connections are released when
all owners drop. Existing generated RPC calls and HTTP responses obtained through
escape hatches have their own transport lifetimes and should be dropped directly.
No remote resource is implicitly deleted and closing does not log out a Session.
Error is a non-exhaustive enum. Status preserves tonic status codes, details,
and metadata; code() exposes known gRPC codes. CommandFailed keeps binary
output and exit status, and WorkspaceFailed includes the last full resource.
Caller cancellation is normal Rust future cancellation; no synthetic success or
silent output loss is substituted. Non-idempotent API calls are never replayed.
§HTTP and extension APIs
With the default http feature, client.http() authenticates requests to workspace
application URLs. The Octelium policy accepts HTTPS for the cluster domain and its
subdomains; alternate hosts require explicit authorization through
configure_transport. Use a request timeout and stream large response bodies.
HTTP error status codes remain available on the reqwest response.
main_service, workspace_service, management_service, and transport are
escape hatches. Generated clients authenticate automatically, but high-level SDK
operation deadlines/cancellation are not applied to those raw calls. The proto,
meta, and prost_types re-exports keep model and runtime versions aligned.
The generated API crate is pinned to its tested version because additive protobuf
fields can change Rust struct construction. Regenerate, update that pin, and run
the workspace checks together when upgrading the API schema.
| Feature | Default | Purpose |
|---|---|---|
http | yes | Authenticated reqwest HTTP client for applications. |
tls-native-roots | yes | Host certificate store for gRPC TLS. |
tls-webpki-roots | no | Bundled webpki roots for gRPC TLS. |
No blocking facade or hidden runtime is created. Async clients work with a Tokio runtime, including a current-thread runtime. Reuse one client per cluster, then clone it cheaply for concurrent tasks.
§Examples and development
The examples include quickstart, streaming commands, lazy workspace listing, template pre-builds, and HTTP applications.
cargo run -p cordium --example quickstart
cargo test --workspace --all-features
cargo clippy --workspace --all-targets --all-features -- -D warnings
cargo fmt --all --check
RUSTDOCFLAGS="-D warnings" cargo doc --workspace --all-features --no-deps
python3 scripts/generate-cordium.py ../pb --checkPublic APIs are documented in rustdoc, and missing public documentation is a compile error. Integration tests run real generated tonic servers and POSIX shell processes on loopback, including binary transfers and authentication cancellation. A real cluster smoke test remains a release check; local tests do not verify a particular cluster’s policies, storage backend, or deployment.
Release dependency order: octelium-apis 0.1.4, octelium 0.2.0, then cordium
0.3.0. Packaging all workspace crates together verifies the local dependency
chain. Nothing is committed or published by the development commands above.
Re-exports§
pub use reqwest;pub use octelium_apis::prost_types;pub use tonic;
Modules§
- meta
- Common protobuf metadata, references, and list options.
The
octelium.api.main.meta.v1protobuf package. - proto
- Complete generated Cordium v1 messages and gRPC clients for advanced uses.
The
octelium.api.main.cordium.v1protobuf package.
Structs§
- Access
Token - Credential implementations and extension traits shared with the Octelium client. A bearer token for the Octelium Cluster and its known expiration time.
- Access
Token Provider Fn - Credential implementations and extension traits shared with the Octelium client.
An
AccessTokenProviderbacked by a closure. - Application
- A named TCP application exposed through the Cordium HTTPS proxy.
- Assertion
- Credential implementations and extension traits shared with the Octelium client. Authenticates with a signed assertion, such as an OIDC ID token.
- Authentication
Token - Credential implementations and extension traits shared with the Octelium client. Exchanges a Credential authentication token for a Cluster Session.
- Bytes
- Reference-counted binary buffers used by streams and execution results. A cheaply cloneable and sliceable chunk of contiguous memory.
- Bytes
Mut - Reference-counted binary buffers used by streams and execution results. A unique reference to a contiguous slice of memory.
- Client
- Shared authenticated client. Cloning shares connections, credentials and shutdown.
- Client
Builder - Configures authentication, transport, and default unary RPC deadlines.
- Event
Stream - An owned, backpressured async stream. Dropping it cancels its RPC.
- Exec
Builder - Configures a command. Awaiting this builder collects output with bounded capture.
- Exec
Input - Clonable write/kill half of an exec session. Writes are serialized and chunked. Dropping an input handle does not send EOF; only dropping the session cancels the RPC.
- Exec
Result - Collected binary output and the command’s exit status.
- Exec
Session - An owned command output stream with bounded capture and an independent input half.
- Files
- Files transferred through the Workspace shell, with literal paths and bounded memory.
- GitProviders
- Git hosting OAuth2 provider configuration.
- Http
Client - HTTP request and response types used by the authenticated application client. An HTTP client that attaches the Octelium access token to authorized destinations.
- List
Options - Pagination and filter configuration. Construct with
Defaultand builder methods. - LogEntry
- A single entry of a Workspace’s initialization logs.
- Management
- Cluster-wide administrator API.
- Memberships
- Space users and access roles.
- Page
- A single server page. Page numbering starts at zero.
- Regions
- Available cluster Regions that can host Workspaces.
- Request
Builder - HTTP request and response types used by the authenticated application client. Builds a request that carries the Octelium access token.
- Resources
- Compute allocations. Unset dimensions inherit platform defaults.
- Secrets
- Write-only Space secrets. Reads return metadata without sensitive content.
- Snapshots
- Point-in-time snapshots of private persistent workspace storage.
- Space
Options - Options for Space creation. All complete protobuf spec fields remain available.
- Spaces
- Space namespaces, limits, runtime configuration, and membership.
- Start
Options - Run-specific variables and placement; they do not alter the stored spec.
- Static
Access Token - Credential implementations and extension traits shared with the Octelium client. One externally managed access token with no known expiration time.
- Stream
Options - Settings for a server stream. Streaming is unlimited in duration by default.
- Task
- A lifecycle shell task, configured using consuming builder methods.
- Templates
- Reusable workspace specifications and asynchronous pre-builds.
- Terminal
- An attached PTY event stream. Drop detaches; only
removeterminates the persistent shell. - Terminal
Input - A clonable terminal write/resize half, usable while another task consumes output.
- Terminal
Options - Initial PTY dimensions and subscription deadline.
- Terminals
- Persistent Workspace terminals. Multiple callers may attach to the same shell.
- User
Config - User preferences, dotfiles, and runtime defaults.
- User
Secrets - Personal write-only secrets and cluster-generated SSH key pairs.
- Volume
Options - Capacity, concurrency and placement options for a persistent Volume.
- Volumes
- Space-owned persistent volumes that outlive Workspaces.
- Wait
Options - Total deadline and polling interval for composite operations.
- Workspace
- A cheap-to-clone Workspace handle with a shared, locally cached resource snapshot.
- Workspace
Options - Workspace or Template configuration. Options override the matching fields of a base spec.
- Workspaces
- Workspace collection. Workspaces are created stopped with server-assigned names.
Enums§
- Command
- An explicit shell command or safely quoted argument vector.
- EnvValue
- An environment value supplied literally or resolved from a Space Secret.
- Error
- An SDK, transport, API, or command failure. New variants may be added.
- Exec
Event - Binary command output or an explicit process exit event.
- List
Filter - Resource list filter. A single enum prevents conflicting filters.
- LogStage
- The initialization stage that produced a log entry.
- LogStream
- The output stream on which a log entry was emitted.
- Member
- Target User of a new Space membership.
- OrderBy
- Sort key used by resource lists.
- Reference
- Exactly one resource name or cluster-wide UID. Strings convert to names.
- Role
- Generated Space membership role enum. Role is the level of access that the Member has inside the Space
- Sharing
Mode - Audience allowed to access a shared named Application.
- Space
Mode - Which relationship selects Spaces in a list.
- State
- Generated lifecycle state enum. Unknown future values remain available in the raw status. State is the current state of the Workspace’s lifecycle
- Task
Phase - When a lifecycle task runs.
- Terminal
Event - Output, resize, or closure event from a persistent PTY shell.
- Workspace
Event - A create, update or delete event of a watched Workspace.
Traits§
- Access
Token Provider - Credential implementations and extension traits shared with the Octelium client. Supplies externally managed Octelium access tokens.
- Authenticator
- Credential implementations and extension traits shared with the Octelium client. Creates a Cluster Session.
- Http
Authorization Policy - HTTP request and response types used by the authenticated application client. Decides whether an HTTP request may receive the Octelium access token.
Functions§
- shell_
quote - Quotes one literal POSIX shell word. NUL cannot be represented and is rejected.
Type Aliases§
- Result
- Result returned by Cordium SDK operations.