Airalogy Engine

Airalogy Engine runs protocol packages (parse, assign, validate) inside a BoxLite sandbox. The Python and Node.js packages share the same sandbox image and protocol executor behavior.

Design Rationale

Airalogy Engine separates the protocol runtime into four layers: Docker/BuildKit builds the sandbox environment, OCI image layout stores that environment as a standard portable artifact, BoxLite mounts the artifact and executes protocol code in isolation, and the Engine API exposes stable image, rootfsPath, and file bridge abstractions to host applications.

This design avoids depending on the host Python environment and avoids requiring Docker daemon access during normal protocol execution after the local rootfs has been built. It also keeps the runtime boundary explicit: future CI pipelines, hosted services, or alternative sandbox runtimes can reuse the same OCI artifact and Engine-level API without changing protocol packages or recorder integrations.

Packages

Package	Source	Registry
Python API	packages/pypi/airalogy-engine	PyPI
Node.js API	packages/npm/airalogy-engine	npm
Sandbox image	packages/runtime/airalogy-engine-image	Local Docker/OCI rootfs
Example protocol	examples/airalogy-engine	Repository example
Protocol demo	apps/protocol-demo	Local demo service

Monorepo Layout

packages/
├── pypi/airalogy-engine/        # Python package
├── npm/airalogy-engine/         # Node.js package
└── runtime/airalogy-engine-image/
    ├── Dockerfile
    └── protocol_requirements.txt

examples/airalogy-engine/        # Example protocol package
examples/protocols/              # Official protocol examples
apps/protocol-demo/              # Local engine-backed demo

Sandbox Image

Build the shared sandbox image from the runtime package:

pnpm build:engine-rootfs

Building the local rootfs requires a running Docker daemon. On macOS, start Docker Desktop from Applications or run open -a Docker, then wait until docker info succeeds before running pnpm build:engine-rootfs or pnpm build:engine-rootfs:force. If you use Colima, Rancher Desktop, or another Docker-compatible runtime, start that runtime and make sure your Docker context points to it.

The build script exports an OCI layout, so it automatically creates and uses a Buildx builder with the docker-container driver. Docker's default docker driver cannot export type=oci. If you need a different builder name, pass --builder <name> or set AIRALOGY_ENGINE_BUILDX_BUILDER.

This creates the default rootfs at packages/runtime/airalogy-engine-image/airalogy-engine-image. Rebuild it after runtime dependency changes with:

pnpm build:engine-rootfs:force

What is an OCI rootfs?

OCI stands for Open Container Initiative. The exported rootfs is an OCI image layout directory, which is a standard local directory format for container images, not a traditional unpacked Linux filesystem and not a Docker-specific format. It contains oci-layout, index.json, and blobs/sha256/... entries, which BoxLite can mount as the sandbox filesystem. If the directory exists but does not contain oci-layout, treat it as an incomplete build and rebuild it with pnpm build:engine-rootfs:force.

Pass the exported rootfs directory to either engine package.

Python

Install from PyPI:

pip install airalogy-engine

Use a local rootfs:

from airalogy_engine import AiralogyEngine

engine = AiralogyEngine(rootfs_path="./airalogy-engine-image")
result = await engine.parse_protocol("./protocol")

Node.js

Install from npm:

pnpm add @airalogy/airalogy-engine

Use a local rootfs:

import { parseProtocol } from "@airalogy/airalogy-engine";

const result = await parseProtocol("./protocol", {
  rootfsPath: "./airalogy-engine-image",
});

Protocol Demo

Run the local demo service from the repository root:

pnpm dev:protocol-demo:full

The demo loads examples/protocols, shows the AIMD recorder surface, and calls the Node.js engine package for parse, validate, and assign operations.

Tests

Python package:

cd packages/pypi/airalogy-engine
uv run pytest tests/ -v --sandbox-mode=rootfs \
  --rootfs-path=../../runtime/airalogy-engine-image/airalogy-engine-image

Node.js package:

cd packages/npm/airalogy-engine
SANDBOX_MODE=rootfs \
ROOTFS_PATH=../../runtime/airalogy-engine-image/airalogy-engine-image \
AIRALOGY_ENGINE_RUN_SANDBOX_TESTS=1 \
pnpm test

Without a local rootfs, the Node.js test command runs path-validation tests and skips sandbox integration cases so the package remains testable on machines without BoxLite runtime support.