> ## 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.

# SDK Reference

> Complete API reference for all BoxLite SDKs

Complete reference for BoxLite APIs, configuration, and error handling.

## SDK API References

Complete API documentation for each SDK:

| SDK         | Description                                      |
| ----------- | ------------------------------------------------ |
| **Python**  | Async/sync API, box types, metrics               |
| **Node.js** | TypeScript definitions, box types, CDP endpoints |
| **Rust**    | Core runtime, stream APIs, security options      |
| **C**       | FFI bindings, JSON API, callback streaming       |

<CardGroup cols={2}>
  <Card title="Python SDK" icon="python" href="/reference/python/index">
    Async and sync APIs, box types, code execution, metrics. Python 3.10+.
  </Card>

  <Card title="Node.js SDK" icon="node-js" href="/reference/nodejs/index">
    TypeScript definitions, box types, CDP endpoints for browser automation.
  </Card>

  <Card title="Rust SDK" icon="rust" href="/reference/rust/index">
    Core runtime, stream APIs, security options. Native performance.
  </Card>

  <Card title="C SDK" icon="c" href="/reference/c/index">
    FFI bindings, JSON API, callback streaming for system-level integration.
  </Card>
</CardGroup>

## Quick Reference

### Python API

For complete Python API documentation, see **[Python API Reference](/reference/python/index)**.

**Key Classes:**

| Class            | Description                                  |
| ---------------- | -------------------------------------------- |
| `Boxlite`        | Main runtime for creating and managing boxes |
| `Box`            | Handle to a running or stopped box           |
| `SimpleBox`      | Context manager for basic execution          |
| `CodeBox`        | Specialized box for Python code execution    |
| `BrowserBox`     | Box configured for browser automation        |
| `ComputerBox`    | Box with desktop automation capabilities     |
| `InteractiveBox` | Box for interactive shell sessions           |

### Node.js API

For complete Node.js API documentation, see **[Node.js API Reference](/reference/nodejs/index)**.

**Key Classes:**

| Class            | Description                           |
| ---------------- | ------------------------------------- |
| `SimpleBox`      | Basic container for command execution |
| `CodeBox`        | Python code execution sandbox         |
| `BrowserBox`     | Browser automation with CDP endpoint  |
| `ComputerBox`    | Desktop automation (14 methods)       |
| `InteractiveBox` | PTY terminal sessions                 |

### Rust API

For complete Rust API documentation, see **[Rust API Reference](/reference/rust/index)**.

**Core Types:**

```rust theme={null}
use boxlite::{
    BoxliteRuntime,  // Main runtime
    BoxOptions,       // Box configuration
    LiteBox,          // Box handle
    BoxCommand,       // Command builder
    RootfsSpec,       // Rootfs specification
    VolumeSpec,       // Volume mount specification
    PortSpec,         // Port forwarding specification
};
```

### C API

For complete C API documentation, see **[C API Reference](/reference/c/index)**.

**Functions:**

| Function              | Description                |
| --------------------- | -------------------------- |
| `boxlite_runtime_new` | Create runtime instance    |
| `boxlite_create_box`  | Create a new box           |
| `boxlite_execute`     | Run command with streaming |
| `boxlite_stop_box`    | Stop and free box          |

## SDK Feature Comparison

| Feature        | Python         | Node.js    | Rust           | C              |
| -------------- | -------------- | ---------- | -------------- | -------------- |
| Async API      | Yes            | Yes        | Yes            | Callback-based |
| Sync API       | Yes (greenlet) | No         | Yes (blocking) | Yes            |
| SimpleBox      | Yes            | Yes        | Yes            | Yes            |
| CodeBox        | Yes            | Yes        | No             | No             |
| BrowserBox     | Yes            | Yes        | No             | No             |
| ComputerBox    | Yes            | Yes        | No             | No             |
| InteractiveBox | Yes            | Yes        | No             | No             |
| Streaming I/O  | Yes            | Yes        | Yes            | Yes            |
| Metrics        | Yes            | Yes        | Yes            | Yes            |
| Type Safety    | Type hints     | TypeScript | Native         | Manual         |

## Configuration Reference

For complete BoxOptions parameter documentation, see the SDK-specific pages:

