crun-sys

Low-level Rust FFI bindings for libcrun, the OCI container runtime library.

Overview

This crate provides raw C bindings generated by bindgen. It exposes the libcrun API for creating, running, and managing OCI containers.

Platform Support

Platform	Status
Linux	✅ Full support
macOS	⚠️ Stub module (compiles, no functionality)
Windows	⚠️ Stub module (compiles, no functionality)

libcrun is Linux-only — it relies on Linux-specific features:

cgroups (v1 and v2)
namespaces (user, pid, network, mount, etc.)
seccomp (syscall filtering)
capabilities

On non-Linux platforms, this crate provides a stub module that allows dependent code to compile but provides no runtime functionality.

Requirements (Linux)

libcrun >= 1.8
pkg-config (for library discovery)
Development headers for libcrun and dependencies

Debian/Ubuntu

apt-get install libcrun-dev libyajl-dev libseccomp-dev libcap-dev pkg-config

Fedora/RHEL

dnf install crun-devel yajl-devel libseccomp-devel libcap-devel pkgconf-pkg-config

Arch Linux

pacman -S crun libseccomp libcap

Usage

Add to your Cargo.toml:

[dependencies]
crun-sys = "0.1"

Example (Linux)

use crun_sys::*;
use std::ffi::CString;
use std::ptr;

fn main() {
    // All FFI functions are unsafe
    unsafe {
        let mut err: libcrun_error_t = ptr::null_mut();
        
        // Load container from OCI config JSON
        let config = CString::new(r#"{"ociVersion": "1.0.0", ...}"#).unwrap();
        let container = libcrun_container_load_from_memory(
            config.as_ptr(),
            &mut err,
        );
        
        if container.is_null() {
            // Handle error, then release
            crun_error_release(&mut err);
            return;
        }
        
        // ... use container ...
        
        libcrun_container_free(container);
    }
}

Safety

All functions in this crate are unsafe as they are direct C FFI bindings. The caller must ensure:

Requirement	Description
Pointer validity	All pointers must be valid and properly aligned
Null-termination	All C strings must be null-terminated (`CString`)
Lifetime management	Contexts and containers must be properly freed
Error handling	`libcrun_error_t` must be released via `crun_error_release()`
Thread safety	libcrun contexts are NOT thread-safe

Building from Source

# Clone the repository
git clone https://github.com/magikrun/magik.git
cd magik/crun-sys

# Build (Linux)
cargo build

# Build (non-Linux) - produces stub module
cargo build  # Warning: libcrun is Linux-only, building stub module

# Run tests
cargo test

Static Builds with musl

For fully portable static binaries that run on any Linux distribution:

# On Alpine Linux (native musl)
apk add rust cargo libcrun-static libseccomp-static libcap-static yajl-static
cargo build --release

# On other distros - build libcrun from source with musl
# See .github/workflows/ci.yml for the full build process

The resulting binary will have zero runtime dependencies.

Related Crates

crun-sys (this crate) — Raw FFI bindings
machineplane — High-level safe Rust wrapper with CrunEngine

License

Apache-2.0

Upstream

libcrun: https://github.com/containers/crun
Minimum supported version: 1.8

crun-sys 0.1.1