> ## Documentation Index
> Fetch the complete documentation index at: https://docs.boxlite.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# C Quick Start

> Get up and running with BoxLite C SDK in 5 minutes.

## Installation

### Prerequisites

<Tabs>
  <Tab title="macOS">
    * macOS 12+ (Monterey or later)
    * Xcode Command Line Tools: `xcode-select --install`
    * GCC or Clang
  </Tab>

  <Tab title="Linux">
    * x86\_64 or ARM64 architecture
    * KVM enabled (`/dev/kvm` accessible)
    * GCC or Clang, CMake 3.15+
  </Tab>
</Tabs>

### Building the SDK

<Steps>
  <Step title="Clone the repository">
    ```bash theme={null}
    git clone https://github.com/boxlite-ai/boxlite.git
    cd boxlite
    ```
  </Step>

  <Step title="Initialize submodules">
    <Warning>
      This step is required! The build will fail without submodules.
    </Warning>

    ```bash theme={null}
    git submodule update --init --recursive
    ```
  </Step>

  <Step title="Build C SDK">
    ```bash theme={null}
    cargo build --release -p boxlite-c

    # Outputs:
    # - target/release/libboxlite.{dylib,so}  (shared library)
    # - target/release/libboxlite.a           (static library)
    # - sdks/c/include/boxlite.h              (header file)
    ```
  </Step>

  <Step title="Verify build">
    ```bash theme={null}
    ls -la target/release/libboxlite.*
    ls -la sdks/c/include/boxlite.h
    ```
  </Step>
</Steps>

***

## Simple API (Easiest)

<Steps>
  <Step title="Create a file hello.c">
    ```c theme={null}
    #include <stdio.h>
    #include "boxlite.h"

    int main() {
        CBoxliteSimple* box = NULL;
        CBoxliteError error = {0};

        // Create box (no JSON required, auto-starts)
        if (boxlite_simple_new("python:slim", 0, 0, &box, &error) != Ok) {
            fprintf(stderr, "Error %d: %s\n", error.code, error.message);
            boxlite_error_free(&error);
            return 1;
        }

        // Run command and get buffered result
        const char* args[] = {"-c", "print('Hello from BoxLite!')", NULL};
        CBoxliteExecResult* result = NULL;

        if (boxlite_simple_run(box, "python", args, 2, &result, &error) == Ok) {
            printf("Output: %s", result->stdout_text);
            printf("Exit code: %d\n", result->exit_code);
            boxlite_result_free(result);
        } else {
            fprintf(stderr, "Exec error: %s\n", error.message);
            boxlite_error_free(&error);
        }

        boxlite_simple_free(box);  // Auto-cleanup
        return 0;
    }
    ```
  </Step>

  <Step title="Build and run">
    <Tabs>
      <Tab title="macOS">
        ```bash theme={null}
        gcc -o hello hello.c \
            -I/path/to/boxlite/sdks/c/include \
            -L/path/to/boxlite/target/release \
            -lboxlite

        export DYLD_LIBRARY_PATH=/path/to/boxlite/target/release:$DYLD_LIBRARY_PATH
        ./hello
        ```
      </Tab>

      <Tab title="Linux">
        ```bash theme={null}
        gcc -o hello hello.c \
            -I/path/to/boxlite/sdks/c/include \
            -L/path/to/boxlite/target/release \
            -lboxlite

        export LD_LIBRARY_PATH=/path/to/boxlite/target/release:$LD_LIBRARY_PATH
        ./hello
        ```
      </Tab>
    </Tabs>
  </Step>
</Steps>

**What's happening:**

1. BoxLite pulls the `python:slim` OCI image (first run only)
2. Creates a lightweight VM with the image
3. Executes the Python command inside the VM
4. Buffers stdout/stderr and returns the result
5. Automatically cleans up when `boxlite_simple_free()` is called

***

## Native API (Full Control)

For advanced use cases with streaming output and custom configuration.

