C quickstart - BoxLite Documentation

Every function returns a BoxliteErrorCode; there are no exceptions to catch. Initialize CBoxliteError error = {0}; and free it on failure.

Prerequisites

The BoxLite C library and headers and a machine with hardware virtualization — see Installation.
Toolchain: a C11-compatible GCC or Clang; optionally CMake 3.15+.
Build artifacts: build the C SDK from the repository source first to produce the shared library and header:

# Run from the repository root (<YOUR_PATH> = the path to your boxlite repository)
cd <YOUR_PATH>/boxlite
# Fetch submodules (required)
git submodule update --init --recursive
# Build the C SDK (produces cdylib + staticlib + header)
cargo build --release -p boxlite-c
# Artifacts:
#   target/release/libboxlite.{dylib,so}   shared library
#   target/release/libboxlite.a            static library
#   sdks/c/include/boxlite.h               header (generated automatically by cbindgen)
# Verify the artifacts exist
ls -l target/release/libboxlite.* sdks/c/include/boxlite.h

Quick Example

The shortest runnable path is the Simple API: it creates and holds the runtime internally, runs commands synchronously, buffers stdout/stderr into the result struct, and requires no manual drain of callbacks. Save the following as hello.c:

#include <stdio.h>
#include "boxlite.h"

int main(void) {
    CBoxliteSimple *box = NULL;
    CBoxliteError error = {0};  /* must be zero-initialized */

    /* Create and automatically start a box. Passing 0 for cpus/memory = use defaults. */
    BoxliteErrorCode code =
        boxlite_simple_new("python:slim", 0, 0, &box, &error);
    if (code != Ok) {
        fprintf(stderr, "create box failed (code %d): %s\n",
                error.code, error.message ? error.message : "unknown");
        boxlite_error_free(&error);  /* free error.message on the failure path too */
        return 1;
    }

    /* Run inside the box: python -c "print('Hello from BoxLite!')" */
    const char *args[] = {"-c", "print('Hello from BoxLite!')"};
    CBoxliteExecResult *result = NULL;
    code = boxlite_simple_run(box, "python", args, 2, &result, &error);
    if (code == Ok) {
        printf("exit code: %d\n", result->exit_code);
        printf("stdout: %s", result->stdout_text ? result->stdout_text : "");
        if (result->stderr_text && result->stderr_text[0]) {
            fprintf(stderr, "stderr: %s", result->stderr_text);
        }
        boxlite_result_free(result);  /* free the result (includes stdout/stderr strings) */
    } else {
        fprintf(stderr, "exec failed (code %d): %s\n",
                error.code, error.message ? error.message : "unknown");
        boxlite_error_free(&error);
    }

    boxlite_simple_free(box);  /* automatically stop + remove + free the runtime */
    return 0;
}

Compile and run:

# Replace <YOUR_PATH> with the path to your boxlite repository
BOXLITE=<YOUR_PATH>/boxlite

gcc -std=c11 -o hello hello.c \
    -I"$BOXLITE/sdks/c/include" \
    -L"$BOXLITE/target/release" \
    -lboxlite

# macOS: let the executable find the dylib
export DYLD_LIBRARY_PATH="$BOXLITE/target/release:$DYLD_LIBRARY_PATH"
# Linux: use LD_LIBRARY_PATH instead
# export LD_LIBRARY_PATH="$BOXLITE/target/release:$LD_LIBRARY_PATH"

./hello

Expected output (the first run pulls the python:slim image and takes longer):

exit code: 0
stdout: Hello from BoxLite!

Native API (callback model)

Use the Native API when you need streaming output, custom configuration (volumes/ports/network/secrets), or multiple boxes. It uses a post-and-drain async model:

Call something like boxlite_create_box(runtime, opts, cb, user_data, &error), passing a completion callback.
The SDK runs the work in an internal Tokio task and posts the completion event to the runtime queue; the call itself returns immediately (only argument-validation errors are returned via out_error).
Call boxlite_runtime_drain(runtime, timeout_ms, &error) on the current thread, which takes events off the queue and runs callbacks on the calling thread. If you never call drain, your callbacks never fire.

boxlite_box_exec is the exception: it returns a CExecutionHandle* synchronously (not via a callback). But boxlite_execution_wait, used to get the exit code, is callback-style and still needs drain. Streaming stdout/stderr is registered via boxlite_execution_on_stdout / boxlite_execution_on_stderr callbacks, which are also dispatched by drain. Save the following as native.c:

#include <stdio.h>
#include <string.h>
#include "boxlite.h"

/* ---- Completion callbacks: store the result in user_data and mark "done" ---- */

typedef struct {
    CBoxHandle *box;
    int done;
    BoxliteErrorCode code;
} CreateState;

static void on_create(CBoxHandle *box, CBoxliteError *err, void *user_data) {
    CreateState *st = (CreateState *)user_data;
    st->box = box;
    st->code = err ? err->code : Ok;
    if (err && err->code != Ok) {
        fprintf(stderr, "create callback error (code %d): %s\n",
                err->code, err->message ? err->message : "unknown");
    }
    st->done = 1;
}

typedef struct {
    int exit_code;
    int done;
    BoxliteErrorCode code;
} WaitState;

static void on_wait(int exit_code, CBoxliteError *err, void *user_data) {
    WaitState *st = (WaitState *)user_data;
    st->exit_code = exit_code;
    st->code = err ? err->code : Ok;
    st->done = 1;
}

static void on_remove(CBoxliteError *err, void *user_data) {
    int *done = (int *)user_data;
    (void)err;
    *done = 1;
}

/* ---- Streaming output callbacks (note: signature is (bytes, len, user_data), not NUL-terminated) ---- */

static void on_stdout(const uint8_t *data, size_t len, void *user_data) {
    (void)user_data;
    fwrite(data, 1, len, stdout);
}

static void on_stderr(const uint8_t *data, size_t len, void *user_data) {
    (void)user_data;
    fwrite(data, 1, len, stderr);
}

/* ---- Block until some *done flag is set to 1 by a callback ---- */
static void drain_until(CBoxliteRuntime *rt, const int *done) {
    CBoxliteError err = {0};
    while (!*done) {
        /* timeout_ms < 0 = block until at least one event; returns the number of dispatched events, -1 on error */
        int n = boxlite_runtime_drain(rt, -1, &err);
        if (n < 0) {
            fprintf(stderr, "drain failed (code %d): %s\n",
                    err.code, err.message ? err.message : "unknown");
            boxlite_error_free(&err);
            return;
        }
    }
}

