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