<Steps>
  <Step title="Create a file native.c">
    ```c theme={null}
    #include <stdio.h>
    #include "boxlite.h"

    void output_callback(const char* text, int is_stderr, void* user_data) {
        FILE* stream = is_stderr ? stderr : stdout;
        fprintf(stream, "%s", text);
    }

    int main() {
        CBoxliteRuntime* runtime = NULL;
        CBoxHandle* box = NULL;
        CBoxliteError error = {0};

        // Create runtime
        if (boxlite_runtime_new(NULL, NULL, &runtime, &error) != Ok) {
            fprintf(stderr, "Runtime error: %s\n", error.message);
            boxlite_error_free(&error);
            return 1;
        }

        printf("BoxLite v%s\n", boxlite_version());

        // Create box with JSON configuration
        const char* options = "{"
            "\"rootfs\":{\"Image\":\"alpine:3.19\"},"
            "\"cpus\":2,"
            "\"memory_mib\":512,"
            "\"env\":[],"
            "\"volumes\":[],"
            "\"network\":\"Isolated\","
            "\"ports\":[]"
        "}";

        if (boxlite_create_box(runtime, options, &box, &error) != Ok) {
            fprintf(stderr, "Box error: %s\n", error.message);
            boxlite_error_free(&error);
            boxlite_runtime_free(runtime);
            return 1;
        }

        // Execute commands with streaming output
        int exit_code = 0;

        printf("\n--- Running: ls -la / ---\n");
        if (boxlite_execute(box, "/bin/ls", "[\"-la\", \"/\"]", output_callback, NULL, &exit_code, &error) == Ok) {
            printf("\nExit code: %d\n", exit_code);
        } else {
            fprintf(stderr, "Execute error: %s\n", error.message);
            boxlite_error_free(&error);
        }

        // Cleanup (runtime frees all boxes)
        boxlite_runtime_free(runtime);
        return 0;
    }
    ```
  </Step>

  <Step title="Build and run">
    Build and run using the same commands as the Simple API above.
  </Step>
</Steps>

***

## Running Examples

BoxLite includes 8 comprehensive C examples:

```bash theme={null}
# Navigate to examples
cd examples/c

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

# Run examples
./simple_api_demo    # Simple API basics
./execute            # Command execution with streaming
./shutdown           # Graceful shutdown
./01_lifecycle       # Create/stop/restart/remove
./02_list_boxes      # Discovery and introspection
./03_streaming_output  # Real-time output handling
./04_error_handling  # Error recovery patterns
./05_metrics         # Performance monitoring
```

**Examples overview:**

| Example                 | Description                                         |
| ----------------------- | --------------------------------------------------- |
| `simple_api_demo.c`     | Quick start with 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                         |

***

## Error Handling

The C SDK uses structured error handling:

```c theme={null}
CBoxliteError error = {0};  // Always initialize to zero
BoxliteErrorCode code = boxlite_simple_new(..., &error);

if (code != Ok) {
    // Check specific error codes
    switch (code) {
        case NotFound:
            printf("Resource not found\n");
            break;
        case Image:
            printf("Image pull failed: %s\n", error.message);
            break;
        default:
            printf("Error %d: %s\n", code, error.message);
    }
    boxlite_error_free(&error);  // Always free on error
}
```

**Error codes:**

| Code | Name              | Description                  |
| ---- | ----------------- | ---------------------------- |
| `0`  | `Ok`              | Success                      |
| `2`  | `NotFound`        | Resource not found           |
| `5`  | `InvalidArgument` | Invalid parameter            |
| `8`  | `Image`           | Image pull/resolution failed |
| `10` | `Execution`       | Command execution failed     |

See [C SDK API Reference](/reference/c/errors-metrics) for the complete list.

***

## Next Steps

<CardGroup cols={2}>
  <Card title="Core concepts" icon="lightbulb" href="/getting-started/core-concepts">
    Understand the different box types, lifecycle, images, and resource configuration.
  </Card>

  <Card title="C SDK Reference" icon="book" href="/reference/c/index">
    Complete SDK documentation covering Simple API and Native API details, JSON configuration schema, Memory management rules, Threading and safety, and Troubleshooting guide.
  </Card>

  <Card title="C API Reference" icon="code" href="/reference/c/native-api">
    Function signatures and parameters for the C SDK.
  </Card>

  <Card title="C Examples" icon="flask" href="https://github.com/boxlite-ai/boxlite/tree/main/examples/c">
    Working code examples on GitHub.
  </Card>
</CardGroup>