* [Python BoxOptions](/reference/python/box-types#boxoptions) — `image`, `cpus`, `memory_mib`, `volumes`, `ports`, `env`, etc.
* [Node.js JsBoxOptions](/reference/nodejs/index#jsoptions) — TypeScript interface
* [Rust BoxOptions](/reference/rust/box-config) — Struct definition with `RootfsSpec`, `SecurityOptions`, etc.
* [C JSON Schema](/reference/c/memory-json-threading#json-schema-reference) — JSON format for `boxlite_create_box()`

### Runtime Options

#### `home_dir: str`

Base directory for BoxLite runtime data.

**Default:** `~/.boxlite`

**Override:** Set `BOXLITE_HOME` environment variable

**Structure:**

```text theme={null}
~/.boxlite/
├── images/       # OCI image cache (blobs, index.json)
├── boxes/        # Per-box data (config.json, disk.qcow2)
├── init/         # Shared guest rootfs
├── logs/         # Runtime logs
├── gvproxy/      # Network backend binaries
├── lock          # Filesystem lock file
└── db/           # SQLite databases (boxes.db, images.db)
```

### Environment Variables

| Variable         | Default      | Description                                                     |
| ---------------- | ------------ | --------------------------------------------------------------- |
| `BOXLITE_HOME`   | `~/.boxlite` | Override runtime home directory                                 |
| `RUST_LOG`       | -            | Debug logging level (`trace`, `debug`, `info`, `warn`, `error`) |
| `BOXLITE_TMPDIR` | System temp  | Override temporary directory                                    |

```bash theme={null}
# Example: enable debug logging
RUST_LOG=debug python script.py

# Example: module-specific logging
RUST_LOG=boxlite::runtime=debug python script.py
```

## Error Codes & Handling

For detailed error types and handling patterns, see the SDK-specific error pages:

* [Python Errors & Metrics](/reference/python/errors-metrics)
* [Node.js Errors & Metrics](/reference/nodejs/errors-metrics)
* [Rust Errors & Metrics](/reference/rust/errors-metrics)
* [C Errors & Metrics](/reference/c/errors-metrics)

## File Formats

### QCOW2 Disk Images

BoxLite uses QCOW2 (QEMU Copy-On-Write version 2) for persistent disks.

**Location:** `~/.boxlite/boxes/{box-id}/disk.qcow2`

**Features:**

* Thin provisioning (sparse allocation)
* Copy-on-write snapshots
* Compression support

**Tools:**

```bash theme={null}
# Inspect QCOW2 image
qemu-img info ~/.boxlite/boxes/{box-id}/disk.qcow2

# Convert to raw (if needed)
qemu-img convert -f qcow2 -O raw disk.qcow2 disk.raw
```

### OCI Image Cache

BoxLite caches OCI images at the layer level for fast starts.

**Location:** `~/.boxlite/images/`

**Structure:**

```text theme={null}
~/.boxlite/images/
├── blobs/
│   └── sha256/
│       ├── abc123...  # Layer blob
│       ├── def456...  # Layer blob
│       └── ...
└── index.json         # Image index
```

<Note>
  Blob-level deduplication across images means shared base layers (e.g., `python:3.11` and `python:3.12`) are stored only once.
</Note>

**Clearing Cache:**

```bash theme={null}
# Clear all cached images
rm -rf ~/.boxlite/images/*

# Images will be re-pulled on next use
```

### Box Configuration

Box metadata and state are stored as JSON.

**Location:** `~/.boxlite/boxes/{box-id}/config.json`

**Example:**

```json theme={null}
{
  "id": "01JJNH8...",
  "image": "python:slim",
  "cpus": 2,
  "memory_mib": 1024,
  "volumes": [
    {
      "host_path": "/host/data",
      "guest_path": "/mnt/data",
      "read_only": true
    }
  ],
  "ports": [
    {
      "host_port": 8080,
      "guest_port": 80,
      "protocol": "tcp"
    }
  ],
  "created_at": "2025-01-15T10:30:00Z",
  "status": "running"
}
```

<Warning>
  Do not manually edit box configuration files. They are managed by BoxLite and manual changes may cause unexpected behavior.
</Warning>

### SQLite Databases

BoxLite uses SQLite for metadata persistence.

**Locations:**

* `~/.boxlite/db/boxes.db` - Box registry and metadata
* `~/.boxlite/db/images.db` - Image cache index

**Tools:**

```bash theme={null}
# Inspect database
sqlite3 ~/.boxlite/db/boxes.db ".tables"
sqlite3 ~/.boxlite/db/boxes.db "SELECT * FROM boxes;"

# Backup
cp ~/.boxlite/db/boxes.db ~/backup/boxes.db.backup
```

<Warning>
  Do not manually modify the SQLite databases. Data corruption may result. Corruption recovery: delete and recreate from box config files.
</Warning>