Boruna

v3.0.0 is the current release. The 1.x line remains under long-term support — active through 2027-11-15, security through 2028-05-15. See docs/lts.md for support windows, deprecation policy, and security-backport SLAs.

Deterministic, policy-gated workflow execution for AI systems that must be auditable.

The problem

Most AI orchestration tools run workflows and return outputs. When something goes wrong — or when a regulator asks — there is no reliable way to answer: What exactly ran? What did the model see? What did it return? Can you prove it?

Boruna answers those questions by design.

Every Boruna workflow run produces a tamper-evident evidence bundle: a hash-chained audit log of every step executed, every capability invoked, every model response received. That bundle can be inspected, verified, and replayed — without network access, without a central server, without trusting anyone’s word.

This makes Boruna suited for teams building AI workflows that touch regulated data, make consequential decisions, or need a defensible audit trail.

What Boruna provides

• DAG workflow execution — steps are .ax source files; the workflow is a workflow.json DAG definition (schema_version: 1 frozen at 1.0)
• Capability enforcement — every side effect (LLM calls, HTTP, database, filesystem) is declared and policy-gated at the VM level
• Evidence bundles — hash-chained tamper-evident logs, written automatically with --record. Optional AES-256-GCM envelope encryption for compliance-sensitive deployments. evidence inspect shows step output content for plaintext bundles.
• Deterministic replay — re-execute any recorded workflow with identical outputs, verified by the VM
• Approval gates — pause workflow execution for human review or external triggers before continuing
• Diagnostics, auto-repair, and migration — boruna lang check, boruna lang repair, boruna migrate for .ax files and bundle/workflow upgrades
• boruna new — interactive scaffold for new workflows from templates
• 33 built-in functions — string (12), list (7), and map (7) operations plus type conversions and debug builtins (__builtin_string_*, __builtin_list_*, __builtin_map_*, …) available in every .ax file without imports
• Import resolution — import "std-name" inlines libs/<name>/src/core.ax at compile time; 14 stdlib packages (the original 13 are 1.0-stable)
• Four formal versioned specifications — .ax language 1.0, bytecode 1.0, evidence bundle format 1.0, workflow DAG schema 1.0 (all under docs/spec/)
• MCP server — exposes 14 tools for AI coding agent integration (Claude Code, Cursor, Codex)

What Boruna is not

• Not a general-purpose language or runtime (use Rust, Python, Go for that)
• Not an LLM framework (use LangChain, LCEL, etc. for prompt engineering)
• Not a cloud service (Boruna runs wherever you deploy it)
• Not a key-management system (operators wire HSM / KMS integration themselves; bundle-encryption KEK lifecycle is operator-owned)

Install

Linux and macOS:

curl -fsSL https://raw.githubusercontent.com/escapeboy/boruna/master/install.sh | sh

Windows (PowerShell):

irm https://raw.githubusercontent.com/escapeboy/boruna/master/install.ps1 | iex

Both scripts pick the right build for your OS and CPU, check it against the release’s SHA256SUMS and refuse to install on a mismatch, then put boruna, boruna-mcp, boruna-pkg and boruna-orch in ~/.local/bin (Windows: %LOCALAPPDATA%\Programs\boruna\bin, added to your user PATH). Set BORUNA_VERSION=v3.4.0 to pin a version or BORUNA_INSTALL_DIR to choose the folder. Read install.sh / install.ps1 first if you prefer not to pipe a script into your shell.

Check the installation with boruna --version and boruna doctor.

# Linux x86_64 (musl — works on Alpine, Ubuntu, Debian, ...)
curl -fsSL https://github.com/escapeboy/boruna/releases/latest/download/SHA256SUMS -o SHA256SUMS
TARGET=x86_64-unknown-linux-musl
TAR=$(grep "$TARGET" SHA256SUMS | awk '{print $2}')
curl -fsSLO "https://github.com/escapeboy/boruna/releases/latest/download/$TAR"
grep "$TAR" SHA256SUMS | sha256sum -c -
tar -xzf "$TAR"
./boruna-*-${TARGET}/boruna --version