int main(void) {
    printf("BoxLite v%s\n", boxlite_version());

    CBoxliteError error = {0};

    /* 1. Runtime (home_dir=NULL uses the default ~/.boxlite; no custom image registry) */
    CBoxliteRuntime *runtime = NULL;
    if (boxlite_runtime_new(NULL, NULL, 0, &runtime, &error) != Ok) {
        fprintf(stderr, "runtime failed (code %d): %s\n",
                error.code, error.message ? error.message : "unknown");
        boxlite_error_free(&error);
        return 1;
    }

    /* 2. Options (typed builder) */
    CBoxliteOptions *opts = NULL;
    if (boxlite_options_new("alpine:3.19", &opts, &error) != Ok) {
        fprintf(stderr, "options failed (code %d): %s\n",
                error.code, error.message ? error.message : "unknown");
        boxlite_error_free(&error);
        boxlite_runtime_free(runtime);
        return 1;
    }
    boxlite_options_set_cpus(opts, 2);
    boxlite_options_set_memory(opts, 512);        /* MiB */
    boxlite_options_set_network_enabled(opts);
    boxlite_options_set_auto_remove(opts, 0);     /* do not auto-remove on stop */

    /* 3. Create the box (callback-based): the call returns immediately; drain triggers on_create */
    CreateState cs = {0};
    if (boxlite_create_box(runtime, opts, on_create, &cs, &error) != Ok) {
        fprintf(stderr, "create_box rejected (code %d): %s\n",
                error.code, error.message ? error.message : "unknown");
        boxlite_error_free(&error);
        boxlite_options_free(opts);
        boxlite_runtime_free(runtime);
        return 1;
    }
    boxlite_options_free(opts);  /* options have been cloned; can be freed immediately */
    drain_until(runtime, &cs.done);
    if (cs.code != Ok || cs.box == NULL) {
        boxlite_runtime_free(runtime);
        return 1;
    }
    CBoxHandle *box = cs.box;

    /* 4. Run a command: boxlite_box_exec returns the execution handle synchronously */
    const char *const args[] = {"-la", "/"};
    BoxliteCommand cmd = {
        .command = "/bin/ls",
        .args = args,
        .argc = 2,
        .env_pairs = NULL,
        .env_count = 0,
        .workdir = NULL,
        .user = NULL,
        .timeout_secs = 30.0,  /* 0.0 = no timeout */
        .tty = 0,
    };
    CExecutionHandle *execution = NULL;
    if (boxlite_box_exec(box, &cmd, &execution, &error) != Ok) {
        fprintf(stderr, "exec failed (code %d): %s\n",
                error.code, error.message ? error.message : "unknown");
        boxlite_error_free(&error);
        goto cleanup;
    }

    /* 5. Register streaming output callbacks (dispatched by subsequent drain) */
    boxlite_execution_on_stdout(execution, on_stdout, NULL, &error);
    boxlite_execution_on_stderr(execution, on_stderr, NULL, &error);

    /* 6. Wait for exit (callback-based): drain dispatches both output chunks and on_wait */
    printf("\n--- ls -la / ---\n");
    WaitState ws = {0};
    if (boxlite_execution_wait(execution, on_wait, &ws, &error) == Ok) {
        drain_until(runtime, &ws.done);
        printf("\nexit code: %d\n", ws.exit_code);
    } else {
        fprintf(stderr, "wait failed (code %d): %s\n",
                error.code, error.message ? error.message : "unknown");
        boxlite_error_free(&error);
    }
    boxlite_execution_free(execution);

cleanup:
    /* 7. Remove the box (callback-based, force=1) */
    {
        char *box_id = boxlite_box_id(box);  /* must be freed with boxlite_free_string */
        int rm_done = 0;
        if (boxlite_remove(runtime, box_id, 1, on_remove, &rm_done, &error) == Ok) {
            drain_until(runtime, &rm_done);
        } else {
            boxlite_error_free(&error);
        }
        boxlite_free_string(box_id);
    }
    boxlite_box_free(box);
    boxlite_runtime_free(runtime);  /* free the runtime (reclaims remaining boxes) */
    return 0;
}

Compile the same way as the Quick Example (the same gcc command, swapping hello.c for native.c).

Running Examples

BoxLite ships 8 C examples under examples/c, built with CMake. The provided CMakeLists.txt already sets BUILD_RPATH to the library directory, so the built binaries find libboxlite.* without any manual LD_LIBRARY_PATH / DYLD_LIBRARY_PATH export.

# Navigate to the examples directory (from the repository root)
cd examples/c

# Build the examples with CMake
mkdir -p build
cd build
cmake ..
make

# Run individual examples
./simple_api_demo      # Simple API basics
./execute              # Command execution with streaming output
./shutdown             # Runtime shutdown with multiple boxes
./01_lifecycle         # Create / stop / restart / remove
./02_list_boxes        # Discovery and introspection
./03_streaming_output  # Real-time output handling
./04_error_handling    # Error codes, retry, graceful degradation
./05_metrics           # Runtime and per-box metrics

The 8 examples, with a one-line description each (source examples/c/):

Example	Description
`simple_api_demo.c`	Quick start with the Simple API
`execute.c`	Command execution with streaming output
`shutdown.c`	Runtime shutdown with multiple boxes
`01_lifecycle.c`	Complete box lifecycle (create / stop / restart / remove)
`02_list_boxes.c`	Discovery, introspection, ID-prefix lookup
`03_streaming_output.c`	Real-time output handling with callbacks
`04_error_handling.c`	Error codes, retry logic, graceful degradation
`05_metrics.c`	Runtime and per-box metrics

Parameters and returns

Error convention

For every function that returns BoxliteErrorCode: Ok (0) means call-level success; non-zero means an argument/synchronous error, with details written to the CBoxliteError* (i.e. FFIError) you pass. For callback-style functions, the business result (whether creation succeeded, the exit code, etc.) is returned through the CBoxliteError* parameter inside the callback, judged separately from the synchronous return value.

Type/field	Type	Description
`CBoxliteError.code`	`BoxliteErrorCode`	Error-code enum (see below)
`CBoxliteError.message`	`char *`	Detail string, may be NULL; when non-NULL, free with `boxlite_error_free`

The complete enum has 22 entries (Ok = 0 through SessionReaped = 21, verified against sdks/c/include/boxlite.h). Common ones:

Name	Value	Meaning
`Ok`	0	Success
`Internal`	1	Internal error
`NotFound`	2	Box/resource not found
`AlreadyExists`	3	Duplicate name / already exists
`InvalidState`	4	The current state does not allow this operation
`InvalidArgument`	5	Invalid argument (e.g. NULL, empty string)
`Config`	6	Configuration error
`Storage`	7	Storage error
`Image`	8	Image pull/resolve failed
`Network`	9	Network error
`Execution`	10	Command execution failed
`Stopped`	11	Box stopped
`Engine`	12	Engine error
`Unsupported`	13	Unsupported operation
`Database`	14	Database error
`Portal`	15	Host-to-guest RPC transport error
`Rpc`	16	RPC error
`RpcTransport`	17	RPC transport error
`Metadata`	18	Metadata error
`UnsupportedEngine`	19	Unsupported engine (e.g. no virtualization)
`ResourceExhausted`	20	A system resource limit was reached
`SessionReaped`	21	An interactive exec session was reaped server-side after disconnect

Simple API

Function	Key parameters	Returns / outputs
`boxlite_simple_new(image, cpus, memory_mib, &box, &err)`	`image` (required); `cpus`/`memory_mib` = `0` for default	`box` = `CBoxliteSimple`
`boxlite_simple_run(box, command, args, argc, &result, &err)`	`command` (required); `args` is `const charconst`; `argc` = argument count (excluding the command itself)	`result` = `CBoxliteExecResult`
`boxlite_result_free(result)`	—	Free the result (including stdout/stderr strings)
`boxlite_simple_free(box)`	—	Automatically stop + remove + free the runtime; NULL-safe

CBoxliteExecResult:

Field	Type	Description
`exit_code`	`int`	Process exit code (non-zero is not a call error; check it yourself)
`stdout_text`	`char *`	Buffered standard output, may be NULL
`stderr_text`	`char *`	Buffered standard error, may be NULL

Native API core functions

Function	Model	Description
`boxlite_runtime_new(home_dir, registries, count, &rt, &err)`	Synchronous	`home_dir`=NULL uses the default `~/.boxlite`; `registries`=NULL uses the default registries
`boxlite_options_new(image, &opts, &err)`	Synchronous	Create the typed options builder
`boxlite_create_box(rt, opts, cb, user_data, &err)`	Callback	`cb`: `void()(CBoxHandle, CBoxliteError, void)`; the options are cloned
`boxlite_start_box(box, cb, user_data, &err)`	Callback	Restart a stopped box
`boxlite_stop_box(box, cb, user_data, &err)`	Callback	Stop (can be started again; does not consume the handle)
`boxlite_box_exec(box, &cmd, &execution, &err)`	Synchronous	Returns `CExecutionHandle*`; there is no `boxlite_execute`
`boxlite_execution_on_stdout / on_stderr(exec, cb, ud, &err)`	Register callback	`cb`: `void()(const uint8_t, size_t, void)`, not NUL-terminated*
`boxlite_execution_wait(exec, cb, user_data, &err)`	Callback	`cb`: `void()(int exit_code, CBoxliteError, void*)`
`boxlite_execution_stdin_write(exec, data, len, &err)`	Synchronous	Write stdin (byte stream)
`boxlite_execution_tty_resize(exec, rows, cols, cb, ud, &err)`	Callback	Resize the PTY
`boxlite_remove(rt, id_or_name, force, cb, user_data, &err)`	Callback	`force`!=0 removes even if running
`boxlite_runtime_shutdown(rt, timeout_secs, cb, ud, &err)`	Callback	Graceful shutdown; `timeout_secs`: 0 = default 10s, -1 = wait indefinitely, >0 = custom
`boxlite_runtime_drain(rt, timeout_ms, &err)`	Synchronous	Drives callbacks; returns dispatched-event count / -1 on error
`boxlite_box_id(box)`	Synchronous	Returns a `char*`, free with `boxlite_free_string`

timeout_ms semantics for boxlite_runtime_drain:

Value	Behavior
`0`	Non-blocking poll
`< 0`	Block until at least one event
`> 0`	Block at most this many milliseconds

BoxliteCommand: command (required, non-NULL), args/argc, env_pairs (interleaved [k0,v0,k1,v1,...])/env_count, workdir, user, timeout_secs (double, 0.0 = no timeout), tty (int).