$base = "https://github.com/escapeboy/boruna/releases/latest/download"
Invoke-WebRequest "$base/SHA256SUMS" -OutFile SHA256SUMS
$target = "x86_64-pc-windows-msvc"   # or aarch64-pc-windows-msvc on Windows on Arm
$zip = ((Select-String -Path SHA256SUMS -Pattern $target).Line -split "\s+")[1].TrimStart("*")
Invoke-WebRequest "$base/$zip" -OutFile $zip
# Compare this hash with the line for $zip in SHA256SUMS:
(Get-FileHash $zip -Algorithm SHA256).Hash.ToLower()
Expand-Archive $zip -DestinationPath .
.\boruna-*-$target\boruna.exe --version

Supported platforms

Every platform below is built and its full test suite is run natively on a real machine of that type in CI (no emulation), together with an example workflow and evidence verify.

Other targets (FreeBSD, 32-bit, RISC-V and so on) are not built or tested; build from source and run cargo test --workspace to see whether they work for you. See docs/releasing.md.

Or build from source:

git clone https://github.com/escapeboy/boruna
cd boruna
cargo build --workspace --release

Quickstart

# Run a workflow
boruna workflow run examples/workflows/llm_code_review --policy allow-all --record

# Verify the evidence bundle
boruna evidence verify .boruna/runs/<run-id>/

→ Full Quickstart — 10 minutes, ends with a verified evidence bundle.

Example workflows

Each example runs in demo mode (no external services) and produces a verifiable evidence bundle.

How the evidence guarantee works

workflow.json  →  DAG Validator  →  Step Runner
                                        ↓
                                   .ax source
                                        ↓
                                   Compiler → Bytecode
                                        ↓
                                   VM (capability gateway)
                                        ↓
                                   EventLog entry (CapCall + CapResult)
                                        ↓
                              Hash-chained audit log

boruna evidence verify <bundle>
  → Chain integrity: VALID
  → All step hashes: MATCH
  → Verification: PASSED

Every CapCall (including LLM calls) is logged with its full response. The log is SHA-256 hash-chained from a genesis entry containing the workflow definition hash. Modification of any entry breaks the chain.

Architecture

Boruna is a Rust workspace with 10 production crates plus a benches/ member:

1175+ tests across 11 workspace members. cargo test --workspace — all pass.

Documentation

Status

Boruna is at v3.0.0 — the release that removes the entire HTTP / serving / distributed-execution layer. Gone are the distributed coordinator, distributed workers, active-active HA and coordinator mTLS, the three web UIs (workflow dashboard, evidence web viewer, approval console), and the serve cargo feature and its server dependencies. What remains is a local deterministic engine and CLI: compiler → capability-gated VM → orchestrator (runner, persistence, audit) → tamper-evident evidence bundles. Approval and external-trigger gates are still handled locally via boruna workflow approve/reject/trigger plus resume. This is a breaking release — the coordinator, dashboard, worker, and evidence serve CLI commands, the --coordinator / --coord-token flags, and the serve feature are removed — so review the 3.0.0 entry in CHANGELOG.md. The core execution engine, evidence bundles, and four formal versioned specifications (.ax language, bytecode, workflow DAG, evidence bundle) remain feature-complete; the 1.x LTS line continues per docs/lts.md.

The project is suited for evaluation, internal tooling, and audit-sensitive AI pipelines. Operator action: validate the docs/PERFORMANCE.md budget against your workload, and review docs/limitations.md for known constraints. External security audit booking is the Q4 2026 commitment in lts.md.

See docs/stability.md for the stability tier breakdown.

For coding agents

Boruna exposes an MCP server for AI coding agent integration. See AGENTS.md for integration instructions and the tool reference.

Contributing

See CONTRIBUTING.md. The short version: open an issue, implement with tests, run cargo test --workspace + cargo clippy + cargo fmt, add a CHANGELOG entry, open a PR.

License

MIT — Copyright 2026 Boruna Contributors

Edit this page on GitHub