Memory and ownership (always free)

Source	Free function
`CBoxliteError.message` (when non-NULL)	`boxlite_error_free(&err)`
String returned by `boxlite_box_id`	`boxlite_free_string(id)`
`CBoxliteExecResult*`	`boxlite_result_free(result)`
`CExecutionHandle*`	`boxlite_execution_free(execution)`
`CBoxliteOptions*`	`boxlite_options_free(opts)` (free once applied)
`CBoxHandle*`	`boxlite_box_free(box)`
`CBoxliteSimple*`	`boxlite_simple_free(box)`
`CBoxliteRuntime*`	`boxlite_runtime_free(runtime)` (reclaims remaining boxes)

All *_free functions are NULL-safe.

Troubleshooting

The linker/runtime cannot find the library

Error dyld: Library not loaded: @rpath/libboxlite.dylib (macOS) or error while loading shared libraries: libboxlite.so (Linux). The dynamic linker was not told the library path. Set it:

# macOS
export DYLD_LIBRARY_PATH=<YOUR_PATH>/boxlite/target/release:$DYLD_LIBRARY_PATH
# Linux
export LD_LIBRARY_PATH=<YOUR_PATH>/boxlite/target/release:$LD_LIBRARY_PATH

Or use CMake (examples/c/CMakeLists.txt already sets BUILD_RPATH, so no manual export is needed).

The callback never fires / the program hangs

The most common Native API pitfall: after calling a callback-style function such as boxlite_create_box / boxlite_execution_wait, you did not call boxlite_runtime_drain. These functions post work to the queue and return immediately; the callback runs on the current thread only during drain. Always call boxlite_runtime_drain(runtime, -1, &err) in a loop while waiting for completion (see drain_until in the Quick Example).

Compile error `implicit declaration of function 'boxlite_execute'`

boxlite_execute does not exist in the current header. To run a command, use boxlite_box_exec(handle, &cmd, &out_execution, &error). Likewise boxlite_create_box / boxlite_execution_wait are callback-style (with cb, user_data parameters) — follow sdks/c/include/boxlite.h.

Box creation fails: `Image error` / non-zero exit code

A failed image pull (the first run needs network) or network flakiness returns Image (8) / Network (9). Check the network, image name spelling (e.g. "alpine:3.19"), and disk space df -h ~/.boxlite; add RUST_LOG=debug ./hello for detailed logs. Note: a non-zero exit code from the command itself (e.g. ls /nonexistent) does not make boxlite_simple_run/boxlite_box_exec return non-Ok — they return Ok, and the exit code is in result->exit_code / the exit_code of on_wait, which you must check yourself.

`UnsupportedEngine` or `kvm: Permission denied` on Linux

No hardware virtualization is available (an environment constraint). Check and enable KVM:

ls -l /dev/kvm                 # should exist and be accessible
sudo modprobe kvm kvm_intel    # Intel; use kvm_amd for AMD
sudo usermod -aG kvm "$USER"   # join the kvm group
newgrp kvm                     # refresh groups (or log in again)

macOS (Apple Silicon) does not need /dev/kvm; it uses the built-in Hypervisor.framework. macOS Intel is not supported and returns UnsupportedEngine (or crashes) — use an ARM64 Mac or Linux instead.

Memory leaks

Diagnose with valgrind --leak-check=full ./hello (Linux) or leaks -atExit -- ./hello (macOS). Common causes: missing boxlite_error_free (free error.message even on the failure path), boxlite_free_string, boxlite_result_free, boxlite_execution_free.

Thread safety

CBoxliteRuntime can be called concurrently from multiple threads; but CBoxHandle / CBoxliteSimple / CExecutionHandle cannot be shared across threads. Callbacks run on the thread that calls boxlite_runtime_drain — do not block inside a callback.

​Prerequisites

​Quick Example

​Native API (callback model)

​Running Examples

​Parameters and returns

​Error convention

​Simple API

​Native API core functions

​Memory and ownership (always free)

​Troubleshooting

​The linker/runtime cannot find the library

​The callback never fires / the program hangs

​Compile error implicit declaration of function 'boxlite_execute'

​Box creation fails: Image error / non-zero exit code

​UnsupportedEngine or kvm: Permission denied on Linux

​Memory leaks

​Thread safety