Vox Programming Language

The AI-Native Programming Language

One language. Database, backend, UI, and agent tools — designed first as a target for large language models, and for the developers who work alongside them.

Get Started Syntax Reference

“Is it a fact — or have I dreamt it — that, by means of electricity, the world of matter has become a great nerve, vibrating thousands of miles in a breathless point of time? Rather, the round globe is a vast head, a brain, instinct with intelligence!”
— Nathaniel Hawthorne, The House of the Seven Gables (1851)

The Architecture: Designed for AI and Humans

Programming languages predate LLMs by decades. JavaScript's dynamic typing fails silently at runtime, C++'s pointer mutation hides state, and Python's configuration layers run deep. While human developers manage these trade-offs, for an AI agent navigating them simultaneously, they compound into hallucination.

A million-token context window sounds generous until the signal is buried in boilerplate¹. Decades of patching the object-relational impedance mismatch² have ballooned the accidental complexity³ and technical debt of modern systems⁴, leaving codebases too brittle for agents to safely refactor.

The Architecture: Designed for AI and Humans

Programming languages predate LLMs by decades. JavaScript's dynamic typing fails silently at runtime, C++'s pointer mutation hides state, and Python's configuration layers run deep. While human developers manage these trade-offs, for an AI agent navigating them simultaneously, they compound into hallucination.

A million-token context window sounds generous until the signal is buried in boilerplate¹. Decades of patching the object-relational impedance mismatch² have ballooned the accidental complexity³ and technical debt of modern systems⁴, leaving codebases too brittle for agents to safely refactor.

Platform Architecture & Stability

Stability is stratified by model predictability. Core surfaces (data, logic, memory) lock first; rendering surfaces remain fluid.

Stability Tiers

• 🟢 Stable — rules locked; LLM output is deterministic.
• 🟡 Preview — functionally complete; execution pipelines still optimizing.
• 🚧 Experimental — under active design; not deployable.

Domain Matrix

(v0.4, April 2026)

Pillar 1: The Single Source of Truth

Agents require a single source of truth. A core concept like a Task no longer needs to be defined three times across SQL, the backend API, and the client. The @table primitive collapses schema and interface into one AST node.

#![allow(unused)]
fn main() {
// [ @table ]
// Auto-generates SQL and gracefully handles schema migrations.
@table type Task {
    title:    str
    done:     bool
    priority: int
    owner:    str
}

// [ @index ]
// The database index, declared inline next to the type.
@index Task.by_owner on (owner)
}

Pillar 2: Compile-Time Determinism

Agents ignore edge cases. By eliminating hidden exceptions in favor of a strict Result[T] type, Vox makes unhandled errors a compile-time failure, granting immediate syntax-level feedback before broken code executes.

#![allow(unused)]
fn main() {
// [ @query ]
// Read-only endpoint; Vox strictly enforces that it never mutates data.
// Becomes a GET /api/query/recent_tasks endpoint automatically.
@query
fn recent_tasks() to list[Task] {
    ret db.Task
        .where({ done: false })
        .order_by("priority", "desc")
        .limit(10)
}

// [ Result[Task] ]
// Forces every caller to handle both success and error branches.
// The compiler will not build code that ignores an error.
@server fn get_task(id: Id[Task]) to Result[Task] {
    let row = db.Task.find(id)
    match row {
        Some(t) -> Ok(t)               // Task found: return it
        None    -> Error("not found")  // Task missing: return an error
    }
}

// [ @mutation ]
// Auto-transacted write; automatically rolls back on network or logic failure.
@mutation
fn add_task(title: str, owner: str) to Id[Task] {
    ret db.insert(Task, {
        title: title,
        done: false,
        priority: 0,
        owner: owner
    })
}
}

Pillar 3: Strict Network Boundaries (Web UI)

WebIR restricts interactive state to explicit boundaries (@island), protecting the agent's context window. The compiler natively implements the "Islands Architecture"⁶ without exposing React hooks or lifecycle waterfalls inside the .vox source file.

#![allow(unused)]
fn main() {
// [ @island ]
// Marks the browser boundary. The compiler generates the React component,
// lifecycle wiring, and typed client stub. None of it appears in the .vox source.
@island TaskList {
    tasks: list[Task]              // Same Task type from Pillar 1
    on_complete: fn(str) -> Unit   // A callback the browser can easily trigger
}

// [ component ]
// Server-rendered execution: fast initial load, written entirely in Vox syntax.
// React's hooks and lifecycles are strictly confined to the generated layer.
component TaskPage() {
    view: (
        <div className="task-list">
            <TaskList
                tasks=[...]
                on_complete={complete_task}
            />
        </div>
    )
}

// [ routes ]
// Safely maps the URL directly to the statically verifiable component.
routes { "/" to TaskPage }
}

v0.dev integration: vox island generate TaskDashboard "A minimal sidebar dashboard" calls the v0.dev API (requires V0_API_KEY) and writes the generated component into islands/src/TaskDashboard/. The @v0 build hook triggers this automatically during vox build.

Pillar 4: Durable State & Agent Interoperability

Multi-agent pipelines crash, and external tools fail. By integrating durable execution⁷ and the "let it crash" actor model⁸, a workflow guarantees state survival automatically.

The @mcp.tool decorator projects these hardened native functions directly to Anthropic's Model Context Protocol (MCP)⁵ for external tool use.⁹

#![allow(unused)] fn main() { // [ activity: Compute Node Execution ] // Flaky steps that execute on transient workers (Node A/B). activity charge_card(req: int) to Result[str] { // If a node dies (DEAD OOM EVENT), Vox retries automatically ret Ok("tx_123") } // [ workflow: Durable Orchestration ] // Commits state to the Arca Vault (SQLite). If Node A crashes, // the workflow rehydrates and safely resumes on Node B. workflow checkout(req: int) to str { let result = charge_card(req) match result { Ok(tx) -> "Result: Ok(" + tx + ")" Error(e) -> "Fault: " + e } } // [ @mcp.tool: MCP Interface ] // Expose the durable workflow to Anthropic's protocol boundary. @mcp.tool "Process durable checkout" fn complete_purchase(req: int) to str { checkout(req) } }

Pillar 5: Solving the Training Paradox

Legacy languages saturate the internet's training data. To catch up, vox populi and the MENS pipeline allow you to locally fine-tune foundation models natively on Vox's structural boundaries, bridging the data gap using Rust-accelerated pipelines.

More: examples/golden/ · Rosetta comparison (C++, Rust, Python)

The Language, Step by Step

Step 1 — Declare your data model once

// vox:skip
@require(len(self.title) > 0)
@table type Task {
    title:    str
    done:     bool
    priority: int
    owner:    str
}

@index Task.by_owner on (owner)
@index Task.by_priority on (priority, done)

@require is a compiler-enforced precondition on the type itself. @index emits DDL alongside the table migration.

Step 2 — Add server logic and queries

// vox:skip
@mutation
fn add_task(title: str, owner: str) to Id[Task] {
    ret db.insert(Task, { title: title, done: false, priority: 0, owner: owner })
}

@server fn complete_task(id: Id[Task]) to Result[Unit] {
    db.Task.delete(id)
    ret Ok(Unit)
}

@query
fn recent_incomplete_tasks() to List[Task] {
    ret db.Task.where({ done: false }).order_by("priority", "desc").limit(10)
}

Step 3 — Build the UI in the same language

Vox generates the network call, serialization, and cross-boundary types — no fetch wrapper, no client SDK:

// vox:skip
import react.use_state

@island
fn TaskList(tasks: List[Task]) to Element {
    let (items, set_items) = use_state(tasks)

    <div class="task-list">
        {items.map(fn(task) {
            <div class="task-row">
                <input
                    type="checkbox"
                    checked={task.done}
                    onChange={fn(_e) complete_task(task.id)}
                />
                <span>{task.title}</span>
            </div>
        })}
    </div>
}

Step 4 — Handle absence and failure explicitly

// vox:skip
@server fn get_task(id: Id[Task]) to Result[Task] {
    let row = db.Task.find(id)
    match row {
        Some(t) -> Ok(t)
        None    -> Error("task not found")
    }
}

Step 5 — Add durable workflows and stateful actors

// vox:skip
workflow checkout(amount: int) to str {
    let result = charge_card(amount)
    match result {
        Ok(tx)     -> "Success: " + tx
        Error(msg) -> "Failed: " + msg
    }
}

Step 6 — Expose functions as AI tools

// vox:skip
@mcp.tool "Search the knowledge base for documents matching the query"
fn search_knowledge(query: str, max_results: int) to SearchResult {
    Found("Result for: " + query, 95)
}

Agent Orchestration & AI Capabilities

Vox goes beyond just syntax. It includes a full AI ecosystem built directly into the toolchain:

• Multi-Agent Coordination: The DEI orchestrator (vox-dei) routes concurrent tasks by file affinity and role. Every state transition is persisted and traceable.
• Agent-to-Agent Messaging: Agents exchange typed, JWE-encrypted envelopes over a structured bus, ensuring compile-time shape guarantees for AI interactions.
• Local GPU & Native Training (MENS): The MENS neural pipeline natively equips developers to fine-tune models using Burn and Candle. No Python required. vox populi probe orchestrates:
  1. QLoRA Fine-Tuning against your internal repositories.
  2. Speech-to-Code (ASR) via local Whisper/Qwen to map vocal commands to AST edits.
  3. Local Mesh Serving securely exposing models over a /v1/completions endpoint for offline execution.

Documentation Structure

Vox uses the Diátaxis framework to organize knowledge by user intent.

Community, Backing & License

Backing Vox (Open Collective)

Community-backed via Open Collective — every dollar raised and spent is public. Sponsorships fund developer grants, CI hardware for MENS neural training, and academic bounties.

Open Collective →

License

Apache 2.0 — commercial use permitted, patent rights granted, modifications allowed with attribution.

LICENSE · github.com/vox-foundation/vox

Get Involved

Vox Scientia aggregates community research wherever developers are talking. Roadmap decisions and architectural questions are tracked in GitHub Discussions — the format our tooling can index, parse, and feed back into the system.

• GitHub Discussions: Architecture questions, language design feedback, and roadmap input.
• RSS Feed: vox-lang.org/feed.xml — changelogs and architectural decision records.

Quick Documentation Links

• Installation Guide: Set up the vox toolchain on your machine.
• Master Architecture Index: Deep dives into the compiler and runtime internals.

Getting Started with Vox

This guide takes you from zero to a running full-stack app in under 5 minutes.

Prerequisites

Before you begin, make sure you have:

• Rust (1.81+) — Install
• Node.js (20+) — Install
• pnpm (9+) — npm install -g pnpm

Tip: Run vox doctor to check all dependencies and environment variables are configured correctly.

Step 1: Install Vox

# Mac/Linux unified install
curl -fsSL https://raw.githubusercontent.com/vox-foundation/vox/main/scripts/install.sh | bash -s -- --install

# Windows (PowerShell) install
irm https://raw.githubusercontent.com/vox-foundation/vox/main/scripts/install.ps1 | iex

Step 2: Create a New Project

Use the Vox CLI to scaffold a new application:

vox init my-app
cd my-app

This scaffolds a complete project structure containing a src/main.vox entrypoint.

Step 3: Explore the Generated Code

Open src/main.vox. You'll see a starter app that includes a database table, a server endpoint, an interactive UI component, and a routing block.

@table type Note {
    title: str
    content: str
}

@server fn health() -> Result[str] {
    ret Ok("ok")
}

component App() {
    view: <div>"Hello Vox"</div>
}

routes {
    "/" to App
}

Step 4: Type Check

Run a fast static analysis and type check:

vox check src/main.vox

Step 5: Build

Compile the application to its backend Rust crate and frontend TypeScript components:

vox build src/main.vox -o dist

You'll see step-by-step progress indicating lexical analysis and code generation.

Step 6: Run

Run the generated binary directly:

vox run src/main.vox

Open http://localhost:3000 in your browser to view the application.

Key Concepts

What's Next?

• Golden Examples — Strictly verified code snippets
• Language Reference — Full syntax reference
• Building Agents — Build MCP tools and agents
• Deployment Guide — Production rollout

Journey: Building Resilient AI Agents

The Broken Reality of Orchestrating LLMs

Building an intelligent AI agent generally involves duct-taping language models to your application state. This requires writing brittle Python scripts or complex TypeScript orchestrators like Langchain.

As soon as your agent needs to execute a tool reliably, parse JSON tool-call responses, retry failures, and maintain a stateful memory of the interaction, the infrastructure complexity explodes. LLMs hallucinate arguments, drop nested fields, and break your application logic.

The Vox Paradigm: Built-In, Type-Safe Orchestration

Vox was explicitly designed as an AI-native programming language. You do not need an external orchestration library to build an agent, because Vox natively generates Model Context Protocol (MCP) tool schemas and natively coordinates stateful LLM queries.

In Vox, the chaos of generative models is bounded by the compiler's zero-null guarantees (Result and Option). You define the rigid boundaries; Vox handles the plumbing.

Core Snippet: Creating an Agent Tool

By adding a single decorator—@mcp.tool— Vox parses the docstring, the types, and the return structure, turning your server function into a ready-to-execute schema for your LLM.

// vox:skip
// This feature is partially implemented.
type SearchResult {
    Found { text: str, score: int }
    NotFound { query: str }
}

@mcp.tool "Search the knowledge base for documents matching the query"
fn search_knowledge(query: str, max_results: int) -> SearchResult {
    let hits = db.vector_search(query, max_results)
    if hits.len() == 0 {
        return NotFound { query: query }
    }
    return Found { text: hits[0].text, score: hits[0].score }
}

@server 
fn get_answer(user_question: str) -> Result[str] {
    let answer = agent.query(user_question, { tools: [search_knowledge] })
    return Ok(answer)
}

Running the Process

1. Save the above snippet into an entrypoint like src/agent.vox.

2. Compile and run:

   vox build src/agent.vox
   vox run src/agent.vox
   

3. Vox will start the development server. The endpoints become immediately queryable, and if running in MCP mode, your agent tools are automatically broadcasted for discovery.

Maturity and limitations

• Maturity: beta for decorator-shaped @mcp.tool examples — compiler and MCP registry paths evolve; treat snippets as orientation, not a guarantee every field matches shipped schemas.
• Limitation ids: L-001 (docs may oversell partial @mcp surfaces), L-023 (MCP tool registry parity is ongoing maintenance).

Deep Dives

To truly scale out this pattern, see how Vox implements AI orchestration under the hood:

• How To: Build AI Agents & MCP Tools: Explore more complex integration loops.
• MCP Exposure from the Vox Language: SSOT explaining how decorators translate to the MCP JSON-Schema specification.
• Socrates Anti-Hallucination Protocol: How Vox evaluates and rejects incorrectly formed agent outputs before they hit your execution loop.

Journey: Reliable Background Workflows

The Brittle Reality of Job Queues

When a user submits an order, your system might need to charge a credit card, reserve inventory, and send an email out. What happens when the server crashes midway between reserving the inventory and sending the email?

Microservice developers typically reach for complex infrastructure like Celery, Sidekiq, Temporal, AWS Step Functions, or Kafka. You write convoluted compensation logic, manual retry loops, and separate out small chunks of code across different services just to ensure task reliability. It fragments your business logic.

The Vox Paradigm: Native Durable Execution

Vox gives you Durable Execution out of the box using two keywords: @workflow and activity.

You write a single function that looks like linear, synchronous code. Behind the scenes, Vox records the result of each activity in a persistent journal or VoxDB. If your server is killed midway through a workflow, upon restart Vox rapidly replays the workflow state, skips the already-completed steps natively (without re-running them), and resumes execution at the exact line of code where it left off.

Core Snippet: Surviving a Server Crash

// vox:skip
// Activities are wrapped by the workflow runtime.
activity charge_payment(amount: int, token: str) -> Result[str] {
    let result = std.http.post_json("https://api.stripe.com/v1/charges", {
        amount: amount,
        source: token
    })
    return Ok(result.json().id)
}

activity send_email(user: str, message: str) -> Result[Unit] {
    std.http.post_json("https://api.sendgrid.com/v3/mail/send", {
        to: user,
        text: message
    })
    return Ok(())
}

workflow process_order(customer: str, amount: int, card_tok: str) -> Result[str] {
    // 1. Charge via retryable activity.
    let payment_id = charge_payment(amount, card_tok)
        with { retries: 3, timeout: "30s", initial_backoff: "500ms" }

    // 2. Send email
    let _ = send_email(customer, "Receipt for " + payment_id)

    return Ok(payment_id)
}

Running the Process

1. Save the snippet into your project.

2. The orchestrator runtime requires a local state store to persist workflow states. Running:

   vox run server.vox
   

   Will automatically start the journal layer mapped to your local storage.

Maturity and limitations

• Maturity: spec_plus_runtime — durable journal v1 is contract-first; operator UX and every language keyword path should be checked against the latest ADR and compiler release notes.
• Limitation ids: L-028 (completion and skeleton policy span multiple CI commands, not a single switch).

Deep Dives

To learn more about the theoretical constraints and architectural layout of Vox's durable workflows:

• Tutorial: Workflow Durability: A step-by-step walkthough of the recovery mechanism.
• Explanation: Durable Execution: Deep dive into how Vox tracks replay safety and ensures side-effect idempotency.
• Durable Workflow Journal Contract v1: The ADR dictating the storage format and constraints placed on compiled state machines.

Journey: One-File Full-Stack Data

The Duplicate Tax of Modern Web Dev

To build a simple "Todo list" or display a database record in most modern apps, you must duplicate the data structure across three distinct layers:

1. The Database: A SQL migration or Prisma schema (table tasks...).
2. The Backend ORM: The structure logic bridging the DB to logic (e.g., a Rust struct).
3. The API Layer: An Express/Axum HTTP endpoint to serialize the struct into JSON.
4. The Frontend: A TypeScript interface Task { id: string, title: string } mirroring the query output.

This causes extreme friction when a single field changes, breaking APIs and forcing developers to jump through five files for the smallest data adjustment.

The Vox Paradigm: No API Layer

Vox enables you to declare this from one single source of truth. One @table definition compiles into the correct Rust struct and the SQLite bindings. One @server function creates an Axum handler and the matching TypeScript serialization client. The @island component then directly calls the server function as if it was native to the React client.

You avoid writing boilerplate. State synchronization and type-checking happen safely across the entire vertical stack at compilation time.

Core Snippet: The Vertical Slice

Below is a complete, working React frontend and Rust backend in a single .vox file.

// vox:skip
import react.use_state

// 1. DDL & Struct defined once entirely.
@table type Task {
    title:    str
    done:     bool
    owner:    str
}

// 2. Server mutation automatically generated. Typed args enforce contract.
@server fn complete_task(id: Id[Task]) -> Result[Unit] {
    db.Task.update(id, { done: true })
    return Ok(())
}

// 3. UI logic generated as React component.
@island
fn TaskList(tasks: list[Task]) -> Element {
    let (items, _set_items) = use_state(tasks)

    <div class="task-list">
        {items.map(fn(task) {
            <label>
                <input 
                    type="checkbox" 
                    checked={task.done}
                    onChange={fn(_e) complete_task(task.id)}
                />
                {task.title}
            </label>
        })}
    </div>
}

// Server Side Routing mapped directly to the UI elements.
routes {
    "/" -> TaskList
}

Running the Process

1. Put the code in src/main.vox.

2. Initialize and run:

   vox build src/main.vox -o dist
   vox run src/main.vox
   

3. Vox will instantly compile the Task type into a Rust struct, create the SQLite table automatically via Codex, launch the Axum server, and compile the React bundle.

Maturity and limitations

• Maturity: beta — web stack and Codex bindings are active development surfaces; verify against golden examples for your compiler version.
• Limitation ids: L-021 (workspace-local vs canonical Codex stores can diverge if env paths are mis-set).

Deep Dives

To examine how the compiler handles this transparently:

• Compiler Architecture Details
• ADR 010 — TanStack as the Vox Web Spine: Why React islands generated by Vox use TanStack Query underneath to maintain reactive state without loading screens.
• Explanation: Vox Web Architecture and TypeScript Interop: SSOT explaining the compilation boundaries between Vox AST and .tsx file emission.

Journey: Native Rust LLM Training

The Curse of Python ML Environments

When you have domain-specific application data housed in a Rust or typical structured backend and want to use it to fine-tune a model, you hit a massive tooling disconnect.

You have to pull the data directly from production, dump it into JSONL files, transfer them, spin up complex Virtual Environments (venv/Conda), manage nested CUDA PyTorch dependencies, and fight Python multi-threading environments in Jupyter notebooks. Your application logic effectively divorces the ML operations layer.

The Vox Paradigm: Zero-Python Native Fine-tuning

The Vox toolchain resolves this tension by providing native hardware-accelerated QLoRA fine-tuning via MENS: vox mens train dispatches Candle + qlora-rs in vox-populi (HF weights through Rust hf-hub). vox-tensor supplies VoxTokenizer, JSONL loading, and the Burn scratch path — a different lane from HF QLoRA.

You can extract corpus pairs, assemble train.jsonl, and run training without a Python training loop. The operator surface is the CLI and corpus commands today; in-language orchestration remains a product direction.

Authoritative pipeline map (sources → compiler → goldens → corpus → Mens): Vox source → Mens pipeline SSOT. Dataset contract: Mens training data contract.

Illustrative snippet (not the shipped CLI)

The following Vox-shaped pseudocode sketches how training might be expressed in source; the supported path today is vox mens train (see mens-training.md).

// vox:skip
// Illustrative imports — operator workflow uses: vox mens train …
import vox.mens.training
import vox.mens.qlora

// We assume we have a table of high-quality agent queries and outputs.
@table type AgentTelemetry {
    query: str
    optimal_response: str
}

@action
fn finetune_from_telemetry() -> Result[str] {
    // 1. Fetch training subset directly from your database
    let records = db.query(AgentTelemetry).take(5000);
    
    // 2. Map structural DB logic into instruction dataset layout
    let dataset = records.map(fn(r) {
        { prompt: r.query, completion: r.optimal_response }
    });
    
    // 3. Initiate a hardware-accelerated QLoRA training session (Candle backend)
    let session = training.qlora_finetune(
        dataset,
        "base_models/Meta-Llama-3-8B-Instruct",
        {
            r: 16,
            lora_alpha: 32,
            target_modules: ["q_proj", "v_proj"],
            batch_size: 4,
            epochs: 3
        }
    )?
    
    return Ok("Trained adapter saved to: " + session.adapter_path)
}

Running the process (operator)

On NVIDIA hardware, build vox-cli with mens-candle-cuda (see mens-training.md and workspace build notes in AGENTS.md). Then:

vox mens corpus pairs …   # produce target/dogfood/train.jsonl (see expl-ml-pipeline)
vox mens train --device cuda --data-dir target/dogfood --output-dir mens/runs/latest

--backend qlora and --tokenizer hf are defaults: weights are fetched natively; no PyTorch training stack.

Maturity and limitations

• Maturity: stable for the vox mens train CLI path on supported presets; GPU kernels require the documented CUDA build alias (see AGENTS.md).
• Limitation ids: L-005 (default vox-cli build may omit GPU train/serve features until rebuilt with the Mens CUDA feature set).

Deep Dives

• ADR 003 — Native Rust Training Over Python: Why the project left Python/Unsloth for the pipeline, and how native Candle QLoRA superseded the “Python for QLoRA” assumption.
• ADR 006 — Mens full-graph Candle QLoRA with qlora-rs: qlora-rs integration and scope.
• Native ML Training Pipeline: Corpus → vox mens train → eval gates.
• Mens native training SSOT (Candle QLoRA): Contract, preflight, merge/serve matrix, and CLI truth table.

Tutorial: Building UI with Islands

Learn how to build modern, reactive user interfaces with Vox. This tutorial covers the @island decorator, JSX-like syntax, and binding UI state to backend logic.

[!NOTE] The @island decorator was updated in v0.3 to use standard brace syntax and return arrows (->).

1. The @island Decorator

Vox interactive UI components are defined with the @island decorator. They look and feel like React components but are compiled and hydrated for maximum performance.

// vox:skip
@island
fn Profile(name: str, bio: str) -> Element {
    <div class="p-6 bg-white shadow rounded-lg">
        <h2 class="text-xl font-bold">{name}</h2>
        <p class="text-gray-600">{bio}</p>
    </div>
}

2. Server vs. Client

You can mix lightweight server-rendered HTML routes with rich client-side islands.

// vox:skip
http get "/profile" -> Element {
    // This renders purely on the server
    <html>
        <body>
            <h1>"User Profile"</h1>
            // The island mounts on the client
            <Profile name="Alice" bio="Developer" />
        </body>
    </html>
}

3. JSX in Vox

Vox supports a JSX-like syntax directly in .vox files. You can embed variables using braces, map over collections, and conditionally render elements.

// vox:skip
@island
fn UserList(users: list[str]) -> Element {
    <ul class="divide-y">
        {users.map(fn(user) {
            <li class="py-2">{user}</li>
        })}
    </ul>
}

4. Binding to Backend Logic

The true power of Vox lies in its technical unification. You can call @mutation or @server fn functions directly from your UI event handlers. Use standard React-like onChange or onClick attributes.

component App() {
    view: <div>"Hello Vox"</div>
}

5. Routing

You map a route to your island or server handler through the global routes { } block.

// vox:skip
routes {
    "/" -> NewsletterForm
}

Next Steps:

• Language Syntax — Detailed JSX specification.
• First App — Apply these UI patterns to a collaborative task list.

Tutorial: Building a Collaborative Task List

Learn how to build a full-stack, collaborative task list app with Vox. This tutorial covers data modeling, server-side logic, and UI integration using a single .vox file.

1. Project Initialization

Create a new directory and initialize a Vox application:

mkdir vox-task-list
cd vox-task-list
vox init --kind application

2. Define the Data Model

Open src/main.vox. We'll start by defining what a "Task" is. Using the @table decorator, we create a persistent database table.

@table type Note {
    title: str
    content: str
}

3. Implement Server Logic

Next, we add @mutation and @query functions to interact with the database.

@query fn get_notes() -> List[Note] {
    ret db.Note.all()
}

@mutation fn create_note(title: str, content: str) -> Result[Id[Note]] {
    let id = db.Note.insert({ title: title, content: content })?
    ret Ok(id)
}

workflow order(id: str) -> Result[Unit] {
    let status = check_inventory(id)
    ret Ok(Unit)
}

4. Build the UI

Now, we'll create the frontend using the @island decorator. Vox islands use a JSX-like syntax that compiles to high-performance hydrated React components.

component App() {
    view: <div>"Hello Vox"</div>
}

5. Wiring It Together

Finally, we map a route to our TaskList component.

// vox:skip
routes {
    "/" -> TaskList
}

6. Build and Run

Compile your app and start the development server:

vox check src/main.vox
vox build src/main.vox
vox run src/main.vox

Visit http://localhost:3000 to see your collaborative task list in action!

Next Steps:

• Actor Basics — Add real-time collaboration with shared state.
• Durable Workflows — Automate task reminders.

Tutorial: Persistent Actors & State

In Vox, Actors are the primary unit of stateful concurrency. Unlike standard functions, an actor has identity and private state. This tutorial walks through building a persistent counter that survives a system crash.

1. Defining the Actor

An actor is defined with the actor keyword. Its internal state is private and only accessible via message handlers.

actor Counter {
    on increment(current: int) -> int {
        let count = current + 1
        print("Count is " + count)
        ret count
    }
}

2. Spawning and Identity

To use an actor, you must spawn it. This returns an ActorRef, which acts as a capability to send messages.

To use an actor, you must spawn it. This returns an ActorRef, which acts as a capability to send messages.

// vox:skip
@server fn demo_actors() -> int {
    // Spawn a new instance
    let ref = spawn GlobalCounter()
    
    // Send an asynchronous message
    ref.send increment(5)
    
    // Await a response from a handler
    let val = await ref.get()
    
    return val
}

3. The Lifecycle: Persistence in Action

Vox actors are not just in-memory. By using state_load and state_save, you tie the actor's life to the durable runtime.

1. Spawn: The actor is created in the runtime's mailbox registry.
2. Handle: A message arrives, state_load pulls the latest value from the local SQLite/Codex store.
3. Save: state_save ensures that even if you kill -9 the process, the value is safe.
4. Restart: When the process resumes and the actor is re-spawned or addressed by its stable ID, it picks up exactly where it left off.

4. Patterns: Actor Communication

Actors can talk to each other. Because each actor has its own mailbox, they process messages sequentially but run in parallel with other actors.

// vox:skip
actor Logger {
    on log(msg: str) {
        print("[LOG]: " + msg)
    }
}

actor Worker {
    let logger = spawn Logger()

    on do_work() {
        // Delegate logging to another actor
        logger.send log("Starting work...")
    }
}

5. Behind the Scenes: How Actors Compile

When you run vox build, the compiler lowers actor constructs directly into high-performance Rust primitives:

6. Summary Checklist

• Isolation: State is never shared; only messages pass between actors.
• Persistence: Use state_load/state_save for durable state.
• Concurrency: Use spawn to create independent units of work.
• Non-blocking: Use send for asynchronous notification.
• Request-Response: Use await ref.handler() for synchronous calls.

Next Steps:

• Workflow Durability — Orchestrate complex, multi-step long-running processes.
• Actors & Workflows Explanation — Deep dive into the theory.
• CLI Reference: vox run — Run your actor-based applications.

Tutorial: Workflow Durability

Learn how to build resilient, long-running processes using Vox workflows. This tutorial explains the durability story Vox supports today: interpreted workflow step replay, stable activity ids, and idempotent activities.

[!WARNING] Interpreted workflow runtime durability and generated-Rust workflow durability are different things. The durable replay and recovery story shown here uses the interpreted path (vox mens workflow ...), not compiled native async functions.

1. The Challenge of Long-Running Tasks

Traditional async functions lose their state if the server restarts or a network error occurs. Vox workflows are intended to solve that by recording progress in a database.

2. Defining a Workflow

Use the bare activity and workflow keywords to describe long-running orchestration.

Use the bare activity and workflow keywords to describe long-running orchestration.

@query fn get_notes() -> List[Note] {
    ret db.Note.all()
}

@mutation fn create_note(title: str, content: str) -> Result[Id[Note]] {
    let id = db.Note.insert({ title: title, content: content })?
    ret Ok(id)
}

workflow order(id: str) -> Result[Unit] {
    let status = check_inventory(id)
    ret Ok(Unit)
}

The with block provides execution options for the activity:

• retries: Number of attempts before failing the workflow step
• timeout: Maximum duration allowed for a single execution
• initial_backoff: Delay before the first retry attempt

3. How It Works

1. Step tracking: The interpreted runtime records activity progress in Codex workflow tracking tables.
2. Recovery: If the workflow is restarted with the same run identity, the runtime skips steps that completed successfully by reading their result from the journal.
3. Idempotency: Activities should still be safe to retry on timeout or failure. Durable step replay is not the same thing as a universal exactly-once guarantee.

4. Workflows vs. Tasks

5. Best Practices

• Idempotency: Activities should be idempotent since they might be retried after a failure.
• Deterministic: Workflow logic must be deterministic. Avoid using rand() directly inside the workflow body; use an activity instead.
• Stable step ids: Use explicit activity_id values for steps you expect to resume safely across restarts. with { id: "..." } sets this.

Next Steps:

• Language Syntax — Explore advanced workflow expressions.
• First App — Integrate a workflow into your task list.

First .vox app — checkpoints

Use this alongside First full-stack app and golden examples.

Checkpoint A — parse

• Create app.vox with a top-level fn or use examples/golden/hello.vox.
• vox check app.vox exits 0 (or fix parse diagnostics).

Checkpoint B — typecheck + HIR

• vox check app.vox shows no type errors.
• Optional JSON: vox check app.vox --json and confirm diagnostics carry category when emitted from the shared pipeline.

Checkpoint C — build / run (when applicable)

• vox build app.vox or your project’s documented build entry.
• vox run … for script mode only when built with script-execution (see CLI reference).

Checkpoint D — mens (optional)

• With populi feature: vox populi serve local smoke; see Populi SSOT.

When stuck, capture full diagnostic output and cross-check parser inventory and the CLI reference.

@py.import – Python Library Integration (torch, numpy, etc.)

2026 stance: vox container init is retired (hard error — use Rust/PM flows). @py.import / uv-backed setup is not a supported product path. Native ML stacks live under vox mens / Candle; treat the material below as historical reference only. For integration with external libraries via FFI going forward, see Rust FFI & Migration Guide.

Vox historically documented importing Python libraries from .vox via @py.import with uv for wheels. That workflow is not maintained as a supported package-management lane.

Quick Start

// vox:skip
@py.import torch
@py.import torch.nn as nn

fn run_inference(input: list[float]) -> list[float] {
    let t = torch.tensor(input)
    let model = nn.Linear(4, 1)
    return model.forward(t).tolist()
}

Legacy documentation previously recommended:

vox container init --file src/main.vox

That command now fails with a migration message — do not rely on it for new work.

Syntax

@py.import <module>                   # binds to last segment (torch → torch)
@py.import <module> as <alias>        # custom binding (torch.nn → nn)

Both dotted module paths (torch.nn.functional) and simple names (torch) are supported.

How It Worked (historical)

The retired vox container init flow used uv as follows:

1. Detects your environment (uv, Python version, GPU/CUDA).
2. Runs uv python install 3.12 — idempotent, skips if already installed.
3. Generates a pyproject.toml with the correct PyTorch wheel source (CPU or CUDA).
4. Runs uv sync — creates .venv in your project directory.

At runtime, the vox-py bridge auto-detects the .venv and injects its site-packages into Python's sys.path. No PYTHONPATH or shell activation is needed.

venv discovery order

The runtime looks for the venv in this order:

Type conversions

Inputs are automatically converted from Vox types to Python types:

Return values come back as their string representation. Use helper utilities like PY_RT.tensor_to_vec_f64() to convert tensors to Vox-native lists, or PY_RT.to_json() for structured results.

PyTorch Example

// vox:skip
@py.import torch
@py.import torch.nn as nn
@py.import torch.nn.functional as F

fn mlp_forward(x: list[float]) -> list[float] {
    let t       = torch.tensor(x)
    let linear1 = nn.Linear(4, 8)
    let linear2 = nn.Linear(8, 2)
    let h       = F.relu(linear1.forward(t))
    let out     = linear2.forward(h)
    return out.tolist()
}

fn main() {
    let result = mlp_forward([1.0, 2.0, 3.0, 4.0])
    println(result)
}

NumPy Example

// vox:skip
@py.import numpy as np

fn moving_average(data: list[float], window: int) -> list[float] {
    let arr = np.array(data)
    let weights = np.ones(window) / window
    return np.convolve(arr, weights, "valid").tolist()
}

Runtime Environment (historical)

vox container init is retired (hard error). It no longer provisions Python, uv, or a project venv. The snippet below is only for readers maintaining trees that still have a pre-existing .venv from before that cutover:

# Retired — fails today with an explicit migration message.
vox container init --file src/main.vox

# Historical follow-up only: rebuild a binary against an already-materialized venv layout.
cargo build && ./target/debug/my-app

Docker / CI (historical)

The vox container init + uv sync lane is retired. The snippets below are retained only for readers maintaining old trees.

When the venv lives at a non-standard path (e.g. inside a Docker image), set VOX_VENV_PATH to override auto-detection:

# Historical — prefer the repo-root Rust `Dockerfile` for new work.
FROM python:3.12-slim
RUN pip install uv

WORKDIR /app
COPY . .
RUN uv sync

# VOX_VENV_PATH tells the compiled binary exactly where packages live
ENV VOX_VENV_PATH=/app/.venv
CMD ["./target/release/my-app"]

Or in a CI step:

# Historical uv-based CI — not a supported Vox PM path.
- run: |
    uv sync
    cargo build --release
    VOX_VENV_PATH=$(pwd)/.venv ./target/release/my-app

[!TIP] For GPU workloads on the historical @py.import + CUDA wheel path, you needed an NVIDIA GPU so auto-detection could pick PyTorch wheels. New work: prefer vox mens / Candle — see Mens training.

[!NOTE] The vox-py Cargo feature is disabled by default to keep compile times short. Enable it by adding vox-py as a dependency to your project's Cargo.toml.

[!IMPORTANT] Do not set PYTHONPATH manually. The vox-py runtime discovers the uv-managed .venv automatically. Setting PYTHONPATH to a different environment will override this detection and may cause import errors.

CUDA Configuration

Vox auto-selects the right PyTorch wheel source based on your detected GPU:

Available Bridge Methods

See Also

• @py.import decorator reference
• Candle inference serving
• NumPy integration patterns

The Future: Native Vox ML (vox-tensor)

While Python integration historically provided utility for @py.import experiments, it inherently conflicts with deeply-held Vox principles: Zero dependency drift, One Binary deployment, and Complete cross-platform compilation.

To address this, we have implemented vox-tensor — a native ML layer built on the Burn framework, providing 95% of PyTorch's capabilities without Python.

Current API (implemented)

#![allow(unused)]
fn main() {
// Tensor creation
Tensor::zeros_1d(len)               // 1D zero tensor
Tensor::zeros_2d(rows, cols)        // 2D zero tensor
Tensor::ones_1d(len)                // 1D ones tensor
Tensor::ones_2d(rows, cols)         // 2D ones tensor
Tensor::from_vec_1d(data)           // 1D from Vec<f32>
Tensor::from_vec_2d(data, rows, cols) // 2D from Vec<f32>
Tensor::randn_1d(len)               // 1D random normal
Tensor::randn_2d(rows, cols)        // 2D random normal

// Operations
tensor.add(&other)           // element-wise add
tensor.sub(&other)           // element-wise subtract
tensor.mul(&other)           // element-wise multiply
tensor.mul_scalar(f64)       // scalar multiply
tensor.add_scalar(f64)       // scalar add
tensor.matmul(&other)        // matrix multiply (2D only)
tensor.transpose()           // transpose (2D only)
tensor.relu()                // ReLU activation
tensor.sigmoid()             // sigmoid activation
tensor.sum()                 // sum all elements
tensor.mean()                // mean all elements
tensor.to_vec()              // extract to Vec<f32>
tensor.shape()               // TensorShape
tensor.numel()               // total element count
}

Neural Network Layers

#![allow(unused)]
fn main() {
// Layers
nn::Module::linear(in, out, bias)   // Dense layer
nn::Module::dropout(prob)           // Dropout
nn::Module::batch_norm1d(features)  // BatchNorm1d
nn::Module::conv2d(in_ch, out_ch, kernel) // Conv2d

// Composition
nn::Sequential::new(vec![
    Module::linear(4, 8, true),
    Module::linear(8, 2, true),
])
.forward(input_tensor)
}

Example: MLP inference without Python

// vox:skip
import tensor as t
import nn

fn infer_mlp() -> list[float] {
    let model = nn.Sequential([
        nn.Module::linear(4, 8, true),
        nn.Module::linear(8, 2, true),
    ])

    let input = t.Tensor::from_vec_2d([1.0, 2.0, 3.0, 4.0], 1, 4)
    let out = model.forward(input)
    return out.to_vec()
}

This ensures Low K-Complexity (no shell dependencies), native type-checked operations, and deployment via the built-in HTTP server — all in a single, self-contained binary.

[!NOTE] vox-tensor uses NdArray (CPU) as the default backend with Autodiff for gradient tracking. GPU acceleration (WGPU) is available via the wgpu feature flag in vox-tensor/Cargo.toml.

Contributing — Mens training (native)

Read first

• Mens native training SSOT
• HF finetune capability matrix

Entrypoints

Commands

cargo check -p vox-populi --features mens-train
cargo test -p vox-populi --features mens-train execution_planner

SSOT rule

Candle QLoRA is the active vox mens train backend; keep docs and error messages aligned (lora_train.rs is authoritative when in doubt).

Contributing — Populi / mens HTTP

Read first

• Mens / Populi SSOT
• OpenAPI
• Deployment compose

Key paths

Commands

cargo test -p vox-populi --features transport --test http_control_plane
cargo test -p vox-populi --features transport openapi_paths

Security defaults

• GET /health stays unauthenticated even when VOX_MESH_TOKEN is set.
• Never log bearer tokens or bootstrap secrets.
• Prefer machine-readable probes (vox doctor --probe) in OCI HEALTHCHECK.

Contributing — parser and HIR

Read first

• Architecture — pipeline
• Parser ambiguity inventory
• HIR legacy inventory
• Diagnostic taxonomy

Key crates

Commands

cargo test -p vox-compiler
cargo test -p vox-compiler --test parser_recovery

Definition of done

• Parser / HIR changes include tests (unit or tests/*.rs).
• New declaration kinds either get a dedicated Hir* vector or land in legacy_ast_nodes only with an inventory update and a graduation plan.

Ecosystem & Tooling

Note: This page describes the intended developer experience. The crates/vox-cli binary implements a subset of commands today (build, check, test, run, bundle; fmt / install fail until wired; lsp). Authoritative current flags: ref-cli.md.

Vox ships with a complete development toolchain: compiler, bundler, test runner, formatter, package manager, and language server — converging on the vox CLI as the primary entry point.

CLI Commands

vox build

Compile a .vox file to Rust and TypeScript:

# Basic build
vox build app.vox -o dist

Watch mode and other flags may land later; use vox build --help and ref-cli.md for what the binary exposes now.

Typical output layout (minimal CLI) — filenames vary by program; Rust lands under target/generated/:

dist/
├── backend/      # Generated Rust (Axum server)
│   ├── src/
│   │   └── main.rs
│   └── Cargo.toml
└── frontend/     # Generated TypeScript (React)
    ├── src/
    │   └── App.tsx
    └── package.json

vox bundle

Ship a single statically-linked binary containing frontend + backend + SQLite:

# Release build targeting Linux
vox bundle app.vox --release --target x86_64-unknown-linux-musl

# Debug build (default)
vox bundle app.vox

vox test

Run @test decorated functions:

vox test tests.vox

This compiles the test functions to Rust #[test] blocks and runs them with cargo test.

vox fmt

Minimal binary today: vox fmt exits with an error until vox-fmt matches the current AST. Formatting work lives in the vox-fmt crate.

vox fmt app.vox

See ref-cli.md.

vox lsp

Launch the Language Server Protocol server:

vox lsp

See Language Server below for details.

Package management (vox add / vox sync / vox pm)

vox install is removed (no CLI subcommand). Use vox add, vox lock, vox sync, and vox pm per reference/cli.md; see the full mapping in pm-migration-2026.md.

vox vendor

Offline trees: use vox pm vendor. Populate .vox_modules/dl/ with vox sync first.

Language Server (LSP)

The vox-lsp crate provides IDE support via the Language Server Protocol.

Current Features

Setup

1. Build the LSP server:

   cargo build --release -p vox-lsp
   

2. Configure your editor:

   VS Code (with the vox-vscode extension or manual configuration):

   "vox.lsp.serverPath": "/path/to/target/release/vox-lsp"
   

The LSP server integrates the full compiler pipeline — when you save a file, it re-runs the lexer, parser, and type checker to provide real-time diagnostics.

Package Manager (vox-pm)

The Vox package manager uses a Content-Addressable Store (CAS) backed by libSQL/Turso.

How It Works

store(data) → SHA3-256 hash
get(hash)   → data

All artifacts are stored by their content hash:

• Deterministic — same content always produces the same hash
• Deduplication — identical artifacts share a single stored copy
• Integrity — content can be verified against its hash at any time

Database Backends

Semantic Code Search

The package manager includes a de Bruijn indexing normalizer that strips identifier names from AST nodes and replaces bound variables with positional indices. This enables detection of semantically identical code regardless of naming differences.

bind_name(namespace, name, hash)    # Map a name to content
lookup_name(namespace, name) → hash # Resolve a name to content
search_code_snippets(query, limit)  # Vector-similarity search

Agent Memory

The store also manages agent memory for AI-powered features:

recall_async(agent, type, limit, min_importance)  # Query with relevance filtering

Installation

Automated (recommended)

# Linux / macOS
./scripts/install.sh          # End-user install
./scripts/install.sh --dev    # Full contributor setup
./scripts/install.sh plan     # JSON install plan (CI/tooling)

# Windows (PowerShell)
.\scripts\install.ps1         # End-user install
.\scripts\install.ps1 -Dev    # Full contributor setup
.\scripts\install.ps1 plan    # JSON install plan (CI/tooling)

Manual

Prerequisites: Rust >= 1.75, Node.js >= 18, C compiler (gcc/clang/MSVC). Full workspace + Turso crates: clang on Linux/macOS; clang-cl (LLVM) on Windows — see docs/src/how-to-setup.md.

cargo install --locked --path crates/vox-cli

Note: Node.js and npm are required at runtime for vox bundle and vox run (frontend scaffolding). Copy .env.example to .env to configure optional API keys.

Development

Building

cargo build --workspace

Testing

cargo test --workspace

Linting

cargo fmt --all -- --check    # Format check
cargo clippy --workspace      # Lint check

Next Steps

• Language Guide — Full syntax and feature reference
• Compiler Architecture — Pipeline internals
• Actors & Workflows — Concurrency and durable execution
• Examples — Annotated example programs

Examples

First Full Stack App

Golden Examples Corpus

The Vox documentation utilizes a "Golden Example" architecture to prevent documentation drift and ensure that all documented code actually compiles against the latest compiler version.

How goldens and docs feed Mens training (lexer vs HF tokenizer, corpus roots): Vox source → Mens pipeline SSOT. Pair layout and hygiene: Mens training data contract.

How Golden Examples Work

Instead of writing raw code blocks directly inside Markdown files, documentation should pull snippets from the examples/golden/ directory.

CI enforces goldens in two layers: (1) vox-compiler integration test all_golden_vox_examples_parse_and_lower — every examples/golden/**/*.vox must parse, lower to HIR, pass WebIR validation, and emit Syntax-K metrics; (2) mdBook / doc pipeline — pages that use {{#include}} must resolve to real golden .vox files (examples_ssot test). A full vox build per golden may run in additional doc or integration jobs; do not assume “build-only” is the only gate.

Adding a Golden Example

To document a feature with machine verification:

1. Create the file: Create a valid .vox file in examples/golden/.
2. Write the code: Add the required logic to the file. Ensure the file works when compiled.
3. Define regions: If your file is large but you only want to document a specific function, wrap the target logic in [REGION:name] anchors.
4. Include it: In your Markdown document, use the standard mdbook include syntax:

{{#include ../../../examples/golden/my_example.vox:my_region}}

The // vox:skip Directive

Sometimes it is necessary to show brief, inline examples that cannot be fully compiled (e.g., demonstrating a syntax error, or showing an incomplete code snippet for brevity).

In these cases, you must add a // vox:skip comment inside the code fence. The vox-doc-pipeline linter will scan for this directive; if it finds raw code fences without // vox:skip and without an #include directive, the build will fail.

// vox:skip
fn incomplete_function() {
    // This inline code will not be strictly verified by the compiler.
}

By ensuring every code fence is either an immutable golden reference or explicitly marked as skipped, Vox guarantees absolute trust in its documentation.

How To: Train Mens on RTX 4080 Super

Canonical contracts, backends, and regression commands: Mens native training SSOT. This page is a step-by-step runbook for RTX 4080 Super; do not duplicate SSOT tables here.

This runbook covers two native paths:

1. Production Qwen 3.5 (recommended for Qwen3.5-4B-Instruct) — Candle QLoRA (--backend qlora, NF4 frozen bases via qlora-rs). Build with mens-candle-cuda on Windows/Linux when you have an NVIDIA GPU and CUDA toolkit available for candle-core.
2. Burn LoRA (GPT-2-shaped HF or Vox tokenizer) — default vox mens train without --backend qlora; uses wgpu (Vulkan/DX12) on Windows.

Recommended Path (Qwen3.5-4B, RTX 4080-class 16GB)

• Build (CUDA): from repo root, cargo vox-cuda-release (alias in .cargo/config.toml — same as cargo build -p vox-cli --release --features gpu,mens-candle-cuda).

  [!WARNING] On Windows, you MUST use an interactive VS Developer Command Prompt or PowerShell shell explicitly bootstrapped with vcvars64.bat. Passing vcvars64.bat via nested subshells (e.g. cmd.exe /c "vcvars64.bat && cargo...") aggressively drops the PATH configurations preventing nvcc from correctly executing cl.exe.

• Data: target/dogfood/train.jsonl (from corpus pairs/mix); optional record_format: tool_trace in mix for command/tool supervision rows (category tool_trace). See mens/schemas/tool_trace_record.schema.json and mens/data/tool_traces.example.jsonl.
• Train:

  .\target\release\vox.exe mens train `
    --backend qlora --tokenizer hf `
    --preset qwen_4080_16g `
    --model Qwen/Qwen3.5-4B `
    --data-dir target/dogfood `
    --output-dir mens/runs/qwen35_qlora `
    --device cuda `
    --qlora-require-full-proxy-stack
  

  --qlora-require-full-proxy-stack is recommended for strict shard completeness on native qwen3_5 runs. LM-head-only mode is currently deferred/not implemented in the native trainer.
• Artifacts: candle_qlora_adapter.safetensors, candle_qlora_adapter_meta.json, populi_adapter_manifest_v3.json, training_manifest.json, telemetry.jsonl.

Go-live checklist (local CUDA dogfood)

1. Shell: VS Developer / MSVC environment so cargo vox-cuda-release (or cargo check -p vox-cli --features gpu,mens-candle-cuda) succeeds.
2. CLI: vox mens train --help lists --qlora-* flags including --qlora-ce-last-k.
3. Corpus: refresh train.jsonl or set VOX_TRAIN_SKIP_CORPUS_MIX=1 when the mix step is unnecessary.
4. Run: canonical QLoRA command from above with --log-dir mens/runs/logs (or your path); tail the log.
5. Acceptance: first log lines show finite loss; optional --qlora-ce-last-k 4 for a stronger suffix LM signal (see SSOT).
6. Thin wrapper (optional): scripts/populi/dogfood_qlora_cuda.ps1.

• Merge (Candle): in-tree vox mens merge-qlora (alias merge-adapter) or vox schola merge-qlora — same merge surface; produces f32 safetensors subsets — not Burn *.bin. See the SSOT train → merge → serve table in mens-training.md. vox mens serve (Burn) loads LoRA or merged Burn checkpoints; it does not load Candle merge-qlora safetensors. For querying merged QLoRA weights, use an external stack (e.g. export to HF/Ollama) or keep the adapter path your inference tool supports.

Burn LoRA path (non-Qwen or GPT-2-shaped HF)

• Default: vox mens train --data-dir target/dogfood --output-dir mens/runs/v1
• Input contract: target/dogfood/train.jsonl
• Backend: wgpu on Windows (Vulkan or DX12); no CUDA required for Burn

Prerequisites

1. Build Vox CLI (release binary):

   & "$env:USERPROFILE\.cargo\bin\cargo.exe" build -p vox-cli --release
   

2. Generate canonical corpus input:

   New-Item -ItemType Directory -Force -Path mens/data,target/dogfood | Out-Null
   .\target\release\vox.exe mens corpus extract examples/ -o mens/data/validated.jsonl
   .\target\release\vox.exe mens corpus extract docs/ -o mens/data/validated.jsonl 2>$null
   .\target\release\vox.exe mens corpus validate mens/data/validated.jsonl --no-recheck -o mens/data/validated.jsonl
   .\target\release\vox.exe mens corpus pairs mens/data/validated.jsonl -o target/dogfood/train.jsonl --docs docs/src/ --docs docs/src/research/ --docs docs/src/adr/
   # Rustdoc merge skipped: response is Rust prose, not Vox code
   

3. Optional Burn GPU backend selection (passed to vox mens train --device; best is default):

   # Prefer flags on the train command, not legacy env, for `vox mens train`:
   # --device best | vulkan | dx12 | cpu
   

4. Optional training profile (RTX 4080 Super 16GB VRAM):

   $env:VOX_TRAIN_PROFILE = "safe"   # Conservative: batch 2, seq 256 (shared GPU, avoids OOM)
   # $env:VOX_TRAIN_PROFILE = "balanced"  # Default for 16GB: batch 4, seq 512, rank 16
   # $env:VOX_TRAIN_PROFILE = "throughput" # Aggressive: batch 6 (may OOM if OS uses GPU)
   

   Device probe auto-detects 16GB and recommends batch 4, seq 512, rank 16. Use vox mens probe to verify.

Full mixed corpus → entire LoRA run (4080 preset)

Use this when you want all sources from mens/config/mix.yaml (not a tiny dogfood slice).

1. Build release CLI with --features gpu (default is mens-base only; native train / QLoRA need the GPU feature stack). Add --features mens-dei only if you need legacy vox train (Together / --native Burn scratch; --provider local bails to vox mens train) or Mens DeI surfaces (generate, review, …):

   & "$env:USERPROFILE\.cargo\bin\cargo.exe" build -p vox-cli --release --features gpu
   

   If this fails, fix vox-cli compile errors before training.

2. Mix into the default mix output path (strict: all non-optional sources must exist and contribute rows):

   .\target\release\vox.exe mens corpus mix --config mens/config/mix.yaml
   

   Writes target/dogfood/train_mixed.jsonl per mix config plus target/dogfood/train_mixed.mix_report.json. If your tree is missing generated files, use --allow-missing-sources once (same as legacy warn-only mix) or run the corpus pipeline stages first.

3. Point training at that file as train.jsonl (preflight requires this exact name inside --data-dir):

   New-Item -ItemType Directory -Force -Path target/dogfood | Out-Null
   Copy-Item -Force target/dogfood/train_mixed.jsonl target/dogfood/train.jsonl
   

4. Train (Qwen + Candle QLoRA) with the qwen_4080_16g preset (16GB-oriented; see SSOT mens-training.md):

   .\target\release\vox.exe mens train `
     --backend qlora --tokenizer hf `
     --preset qwen_4080_16g `
    --model Qwen/Qwen3.5-4B `
     --data-dir target/dogfood `
     --output-dir mens/runs/rtx4080_full `
     --device cuda `
     --background
   

   --background alone attaches logs under mens/runs/logs (repo root when detected) and returns immediately; equivalent to --log-dir mens/runs/logs. On Windows the child process is spawned with breakaway-from-job flags to reduce IDE teardown killing the trainer. Tail: Get-Content mens/runs/logs/train_*.log -Wait -Tail 25. Alternatives: vox mens train … --background, or pwsh scripts/populi/release_training_gate.ps1 only for CI gates (not full training).

   On OOM, use --preset safe / 4080_safe, lower --seq-len, raise --grad-accum, lower --rank, or set VOX_CANDLE_DEVICE=cpu (slow).

First Training Run (Native)

.\target\release\vox.exe mens train --data-dir target/dogfood --output-dir mens/runs/v1

Or run the end-to-end automation script:

.\scripts\run_mens_pipeline.ps1 -DataDir target/dogfood -OutputDir mens/runs/v1 -Backend vulkan

Expected outputs:

• mens/runs/v1/model_final.bin
• mens/runs/v1/checkpoint_epoch_*.bin
• mens/runs/v1/eval_results.json
• mens/runs/v1/benchmark_results.json (if benchmark gate enabled)

Quality Gates

• Eval thresholds:
  • VOX_EVAL_MIN_PARSE_RATE (default 0.80)
  • VOX_EVAL_MIN_COVERAGE (default 0.60)
• Strict enforcement:
  • VOX_EVAL_STRICT=1 to fail run on threshold miss
• Optional held-out benchmark (build with --features mens-dei; paths via env):
  • VOX_BENCHMARK=1 — after training, spawns vox mens eval-local
  • VOX_BENCHMARK_MODEL — checkpoint path (else auto-detect under output dir)
  • VOX_BENCHMARK_DIR — held-out bench directory (default mens/data/heldout_bench)

.\target\release\vox.exe mens corpus eval target/dogfood/train.jsonl -o mens/runs/v1/eval_results.json

Runtime Profiles

• Fast dogfood:
  • 1 epoch, smaller dataset while iterating on pipeline code/docs
• Full run:
  • Full corpus + rustdoc merge and benchmark gate enabled

Model Card

After training, the model card is rendered from mens/model_card/:

uv run --project scripts render-model-card --run-dir mens/runs/v1

Dogfood operator checklist (real corpus, 4080 QLoRA)

Use this before claiming a full dogfood run is complete (CI cannot substitute for your GPU box).

Cursor / agents: full vox ci mens-gate can exceed tool timeouts — use pwsh scripts/populi/release_training_gate.ps1 -Detach and tail target/mens-gate-logs/ (see mens-training.md).

1. Corpus: mens corpus mix --config mens/config/mix.yaml → copy/rename to target/dogfood/train.jsonl (preflight requires that filename in --data-dir).
2. Build: cargo vox-cuda-release natively from a vcvars64.bat loaded interactive terminal (nvcc relies on absolute discovery and crashes in subshells).
3. Train: vox mens train --backend qlora --tokenizer hf --preset qwen_4080_16g (or --preset 4080, same profile) + --model, --data-dir, --output-dir, --device cuda; keep --qlora-require-full-proxy-stack on for strict native shard completeness.
4. Artifacts: Confirm candle_qlora_adapter.safetensors, candle_qlora_adapter_meta.json, populi_adapter_manifest_v3.json, training_manifest.json, telemetry.jsonl under the output dir.
5. Merge / serve: Candle merge is vox schola merge-qlora (f32 shard subsets); vox mens serve stays Burn-only — see SSOT Merge / export.
6. Optional automation: scripts/populi/dogfood_qlora_cuda.ps1 builds (CUDA by default) and launches the canonical CLI in the background; see scripts/README.md.

See Also

• Native ML Training Pipeline
• How To: Publish Mens to Hugging Face
• scripts/README.md — thin delegates + optional RTX 4080 QLoRA helper script

Canonical VoxDB / Codex store

What is canonical?

Authoritative relational data (Codex, publication, research, default training telemetry) lives in the user-global database resolved by:

• DbConfig::resolve_canonical (same as resolve_standalone), then
• VoxDb::connect.

Typical local path: <VOX_DATA_DIR or platform default>/vox/vox.db via default_db_path. Override with VOX_DB_PATH or use VOX_DB_URL + VOX_DB_TOKEN for remote Turso.

What is not canonical?

migrating off a legacy chain

If vox codex verify or normal connect reports a non-baseline schema:

1. vox codex export-legacy backup.jsonl
2. Point VOX_DB_PATH at a new file (or delete the old file after backup).
3. vox codex verify (applies current baseline).
4. vox codex import-legacy backup.jsonl

Details: codex-legacy-migration.

Historical vox_training_telemetry.db

Mens training uses VoxDb::connect_default on the canonical store. If vox.db is still on a legacy schema_version chain, connect fails with LegacySchemaChain until you complete export / fresh baseline / import (see codex-legacy-migration). A leftover vox_training_telemetry.db from older releases can be archived after primary cutover.

Deprecation stance

• Canonical: one maintained BASELINE_VERSION in manifest.rs.
• Legacy: multi-version schema_version chains — export/import only, not incremental SQL bridges.

Related

• Codex / Arca compatibility boundaries
• Forward migration charter
• Mens training

How-To: Build AI Agents and MCP Tools

Vox is an AI-native language, meaning it bridges the gap between high-level business logic and the Model Context Protocol (MCP) without glue code. Any Vox function can become an MCP tool with a single decorator.

1. Creating MCP Tools

Any Vox function can be exported as an MCP tool using the @mcp.tool decorator.

@mcp.tool "Calculate the sum of two integers"
fn sum(a: int, b: int) -> int {
    return a + b
}

Comparison to other approaches:

• Type Safety: If your function returns a Result[T, E], Vox handles the MCP error response mapping for you.
• Zero Configuration: No and manifests to maintain. The @mcp.tool decorator is the manifest.
• Auto-Discovery: Tools are automatically discovered by the vox-orchestrator during development.

2. Defining Agent Roles

Agents in Vox are not just prompts; they are scoped types that bundle specific tools and instructions. Use the @agent decorator to define an agent's identity.

[!NOTE] The agent declaration is now a first-class HIR element in Vox v0.3, enabling static validation of toolsets and instructions.

agent Assistant {
    version "1.0.0"

    on greet(name: str) -> str {
        return "Hello " + name + ", how can I assist you today?"
    }

    migrate from "0.9.0" {
        print("Migrating data...")
    }
}

Agent Handoffs

Agents can call other agents if you grant them the tool to do so. In Vox, an agent's tools list can include other agent identifiers.

3. Tool Discovery and Execution

To expose your tools to a local AI assistant (like Claude Desktop or Cursor):

1. Run the MCP server:

   vox run src/main.vox
   

2. Observe Logs: The orchestrator will list all registered tools and resources.
3. Connect: Add the generated endpoint to your claude_desktop_config.json.

4. Testing Your Tools

Never guess if a tool works. You can test your tool directly against the generated server. (Note: A dedicated vox test-mcp CLI is an aspirational future feature).

# Test the 'search_docs' endpoint manually using standard tools
curl -X POST http://localhost:8080/api/tools/search_docs -d '{"query": "actors"}'

5. Security and Bounds

By default, an @mcp.tool has the same permissions as your compiled Vox binary. Use the @require decorator to add runtime guardrails:

// vox:skip
@mcp.tool "Delete user data"
@require(auth.is_admin(caller))
@mutation fn delete_data(id: int) -> Result[Unit] {
    db.delete(id)
    return Ok(())
}

If the precondition fails, the MCP tool returns a "Tool execution failed" error to the model with the specific violation reason, preventing the LLM from attempting unauthorized actions.

Related Reference:

• MCP Protocol SSOT
• Agentic Loop Blueprint
• CLI Reference: vox mcp

How-To: Deploy to Production

Learn how to package and deploy your Vox application using declarative environments and the vox deploy command.

You can define your deployment environment directly in your .vox files using environment blocks. This allows you to specify a base image, system packages, environment variables, exposed ports, and more.

environment staging {
    base "node:22-alpine"
    packages ["curl"]
    env STAGE = "staging"
    expose [8080]
}

[!NOTE] The npx tsx server.ts command is a legacy / opt-in Node lane. TypeScript codegen emits server.ts only when VOX_EMIT_EXPRESS_SERVER=1 is set at build time; the default product path is the generated Axum binary plus api.ts for @server fn. See vox-fullstack-artifacts.md.

Bare Metal (systemd) Provider

For applications that run directly on Linux servers without Docker, set base to "bare-metal" and Vox will generate a systemd .service file instead of a Dockerfile:

// vox:skip
environment server {
    base "bare-metal"
    workdir "/opt/my-app"
    env PORT = "8080"
    cmd ["./my-app", "--port", "8080"]
}

Running vox build will emit a server.service file ready for deployment with systemctl enable and systemctl start.

Vox will automatically use these blocks to generate customized OCI-compatible Dockerfiles or systemd service files.

1. Registry Authentication

Before pushing images to a private registry, authenticate with vox login:

# Log in to the default VoxPM registry
vox login <your-api-token>

# Log in to a private OCI registry (e.g. GitHub Container Registry)
vox login <token-or-password> --registry ghcr.io --username myuser

# Log in to Docker Hub
vox login <password> --registry registry.hub.docker.com --username myuser

Credentials are stored in ~/.vox/auth.json. When you run vox deploy, the CLI will automatically authenticate with the configured registry before pushing.

[!TIP] For CI/CD pipelines, pass the token via stdin:

echo "$REGISTRY_TOKEN" | vox login token --registry ghcr.io --username $REGISTRY_USER

2. Deploying with vox deploy

The simplest way to deploy your application is using the vox deploy command. This handles building your container image, authenticating with the registry, and pushing.

# Vox.toml
[deploy]
image_name = "my-registry.io/my-vox-app"
registry   = "my-registry.io"
runtime    = "podman"  # optional: docker or podman (auto-detected if omitted)

Then run:

vox deploy
# or for a specific environment:
vox deploy --env staging

vox deploy automatically:

1. Detects your container runtime (Podman preferred, Docker fallback)
2. Builds the OCI image
3. Authenticates with your registry using credentials from vox login
4. Tags and pushes the image

3. Manual Packaging

If you prefer building yourself, Vox generates an OCI-compatible Dockerfile:

vox package --kind docker
docker build -t my-vox-app .

4. Persistent Storage

Since Vox uses SQLite for the data layer and durability journal, ensure you mount a persistent volume if deploying as a container.

# fly.toml example
[mounts]
  source = "vox_data"
  destination = "/data"

Related Reference:

• Fullstack Artifacts — Rust-first containers vs Express server.ts.
• CLI Reference — All vox package and vox deploy options.
• Runtime Explanation — Understanding the runtime environment.

How-To: Handle Errors Gracefully

Learn the best practices for error management in Vox to build robust, fault-tolerant applications.

1. The Result Type

Vox uses the functional Result[T, E] type for operations that can fail, rather than standard exceptions.

// vox:skip
fn find_user(id: str) -> Result[str] {
    if id == "" {
        return Error("Invalid ID")
    }
    return Ok(id)
}

2. Using the ? Operator

The ? operator provides ergonomic error propagation. If an expression evaluates to Error, the surrounding function returns that error immediately.

// vox:skip
fn process_order(id: str) -> Result[bool] {
    let user = find_user(id)?
    // `check_balance` might also return a Result
    // let balance = check_balance(user)?
    return Ok(true)
}

3. Error Handling

Vox allows you to handle Result types directly using exhaustive pattern matching. (Error display in UI is covered in the islands tutorial).

// vox:skip
let result = find_user("123")

match result {
    Ok(user)   -> println("Found { " + user)
    Error(msg) -> println("Failed: " + msg)
}

4. Converting Errors with Result[T, E]

You can transform results using functional combinators or explicit pattern matching.

// vox:skip
fn get_user_name(id: str) -> Result[str] {
    let user = find_user(id).map_err(|e| "User fetch failed: " + e)?
    return Ok(user.name)
}

5. Preconditions with @require

For invariant safety (assertions that must hold for a type to be valid), use the @require decorator. This acts as a construction-time guard.

// vox:skip
@require(self.age >= 18)
type Adult {
    name: str
    age: int
}

If the condition fails during instantiation, a panic is triggered (or an error returned if used within a fallible constructor context).

Best Practices

1. Surface Results Early: Always surface the Result type rather than attempting to unwrap() or panic inside production web routes.
2. Contextualize Errors: Use .map_err() to add context to low-level errors (e.g., "Database error" -> "Failed to save user").
3. Use ? for Flow: The ? operator is the preferred way to maintain a "happy path" while handling fallibility.

Summary

• Use Result for operations that can gracefully fail.
• Use ? to easily propagate Error up the call stack.
• Use pattern matching with match blocks to unwrap and inspect the branches safely.

Related

• Language Syntax — Syntax for match and ?.
• Durable Workflows — Automatic error recovery in long-running tasks.

How-To: Build UI with Islands and Pages

Vox relies on a server-first web architecture. Rather than building massive client-side bundles, Vox generates raw HTML routes and uses targeted interactive "islands" for dynamic functionality.

(Note: The legacy @island decorator has been removed in v0.3. Use @island and http get instead).

When to use @island vs http get

• Use http get: When you need to return server-side rendered data, pages that require no Javascript, or raw API responses like JSON.
• Use @island: When the user needs to click, type, drag, or interact with state dynamically. Islands compile into hydrated React components under the hood.

Defining an Island with Props

Let's stick with the Task domain. Suppose you want a UI component to render a list of tasks.

// vox:skip
import react.use_state

@island
fn TaskList(tasks: list[Task]) -> Element {
    let (items, set_items) = use_state(tasks)

    <div class="task-list">
        <h1>"Your Tasks"</h1>
        <ul>
            {items.map(fn(task) {
                <li>{task.title}</li>
            })}
        </ul>
    </div>
}

JSX Syntax within an Island

Within an @island body, the compiler supports standard JSX syntax.

• You can embed variables and functions within braces {}.
• You can include inline conditionals and standard attributes.
• Events like onChange or onClick are fully typed and bind directly to functions.

Calling @server Functions from an Island

The power of Vox is that your frontend and backend are co-located in the same file. You can call an @server function directly from a client-side button click without writing manual fetch() bindings!

// vox:skip
@server fn complete_task(id: Id[Task]) -> Result[Unit] {
    db.Task.update(id, { done: true })
    return Ok(())
}

@island
fn TaskRow(task: Task) -> Element {
    <div class="task-row">
        <input 
            type="checkbox" 
            checked={task.done} 
            onChange={fn(_e) complete_task(task.id)} 
        />
        <span>{task.title}</span>
    </div>
}

The Vox compiler automatically generates the TypeScript client, handles the asynchronous RPC call, and returns the result back to your interactive component.

Passing Data from Server to UI

To get your database state into the TaskList, you map an endpoint directly to the UI component via the routes block. The system will automatically resolve queries to fulfill the tasks prop of TaskList.

// vox:skip
@query
fn get_active_tasks() -> list[Task] {
    return db.Task.where({ done: false }).all()
}

routes {
    // The framework will fetch `get_active_tasks` and inject the data
    // into the `TaskList` component as props, then render to HTML.
    "/" -> TaskList(tasks: get_active_tasks())
}

The Data/View routes { } Block

The routes block maps URL paths directly to server responses or UI.

// vox:skip
routes {
    "/"              -> HomeIsland     # Render an Island 
    "/tasks"         -> TaskList       # Render the TaskList
    "/dashboard"     -> Dashboard      # Render a complex page
}

AI-Generated Islands

[!TIP] Vox supports a special @v0 decorator for pulling down interface prototypes.

@v0 "yM1xXq6"
fn PricingTable() -> Element

The orchestrator will dynamically download the requested implementation into target/generated/ at build time by calling Vercel's CLI. Use this pattern to integrate high-fidelity layouts without context switching.

Related Topics:

• Tutorial: Building UI with Islands
• Reference: Web Model

How-To: Model Complex Domain Logic

Learn how to use Vox's expressive type system to model your application's domain logic effectively.

1. Algebraic Data Types (ADTs)

Vox supports powerful ADTs (sum types) for representing state that can be one of several variants.

// vox:skip
type OrderStatus =
    | Pending
    | Processing(staff_id: str)
    | Shipped(tracking_number: str)
    | Delivered(timestamp: int)

2. Pattern Matching

Use the match expression to handle ADT variants with full type safety.

// vox:skip
fn describe_status(status: OrderStatus) -> str {
    return match status {
        Pending         -> "Waiting for staff"
        Processing(id)  -> "Being handled by " + id
        Shipped(track)  -> "In transit { " + track
        Delivered(_)    -> "Package reached destination"
    }
}

3. Composing Structs

Group related data into named structs.

// vox:skip
type Address {
    street: str
    city:   str
    zip:    int
}

type Customer {
    name:  str
    email: str
    shipping_address: Address
}

4. Validation with @require

Add runtime guards to your data types using the @require decorator.

// vox:skip
@require(len(self.password) > 8)
type UserAccount {
    username: str
    password: str
}

Summary

• Describe mutually exclusive states and data variants cleanly using ADTs (Sum Types).
• Avoid invalid states with constructor validation guards via @require.
• Pattern match to strictly process all possibilities at compile time.

Related

• Language Syntax — Full type system syntax.
• Database Schema — Modeling domain with tables.

How-To: Publish Scientia findings

This workflow uses a single publication manifest in Codex (publication_manifests) with digest-bound approvals and scholarly submission tracking.

Note: scholarly submit defaults to local_ledger (VOX_SCHOLARLY_ADAPTER). For architecture and lingo, see VoxGiantia publication architecture. For operator inputs vs derived fields, see operator inputs. For remediation, see publication playbook. Policy SSOT: scientia-publication-automation-ssot, worthiness rules, readiness audit.

Fastest safe path

When you already have a prepared SCIENTIA manifest, the shortest safe default path is:

1. vox scientia publication-preflight --publication-id <id> --with-worthiness
2. Fix anything in findings, manual_required, and ordered next_actions.
3. Record two digest-bound approvals.
4. Run vox scientia publication-scholarly-pipeline-run --publication-id <id> --dry-run.
5. Re-run without --dry-run when the output looks correct.

Use vox scientia publication-status --publication-id <id> --with-worthiness as the ongoing checklist surface when you also want the worthiness rubric inline; without the flag it still includes the same readiness report and next_actions, plus approvals, attempts, submissions, and status events.

Discovery → draft assistance (deterministic)

• vox scientia publication-discovery-scan — ranks stored scientia manifests by structured scientia_evidence signals (strong / supporting / informational). Use vox db publication-discovery-scan with --content-type / --state when you need filters beyond the scientia facade default.
• vox scientia publication-discovery-explain --publication-id <id> — machine explanation, manifest completion report, evidence completeness, and a non-authoritative transform preview (labels machine_suggested + requires_human_review).
• vox scientia publication-transform-preview --publication-id <id> — preview-only JSON for scholarly/social stubs.
• vox scientia publication-discovery-refresh-evidence --publication-id <id> — merges live Socrates telemetry + JSON sidecars, rebuilds scientia_evidence (headings, signals), upserts digest; emits discovery_evidence_refreshed. MCP: vox_scientia_publication_discovery_refresh_evidence.
• Preflight JSON now includes destination_readiness (credential presence checks; no secret values).

Anti-slop: LLM assists (vox_scientia_assist_suggestions in MCP) must output JSON checklists grounded on provided evidence; they do not establish novelty or scientific truth. See contracts/scientia/machine-suggestion-block.schema.json and scientia-a2a-evidence-tasks.

1) Prepare a manifest

vox scientia publication-prepare \
  --publication-id ai-research-2026-03 \
  --author "Your Name" \
  docs/src/research/ai-research-2026-03.md

If you omit --title, Vox now infers it from markdown frontmatter title: or the first # Heading.

Optional: pass --title, --abstract-text, --citations-json <file>, and --scholarly-metadata-json <file> (structured JSON for scientific_publication: authors with optional ORCID/affiliation, license_spdx, funding_statement, competing_interests_statement, reproducibility, ethics_and_impact — see vox_publisher::scientific_metadata). The same --scholarly-metadata-json flag works on vox db publication-prepare.

To use publication-prepare as an early discovery-to-draft bridge instead of a blank manifest step, also pass any structured evidence you already have:

• --eval-gate-report-json <repo-file>
• --benchmark-pair-report-json <repo-file>
• --human-meaningful-advance
• --human-ai-disclosure-complete

When those inputs are present, SCIENTIA seeds metadata_json.scientia_evidence with discovery signals, draft-preparation hints, and a short candidate note, then records a discovery_candidate_prepared status event.

Use --preflight (or publication-prepare-validated) -> run vox_publisher::publication_preflight before persisting; use --preflight-profile arxiv-assist when the handoff target is arXiv (requires abstract_text). Optional --discovery-intake-gate strong-signals-only or allow-review-suggested blocks scientia publication-prepare when deterministic discovery rank does not meet the tier (empty evidence ranks as low-signal unless you pass sidecars). MCP vox_scientia_publication_prepare accepts scientia_evidence JSON and the same gate when you prepare from agents without repo-relative report files. Use publication-preflight to inspect readiness JSON for an existing id (including manual_required, confidence, and live-publish gate hints when VoxDb is attached); add --with-worthiness to score against contracts/scientia/publication-worthiness.default.yaml. CLI-prepared manifests now include repository_id automatically, so --with-worthiness can merge live socrates_surface telemetry and repo-local scientia_evidence sidecars into the same decision path. You may also embed scientia_evidence manually (eval-gate result, baseline/candidate run ids, human_meaningful_advance, human_ai_disclosure_complete) so worthiness blends orchestrator telemetry with explicit human attestations. Use publication-zenodo-metadata to emit a Zenodo metadata object (stdout) for manual or scripted upload.

2) Record approvals (two distinct approvers)

vox scientia publication-approve --publication-id ai-research-2026-03 --approver alice
vox scientia publication-approve --publication-id ai-research-2026-03 --approver bob

Approvals are bound to the current content digest. If content changes, re-approve the new digest.

3) Default scholarly pipeline

vox scientia publication-scholarly-pipeline-run --publication-id ai-research-2026-03 --dry-run
vox scientia publication-scholarly-pipeline-run --publication-id ai-research-2026-03

This is the preferred scholarly path because it reuses preflight, the dual-approval gate, optional staging export, and submit in one flow instead of asking the operator to choose the low-level sequence each time.

4) Submit to scholarly adapter directly

vox scientia publication-submit-local --publication-id ai-research-2026-03

publication-submit-local uses the scholarly adapter selected by VOX_SCHOLARLY_ADAPTER (default local_ledger; echo_ledger for deterministic/no-network tests) and writes submission metadata to scholarly_submissions. Unknown adapter names error (no silent fallback).

5) Inspect lifecycle state

vox scientia publication-status --publication-id ai-research-2026-03 --with-worthiness

The status payload includes:

• current manifest state
• active content digest + version
• approval count for that digest
• embedded preflight report with manual_required and ordered next_actions
• optional inline worthiness output when --with-worthiness is set
• scholarly submission rows and external submission ids
• media assets, publication attempt timeline, and status event timeline

6) Optional social distribution metadata

To drive Reddit/Hacker News/YouTube planning from the same manifest, embed a metadata_json.syndication object conforming to:

• contracts/scientia/distribution.schema.json
• contracts/scientia/distribution.default.yaml

Legacy manifests may still use metadata_json.scientia_distribution. At hydrate time the publisher deep-merges legacy + canonical keys (canonical syndication wins on conflicts), normalizes contract channels / channel_payloads into the flat runtime shape, and logs a deprecation warning when the legacy root is present. vox db publication-preflight surfaces the same hint under manual_required.

Important runtime alignment notes:

• distribution_policy.channel_policy is the supported location for per-channel policy.
• Root-level channel_policy is deprecated; runtime migrates it with a warning.
• crosspost_plan is currently reserved and ignored by runtime hydration.
• Channels like reddit, github, open_collective, youtube, and crates_io need matching channel_payloads.<channel> blocks before they materialize into a live runtime channel.

Optional metadata_json.topic_pack: set to a pack id from contracts/scientia/distribution.topic-packs.yaml (for example research_breakthrough). At hydrate time the pack merges worthiness floors, template profiles, and topic filters into the effective syndication config. Channel allowlists in the pack drop any channel not listed for that pack (after merge), so operators can tighten routing without editing every manifest.

Minimum-input recipe: set topic_pack + enable only the channels you need (or rely on pack allowlists). Omit per-channel payloads when the pack supplies policy; add channel_payloads / flat twitter / reddit blocks only for overrides.

Example skeleton:

{
  "topic_pack": "research_breakthrough",
  "syndication": {
    "channels": ["reddit", "hacker_news", "youtube"],
    "channel_payloads": {
      "reddit": {
        "subreddit": "MachineLearning",
        "kind": "link"
      },
      "hacker_news": {
        "mode": "manual_assist"
      },
      "youtube": {
        "video_asset_ref": "artifacts/videos/demo.mp4",
        "privacy_status": "private"
      }
    },
    "distribution_policy": {
      "approval_required": true,
      "dry_run": true,
      "channel_policy": {
        "reddit": {
          "enabled": true,
          "template_profile": "deep_dive_selfpost",
          "worthiness_floor": 0.82,
          "topic_filters": {
            "include_tags": ["research_breakthrough", "benchmark"],
            "exclude_tags": ["internal_only"],
            "min_topic_score": 0.2
          }
        }
      }
    }
  }
}

Notes:

• Hacker News support is manual-assist only (official API is read-only).
• YouTube support uses OAuth refresh + resumable upload and should remain policy-gated by quota and audit readiness.
• crates_io is modeled in routing policy and outcomes; live publish adapter wiring remains intentionally explicit (non-implicit).
• distribution_policy.channel_policy.*.template_profile does not change copy unless VOX_SYNDICATION_TEMPLATE_PROFILE=1 / true (then Twitter/Reddit/YouTube derived text caps follow named profiles such as brief / roomy; see docs/src/reference/env-vars.md).
• Configure social credentials via VOX_SOCIAL_* environment variables (docs/src/reference/env-vars.md).
• SSOT precedence is: manifest overrides > distribution policy defaults/contracts > runtime env overrides.

7) Route simulation and controlled fan-out

Use vox db for operator controls that are broader than the vox scientia convenience subset:

vox db publication-route-simulate --publication-id ai-research-2026-03
vox db publication-route-simulate --publication-id ai-research-2026-03 --json
vox db publication-publish --publication-id ai-research-2026-03 --channels reddit,youtube --dry-run true
vox db publication-publish --publication-id ai-research-2026-03 --channels reddit,youtube --dry-run true --json
vox db publication-retry-failed --publication-id ai-research-2026-03 --dry-run true
vox db publication-retry-failed --publication-id ai-research-2026-03 --dry-run true --json

Add --json for machine-readable stdout (one structured object per invocation). MCP equivalents vox_scientia_publication_publish and vox_scientia_publication_retry_failed accept json: true for a single-line compact JSON tool envelope.

Retry-failed idempotency: publication-retry-failed / MCP vox_scientia_publication_retry_failed pick candidates from the latest digest-bound attempt. Channels that already have a Success outcome for that digest are not republished (they appear as skipped_success_channels). Explicit --channel / channel follows the same planner so operators cannot accidentally duplicate a succeeded post when retrying a subset.

How-To: Rust crate imports in Vox scripts

This page is the SSOT for the current import rust:… feature: what it does in the toolchain, what it does not do yet, and how to evolve it with high leverage and low Kolmogorov complexity (small mental model, few rules, familiar Cargo concepts).

In the bell-curve interop model, import rust:... is a Tier 3 escape hatch. See Interop tier policy.

Syntax (what you can write today)

Rust crate imports use the reserved prefix rust: on an import entry. They can be comma-separated with ordinary symbol imports in the same import statement.

// vox:skip
import react.use_state
import rust:serde_json
import rust:serde_json(version: "1") as json
import rust:my_thing(path: "../crates/my_thing"), rust:other(git: "https://example.invalid/repo", rev: "main")

Metadata keys (inside parentheses)

Keys are identifiers; values may be string literals or simple identifiers.

Compatibility rule: Do not specify both path and git for the same import; the compiler rejects that combination.

Same crate twice: You may bind the same crate under two aliases only if the dependency tuple (version, path, git, rev) is identical. Otherwise you get a lowering diagnostic (conflicting specs).

Architecture (end-to-end)

The feature is implemented inside the existing compiler and codegen crates, not as a sidecar tool.

flowchart LR
  A["`.vox` source"] --> B["Lexer / Parser"]
  B --> C["AST `ImportPathKind::RustCrate`"]
  C --> D["HIR `HirRustImport`"]
  D --> E["Type registration"]
  D --> F["`Cargo.toml` synthesis"]
  F --> G["`cargo build` in cache / generated crate"]

1. Parse — rust: is recognized only when the first segment is the identifier rust followed by :; see crates/vox-compiler/src/parser/descent/decl/head.rs (parse_import_path).
2. AST — ImportPath carries ImportPathKind::RustCrate(RustCrateImport) plus optional alias; see crates/vox-compiler/src/ast/decl/types.rs.
3. HIR — Lowering fills HirModule::rust_imports (HirRustImport: crate name, alias, version/path/git/rev, span); symbol-style imports still populate HirModule::imports; see crates/vox-compiler/src/hir/lower/mod.rs.
4. Validation — crates/vox-compiler/src/hir/validate.rs checks empty names, conflicting path+git, etc.
5. Type checking — register_hir_module binds the alias to an internal Ty::Named("RustCrate::<crate>") and reports alias clashes with other top-level names; conflicting metadata for the same crate name emits DiagnosticCategory::Lowering; see crates/vox-compiler/src/typeck/registration.rs.
6. Code generation — Script mode (generate_script_with_target) and full-server emit (emit_cargo_toml) append extra [dependencies] lines derived from rust_imports, with deduplication by crate name (first spec wins in the map). See crates/vox-compiler/src/codegen_rust/pipeline.rs and crates/vox-compiler/src/codegen_rust/emit/mod.rs.

CLI and diagnostics

• vox check runs the same frontend (lex → parse → typecheck → HIR validate). With global --json, type/HIR diagnostics are printed as a JSON array (category, severity, message, line, col, file); see crates/vox-cli/src/pipeline.rs and crates/vox-cli/src/commands/check.rs.
• Golden coverage for a Lowering rust-import diagnostic lives in crates/vox-cli/tests/golden/check_rust_import_lowering.json.

Relation to Vox PM (vox.lock)

Project dependencies for Vox packages still flow through Vox.toml / vox.lock / vox sync (see reference/cli.md). import rust:… is compile-time Cargo manifest sugar for generated crates: it does not by itself add rows to vox.lock. Longer term, aligning “script deps” with the PM graph is optional hardening (see below).

Current capabilities vs limitations

What works

• Declaring extra Cargo dependencies for generated script binaries and generated full-stack Rust outputs.
• Deterministic merge/dedup of dependency lines per crate name in codegen.
• Strict error when the same crate name is imported with incompatible version/path/git/rev metadata.
• WASI script guardrail: native-only crates listed under wasi_unsupported_rust_imports in contracts/rust/ecosystem-support.yaml are rejected as rust imports in WASI mode; examples include tokio and axum.

What does not work yet (important)

• No automatic Rust use or Vox-call mapping: Adding import rust:serde_json updates Cargo.toml only. It does not emit Rust that calls serde_json from lowered Vox code, and does not import items into the Vox type universe from rustdoc or rustc.
• The alias is not a typed API surface: Bindings use the internal marker type RustCrate::<crate>. Field access on that binding is rejected in the typechecker with a clear error (see crates/vox-compiler/src/typeck/checker/expr_field.rs).
• Default version *: If you omit version / path / git, codegen emits a loose crates.io requirement (crate = "*"), which is convenient for experiments but weak for reproducibility.
• No linkage to cargo vendor / vendoring policy in this path alone; reproducibility remains “whatever Cargo resolves” unless you tighten versions or use path/git explicitly.

Plain language: today’s feature is best thought of as “make this script’s generated crate depend on these Rust packages.” It is not yet “call arbitrary Rust APIs from Vox with one line.”

Support-class annotations and reproducibility warnings

Rust imports now carry a support-class classification for clearer operator expectations:

• first_class
• internal_runtime_only
• escape_hatch_only
• deferred

Current compiler behavior:

• emits warnings when a crate is classified as internal_runtime_only or deferred
• emits warnings when a crate is classified as escape_hatch_only
• emits warnings when a crate has planned semantics in the support registry
• emits warnings when no version / path / git pin is provided (Cargo fallback *)
• emits warnings when import-level pins are provided for full app template-managed crates (those templates may own versions/paths)
• annotates generated Cargo.toml dependency lines with # vox_rust_import support_class=...

These annotations are guidance, not a typed interop promise.

Canonical support matrix and contract metadata:

• Rust ecosystem support contract

For common app capabilities, prefer:

1. builtins and std.* surfaces,
2. approved wrappers,
3. package-managed Vox libraries,
4. import rust:... only when the earlier tiers do not fit.

Reducing K-complexity and boilerplate (without breaking compatibility)

Keep the mental model small:

1. One syntax only — Keep import rust:… as the single user-facing form; avoid parallel @rust.import or magic decorators unless they lower to the same AST (doc and tooling stay simpler).
2. Cargo is the execution truth — Users already understand version / path / git. Prefer mapping from those fields to Cargo.toml over inventing a third version language.
3. Layer capabilities — Dependency declaration (done) → optional manifest merge from project lock (next) → optional thin escape hatch or shims (later).

High-impact, not over-engineered wins

These are ordered by value / effort:

1. Implicit versions from project context (medium)
   If Vox.toml or a sibling Cargo.toml / lockfile already pins serde_json, allow import rust:serde_json without repeating version: "…", by resolving from the project graph when building from a workspace package. Compatibility: When no pin exists, keep today’s behavior (* or diagnostic). K win: One-line imports match user expectation of “like Cargo.”

2. vox check / cargo check parity messaging (low)
   When script codegen fails, surface Cargo’s error with a hint { “dependency X declared via import rust:X at line L.” Ties the mental model to the line they wrote.

3. Curated vox-* or shims for 5–10 hot crates (medium)
   Instead of full rustdoc typing, expose std-style namespaces for e.g. JSON, time, UUID (wrappers in vox-runtime or a small vox-shims crate). K win: Users learn one Vox API; compiler stays small. Big win: Works today under the existing builtin pattern.

4. Single escape hatch: embedded Rust snippet with explicit unsafe boundary (medium–high)
   A block or decl that copies almost verbatim into generated main / module, with scoped use generated from adjacent import rust:…. Compatibility: Opt-in, clearly marked; keeps the main language pure. K win: Power users stop fighting the compiler; everyone else ignores it.

5. Defer: full dynamic rustdoc / rustc-based typing
   High cost, long-term maintenance, and versioning traps. Prefer shims + escape hatch until the language stabilizes.

Wins to defer (usually over-engineered for the current stage)

• Full ABI-stable plugin system for every crate.
• Automatic WASM component bindings for arbitrary crates.
• Replacing Cargo with a custom resolver for script deps.

Those belong behind explicit feature gates and product milestones, not on the default path.

Related docs

• Keyword: import syntax
• CLI reference: PM vs generated Cargo.lock
• Diagnostic taxonomy
• Vox packaging blueprint (extension boundaries)

Maintenance: When you change parser, HIR, registration, or codegen behavior for rust imports, update this page and the golden JSON under crates/vox-cli/tests/golden/ if diagnostics or spans shift. After contract/policy edits, run cargo run -p vox-cli --quiet -- ci rust-ecosystem-policy.

How-To: Scale Actors

As your application grows beyond a single executable, Vox Actors must scale horizontally across the Populi mesh or large orchestrated deployments.

The Concept of Actor Affinity

By default, an initialized Actor runs in memory on the node where spawn was invoked. In a distributed environment, you rely on the Codex to synchronize and persist state securely.

// vox:skip
actor SessionManager {
    on Login(user: str) -> Result[str] {
        let current_sessions = state_load("active_users")
        // logic ...
        state_save("active_users", current_sessions)
        return Ok("Success")
    }
}

Because state_save natively pushes updates to Codex, another node starting a SessionManager actor targeting the same specific state scope can seamlessly resume operations.

Load Balancing and Populi

When scaling the inference compute or orchestration logic via Populi Meshes, Vox abstracts message routing.

1. Local Node Execution: Functions run via Tokio threads in the core binary.
2. Distributed GPU Execution: LLM evaluation or heavy compute tasks explicitly placed on GPU labeled nodes.

To dispatch an orchestration task externally, the framework determines placement inherently via the resource requests.

[!WARNING] Manual remote procedure calls (RPC) -> force specific Actor placement remains in active development. As of v0.3, horizontal scaling predominantly operates seamlessly behind standard routes { } load-balancing and Turso replicated databases, rather than direct point-to-point remote actor message passing.

Actor Naming and Discovery

By default, spawn produces a random anonymous identity. For singleton services or discoverable workers, you can provide a stable name.

Stable names allow the system to route messages to the correct instance across a cluster and ensure that only one instance of that specific actor exists.

// vox:skip
let session_ref = spawn SessionManager() with { name: "user_session_" + user_id }

Lifecycle and Restart Behavior

Actors in Vox are designed for "Let it Crash" reliability. If an actor panics or its host node fails:

1. Detection: The Process Registry (Codex) detects the heartbeat failure.
2. Re-hydration: The actor is re-spawned on a healthy node.
3. Recovery: The new instance calls state_load. Since state_save was persistent, no data is lost.
4. Resumption: Message ordering is guaranteed; pending messages in the durable mailbox are redelivered to the new instance.

Best Practices for Scale

• Prefer Workflows: For long-running business logic, workflow is safer than a long-lived actor because and provides step-level journaling.
• Stateless handlers: Keep actor handlers as pure as possible between state_load and state_save.
• Avoid Large State: Keep actor state small (under 1MB) to ensure rapid re-hydration across nodes.

How-To: System I/O

Vox code natively compiles into isolated WASI execution bounded containers or strict actor channels. System IO (disk reading/writing, network fetching) runs under the std.fs and std.http global contexts.

[!IMPORTANT] Aspirational @task sandboxes or untrusted LLM code generated at runtime may have explicit prohibitions against invoking arbitrary std.fs or std.http targets. See Explanation: Capabilities.

Reading and Writing Files

The std.fs package treats operations as inherently failable (returning Result).

// vox:skip
import std.fs

fn process_log() -> Result[Unit] {
    let contents = fs.read("/var/logs/app.log")?
    
    if len(contents) > 1000 {
        fs.write("/var/logs/app-archive.log", contents)?
        fs.write("/var/logs/app.log", "")?
    }
    
    return Ok(())
}

External Network Requests

Vox uses std.http to generate outbound JSON API requests, translating directly to reqwest instances under the hood.

// vox:skip
import std.http
import rust:serde_json as json

fn query_weather(city: str) -> Result[str] {
    let endpoint = "https://api.weather.com/v1/" + city
    let response = http.get(endpoint)?
    return Ok(response)
}

If you are posting complex ADT models, serialize them safely across the JSON integration boundary.

// vox:skip
fn publish_event(topic: str, payload: str) -> Result[Unit] {
    let body = json.encode({ topic: topic, message: payload })
    let res = http.post_json("https://webhook.site/abc", body)?
    
    assert(res == "200 OK")
    return Ok(())
}

Handling Errors Gracefully

Always surface the Result type rather than attempting to unwrap() or panic inside production web routes, to allow the framework to map the error to a correct HTTP 500 equivalent.

How-To: Test Your Logic

Learn how to write and run automated tests for your Vox application using the built-in test runner.

1. Writing Unit Tests

Use the @test decorator to mark functions as test cases. These functions can be run with the vox test command.

// vox:skip
@test 
fn test_addition() -> Unit {
    assert(1 + 1 == 2)
}

2. Hand-Rolled Setup Helpers (Fixtures)

Rather than language-level magic, Vox encourages simple, plain functions for setup logic that can be reused across test cases.

// vox:skip
fn setup_mock_db() -> Database {
    return spawn MockDatabase()
}

@test 
fn test_query() -> Unit {
    let db = setup_mock_db()
    let result = db.call(query("SELECT 1"))
    assert(result == [1])
}

[!WARNING] Historical decorators @fixture and @mock are considered aspirational. Use standard helper functions for state-setup instead.

3. Property Writing with @forall

Vox supports property-based testing. The test runner will generate random inputs for your function to find edge cases where your assertions fail.

// vox:skip
@forall
fn test_addition_commutative(a: int, b: int) -> Unit {
    assert(a + b == b + a)
}

4. Fuzzing with @fuzz

For deeper security and stability testing, the @fuzz decorator uses the project's native LLVM-based fuzzer to explore illegal execution paths.

// vox:skip
@fuzz
fn fuzz_parser(input: str) -> Unit {
    let _ = parse_json(input) // Fuzzer tries to crash this
}

5. Running Tests and Output Format

Use the vox test command to execute your suite.

vox test src/

Output Example:

[PASS] tests::test_addition (1.2ms)
[PASS] tests::test_addition_commutative (100 iterations)
[FAIL] tests::fuzz_parser
       > Reason: Panic at core.vox:120 (division by zero)
       > Input: "{"a": 0}"

Summary

• Use @test for standard unit tests.
• Use @forall for property-based data validation.
• Use @fuzz for security and crash-resilience testing.
• Write standard functions that serve as setups, fixtures, and mocks explicitly.
• Run vox test <path> to execute blocks tagged with @test.

Related

• CLI Reference — vox test flags and configuration.
• Durable Workflows — Understanding testable workflows.

How-To: Testing Integration

Testing in Vox focuses on unit tests and bounded integration tests using the @test decorator. Note that the legacy @mock and @fixture features have been removed or placed into aspirational scope for v0.3.

Structuring a Test

Any function annotated with @test will be executed during a vox test invocation. The assert global built-in is used to evaluate conditions.

// vox:skip
fn calculate_total(subtotal: int, tax: int) -> int {
    return subtotal + tax
}

@test
fn test_calculate_total() -> Unit {
    let result = calculate_total(100, 10)
    assert(result == 110)
}

Testing Result Returns

When testing functions that return Result[T, E], you typically use match to assert the correct execution branch.

// vox:skip
@test
fn test_database_insert_validation() -> Unit {
    let invalid_data = { title: "", owner: "alice" }
    
    // Assuming db.Task.insert has a length requirement on title
    match db.Task.insert(invalid_data) {
        Ok(_) -> assert(false) // Should fail
        Error(_) -> assert(true) // Expected
    }
}

Testing Asynchronous Workflows

Workflows and Activities evaluate sequentially and synchronously from the tester's perspective because the execution context blocks until the workflow concludes or hits a checkpoint limit.

// vox:skip
@test
fn test_order_workflow() -> Unit {
    // Run the workflow natively
    let result = process_order("alice", 500)
    
    match result {
        Ok(tx) -> assert(len(tx) > 0)
        Error(_) -> assert(false)
    }
}

Running Tests

Execute all tests in the workspace {

vox test

Execute tests targeting a specific module:

vox test src/domain/tasks.vox

You can view the specific failures via standard error stack traces emitted by the V0.3 compiler pipeline.

How-To: Use the Database Layer

Vox utilizes a unified storage paradigm known as Codex, which compiles into type-safe SQLite database schemas and Rust structs. You never need to write raw migrations; they are deterministically derived from your file structures.

Defining a Table

Any type struct adorned with the @table decorator becomes a persistent database entity.

@table type Note {
    title: str
    content: str
}

Indexing for Performance

To speed up lookups on large datasets, use the @index syntax. Vox determines the optimal storage engine (B-Tree or Hash) and generates the SQL automatically.

// vox:skip
@table type User {
    email: str
    team_id: Id[Team]
}

// Unique index: prevents duplicate emails
@index User.unique_email on (email) unique

// Composite index: speeds up filtered team lookups
@index User.by_team on (team_id, email)

[!TIP] Always index foreign keys (like Id[T]) if you plan to filter or join on them frequently.

Basic CRUD Accessors

The built-in db module uses code-generation to inject statically typed accessors for all your @table types.

• Create:

  // vox:skip
  let new_id: Id[Task] = db.Task.insert({ 
      title: "Clean desk", 
      done: false, 
      priority: 1, 
      owner: "alice" 
  })
  

• Read:

  // vox:skip
  match db.Task.find(new_id) {
      Some(t) -> println(t.title)
      None    -> println("Not found")
  }
  

• Update:

  // vox:skip
  db.Task.update(new_id, { done: true })
  

• Delete:

  // vox:skip
  db.Task.delete(new_id)
  

Advanced Filtering

Instead of raw string interpolation, use Vox's exact literal querying to avoid injection attacks.

// Fetch simple exact match parameters

// vox:skip
let alice_tasks = db.Task.filter({ owner: "alice" })

// Advanced predicate-object queries

// vox:skip
let urgent_tasks = db.Task.where({ priority: { gt: 10 }, done: { eq: false } }).all()

Query Chaining

You can apply limits, multi-field ordering, and select specific field projections by chaining.

// vox:skip
let feed = db.Task
            .where({ done: false })
            .order_by("priority", "desc")
            .limit(10)
            .all()

Guarding Reads/Writes with @query and @mutation

For security, you should rarely expose db.* calls directly to UI islands or agents. Instead, wrap your database interactions in @query (read-only) and @mutation (write-enabled) functions.

The compiler verifies that a @query function does not contain .insert, .update, or .delete operations.

Transactional Integrity with @mutation

Every function marked with @mutation is automatically wrapped in a database transaction. If the function returns an Error or panics, the transaction is rolled back.

// vox:skip
@mutation
fn transfer_funds(from: Id[Account], to: Id[Account], amount: int) -> Result[Unit] {
    let mut sender = db.Account.find(from)?
    let mut receiver = db.Account.find(to)?
    
    sender.balance -= amount
    receiver.balance += amount
    
    db.Account.update(from, sender)
    db.Account.update(to, receiver)
    
    return Ok(())
}

Under the hood, this uses Codex::transaction to ensure ACID compliance across the local SQLite or distributed Turso mesh.

The Escape Hatch: Raw SQL

Occasionally, complex analytic aggregations exceed the currently supported ORM builder patterns. You can drop down to raw SQL using db.query.

[!WARNING] Use this only as a last resort. Raw SQL queries bypass Vox's type checking checks on schema changes.

// vox:skip
let count = db.query("SELECT COUNT(*) FROM Task WHERE owner = ?", ["alice"])

A Note on Codex

When running vox-run, the backing data source is the Local Codex Store (an embedded SQLite engine on disk). For enterprise orchestration and Populi GPU meshes, the database seamlessly promotes to Turso cloud sync clusters dynamically, without requiring any changes to your .vox schema definitions!

Related Topics:

• Reference: Database Surface
• Tutorial: Your First App

Model Routing & Provider Cascade

Vox uses a dynamic OpenRouter catalog as the primary cloud model source, with provider policy enforced in shipped surfaces via in-tree helpers (for example vox doctor under --features codex) and MCP / external vox-dei-d for full DeI routing. The vox-orchestrator crate is a workspace member but ships only a minimal lib.rs (Socrates floors); legacy sources on disk are not wired into that library—routing SSOT remains vox-dei-d, MCP, and vox-orchestrator.

Usage statistics and BYOK-style limits are persisted to Codex (Turso via vox-pm / vox-db) where wired; legacy docs may say vox-arca for the same storage plane.

For full runtime architecture and operational rollout details, also read:

• docs/src/expl-context-runtime-architecture.md
• crates/vox-cli/src/dei_daemon.rs — stable RPC method id SSOT for the external vox-dei-d daemon
• crates/vox-runtime/src/model_resolution.rs — OpenAI-compatible chat route resolution in the shipped runtime

Dynamic Catalog

The historical in-tree model_catalog narrative referred to the archival vox-orchestrator sources. Today, catalog refresh and normalization for CLI/MCP paths are owned by the daemon + MCP stack and vox-runtime / vox_config inference helpers. Conceptually the pipeline remains:

1. Fetches models from https://openrouter.ai/api/v1/models (public fetch; API key optional but recommended for consistent provider policy behavior)
2. Normalizes each entry to capability metadata (vision, cost, strengths) in the consumer
3. Caches under ~/.vox/cache/ where applicable
4. Falls back to cache, then static allowlists where implemented

API (if key) → Cache (if fresh) → Static fallback

Provider Cascade

┌─────────────────────────────────────────────────┐
│              Model Selection (catalog-driven)     │
├─────────────────────────────────────────────────┤
│  Layer 1: Google AI Studio (direct)             │
│  └── google/gemini-* from catalog (auto-selected)│
│                                                  │
│  Layer 2: OpenRouter (requires free API key)     │
│  └── :free models from catalog (Devstral, Qwen…)  │
│                                                  │
│  Layer 3: OpenRouter Paid (premium)              │
│  └── SOTA models from catalog                   │
│                                                  │
│  Layer 0: Ollama (always available, zero-auth)   │
│  └── any locally pulled model                   │
└─────────────────────────────────────────────────┘

How Model Selection Works

vox chat (CLI)

The minimal vox binary does not ship the historical interactive vox chat subtree. Use Mens / MCP / vox-dei-d for chat-shaped flows, or wire a new chat module deliberately behind an explicit feature. When a chat stack is enabled, the cascade conceptually remains:

1. Refresh or load catalog / model list (daemon or runtime)
2. Check for Google AI Studio key → prefer Gemini-family routes where configured
3. Check for OpenRouter key → respect --free / efficient vs paid routing in the active implementation
4. Check for Ollama → fall back to local inference (vox_config::inference::local_ollama_populi_base_url)
5. No keys → guide the user to free-tier setup

Mens / Ollama base URL

Local inference uses a single resolution order: OLLAMA_URL → POPULI_URL → default http://localhost:11434, exposed as vox_config::inference::local_ollama_populi_base_url() (SSOT in crates/vox-config/src/inference.rs). The Mens client (vox_runtime::mens::MensConfig::from_env) uses the same precedence.

Hugging Face Inference Providers (router)

For OpenAI-compatible chat against the HF Inference Providers router, use:

• URL: https://router.huggingface.co/v1/chat/completions (constant vox_runtime::inference_env::HF_ROUTER_CHAT_COMPLETIONS_URL)
• Token: HF_TOKEN or HUGGING_FACE_HUB_TOKEN via vox_config::inference::huggingface_hub_token()
• Descriptor: vox_runtime::inference_env::resolve_huggingface_router("org/model") returns model id, URL, and optional bearer token.
• Dedicated endpoint: vox_runtime::inference_env::resolve_huggingface_dedicated("https://….hf.space/v1/chat/completions", "model-id") for pinned Inference Endpoints (same token env vars).
• Env shortcut (policy resolver): HF_DEDICATED_CHAT_URL + HF_DEDICATED_CHAT_MODEL (see vox_config::inference::hf_dedicated_chat_completions_url / hf_dedicated_chat_model) are read by [vox_runtime::model_resolution::RouteResolutionInput::default] and take precedence over the shared router when an HF token is present.

Manual model pins and task overrides still win over automatic routing (see precedence below).

Hugging Face Hub catalog (text-generation)

vox_runtime::inference_env::fetch_hf_hub_text_generation_models(limit) calls the Hub /api/models listing (pipeline_tag=text-generation, sorted by downloads) and normalizes rows with parse_hf_hub_models_array. Use this for adapters and tooling that need a fresh allowlist without hardcoding model ids in business logic.

Runtime SSOT resolver (OpenAI-compatible chat)

vox_runtime::model_resolution::resolve_chat_provider_route applies fixed precedence: manual → Mens (GPU-prefer) → HF dedicated (token + dedicated env) → HF router (token + HF_CHAT_MODEL) → OpenRouter (key) → any Mens → OpenRouter bootstrap (OPENROUTER_AUTO). Map the result with chat_route_to_llm_config before vox_runtime::llm::llm_chat.

Unified four-lane backend semantics (orchestrator / MCP / runtime chat)

Registry-backed work (vox-orchestrator ModelSpec + route_backend_for_model) and HTTP chat routing share four normalized backend lanes for telemetry and dashboards:

SSOT for telemetry strings: vox_runtime::model_resolution::backend_telemetry_labels. MCP mcp_provider_telemetry_labels delegates to it so labels cannot drift.

Residual divergence (by design):

• Precedence vs lane: Runtime chat resolution still prefers HF dedicated/router when an HF token is present (see precedence above); those routes are labeled cascade for backend-family purposes, not as separate HF enum variants.
• Gemini without Generative Language URL: A pinned Gemini model delivered only through OpenRouter (OpenRouter-shaped URL/model id) is labeled openrouter, not google/direct, until the chat stack uses a Google direct endpoint URL.
• Orchestrator route_backend_for_model nuance: Non-OpenRouter third-party ProviderTypes map to OpenRouter vs CascadeFallback based on model id heuristics (e.g. org/model → OpenRouter lane); runtime chat has no equivalent until a concrete ChatProviderRouteKind is built for that call.

Helpers: route_backend_for_chat_route, route_telemetry_labels (derived from the backend). Structured logs from routers may still use different tracing targets; filter RUST_LOG by the binary you run.

Mens capability probe (GPU / health)

vox_runtime::inference_env::probe_populi_capabilities(base_url) (and PopuliClient::probe_capabilities) call Ollama-compatible /api/tags and /api/version. gpu_capable is Some(true) only when version JSON (string match) suggests CUDA, ROCm, or Metal; otherwise None if unknown.

Multi-agent / DeI (external daemon)

Full multi-agent model registry behavior (task categories, complexity bands, economy vs performance, research stage picks) lives in the vox-dei-d / MCP plane, not in the minimal compiled vox-orchestrator crate or its unwired legacy files. The in-tree vox-orchestrator crate handles affinity, routing metadata, and session layout for MCP and the vox live demo bus.

Dei task inference (precedence)

For orchestrator-attached tasks, treat precedence as task override → per-agent config → mode profile / env / Vox.toml → MCP model override, matching the semantics documented for MCP vox_submit_task / vox_set_model_override. Exact function names in archived vox-orchestrator sources are not authoritative for the slim CLI build.

MCP chat / inline / ghost override

Tools vox_set_active_model and vox_get_active_model pin the model used by vox_chat_message, vox_inline_edit, and vox_ghost_text to a registry id (must exist in vox_list_models). Pass an empty model_id to vox_set_active_model to clear the override and restore automatic best_for_config resolution (same path as chat when no override is set).

Route telemetry

Structured logs for route telemetry are emitted from the daemon / MCP implementation; use RUST_LOG filters documented for the binary you run (vox-mcp, vox-dei-d, etc.) rather than assuming a vox_orchestrator::... target in minimal workspace crates.

# Pseudocode shape (actual types live in DeI daemon / MCP, not in the minimal vox-orchestrator library)
registry.resolve_for_task(task_category, complexity, cost_preference, inference_config)

Escalation Chain

If a model fails (rate limit, error), chat-shaped surfaces escalate using catalog-driven fallback lists in the active DeI implementation. The chain is catalog-driven, not a hardcoded short list in vox-cli:

Catalog Refresh

Force-refresh the OpenRouter catalog (e.g. after new models are added):

vox status --refresh-catalog   # Refresh before showing provider status

The orchestrator-side registry also performs periodic refresh merges using:

• VOX_OPENROUTER_CATALOG_MIN_REFRESH_INTERVAL_SECS
• VOX_OPENROUTER_CATALOG_REFRESH_JITTER_MS

with a refresh marker in the Vox config directory to avoid excessive fetch churn.

Key Management

Keys are managed via the unified vox auth system:

vox auth login --registry google YOUR_KEY      # Google AI Studio
vox auth login --registry openrouter YOUR_KEY  # OpenRouter

# Keys stored in ~/.vox/auth.json
# Also reads from env vars: GEMINI_API_KEY, OPENROUTER_API_KEY

Cost Tracking

When using paid models, Vox tracks costs in Codex. You can check your current usage and estimated costs for the day:

Quota rollups that depended on the excluded in-tree DeI crate are not shipped in the default vox binary; inspect provider dashboards or Codex tables directly until a daemon-backed quota API is wired.

Cost data may still be persisted as provider-specific usage rows in Codex (Arca schema on Turso) where integrations exist.

Repository Context Controls (Rollout)

Add these keys under [dei] in Vox.toml for repo-aware chat/index/A2A behavior. (Legacy: [orchestrator] is also supported for backward compatibility.)

[dei]
context_window_soft_ratio = 0.80
context_window_hard_ratio = 0.95
repo_index_max_files = 12000
repo_index_max_file_bytes = 262144
provider_tool_calls_enabled = true
provider_tool_calls_max_per_turn = 5
provider_tool_calls_read_only_mode = false
repo_index_incremental = false   # set true for monorepos (vox repo enables it)
context_window_chars_per_token = 4
a2a_context_packet_enabled = true

Equivalent environment variables (prefer vox_orchestrator_*; VOX_DEUS_* and VOX_ORCHESTRATOR_* are legacy):

• vox_orchestrator_CONTEXT_WINDOW_SOFT_RATIO
• vox_orchestrator_CONTEXT_WINDOW_HARD_RATIO
• vox_orchestrator_REPO_INDEX_MAX_FILES
• vox_orchestrator_REPO_INDEX_MAX_FILE_BYTES
• vox_orchestrator_PROVIDER_TOOL_CALLS_ENABLED
• vox_orchestrator_PROVIDER_TOOL_CALLS_MAX_PER_TURN
• vox_orchestrator_PROVIDER_TOOL_CALLS_READ_ONLY_MODE
• vox_orchestrator_A2A_CONTEXT_PACKET_ENABLED

Operational MCP tools for rollout verification:

• vox_repo_index_status / vox_repo_index_refresh
• vox_context_sources
• vox_context_budget_snapshot / vox_compaction_history

Migration and environment compatibility

Scientia publication: operator inputs vs system-derived fields

Use this with How-To: Publish Scientia findings and the publication playbook.

Surfaces (same manifest, different entry points)

Live publish gate (all surfaces): two distinct digest-bound approvers in VoxDb, publish_armed (config and/or VOX_NEWS_PUBLISH_ARMED), no overriding dry-run on item + surface. CLI armed uses env only; MCP/orchestrator use config OR env.

If syndication.distribution_policy.dry_run is true in metadata, the runtime forces syndication.dry_run on (stricter than omitting the flag).

Config precedence (MCP publication): env vars read by PublisherConfig::from_operator_environment win over orchestrator TOML for Twitter chunk/suffix and API bases; orchestrator fills gaps only when env left those fields unset. Site URLs use [news] then VOX_NEWS_SITE_BASE_URL / VOX_NEWS_RSS_FEED_PATH. CLI publication uses contract defaults plus the same news site env overrides (no orchestrator TOML).

Rough character budgets (typed by you vs derived)

Approximate UTF-8 characters; platforms may count code points differently. “You” = manifest fields + syndication overrides; “System” = truncation/summaries from content_markdown / title.

Per-channel: typical manual burden

Scholarly submit: VOX_SCHOLARLY_ADAPTER — local_ledger (default, Codex-friendly ledger id) or echo_ledger (deterministic id, no external repo call; tests/CI). Unknown values fail fast.

Metadata keys (DB / frontmatter)

Persist syndication policy under metadata_json as syndication, not a top-level scientia_distribution key. Optional topic_pack string merges topic-pack YAML. See contracts/scientia/distribution.schema.json.

Troubleshooting FAQ — Vox ↔ AI Agents Integration

This page is for operational fixes.

If you want product or architecture answers, use the main Vox FAQ.

Common Issues & Fixes

vox-mcp connection timeout

Cause: The vox-mcp binary is missing or not in the expected path. The AI Agent reads the binary path from vox-agent.json.

Fix:

# Build the binary
cargo build -p vox-mcp

# Check it exists
ls target/debug/vox-mcp*

# Re-run doctor
vox agent doctor

If you're using a release build, make sure vox-agent.json points to target/release/vox-mcp.

vox-lsp not starting or LSP crashes

Cause: The LSP binary is not built, or it panics on startup with an invalid project.

Fix:

# Build the LSP binary
cargo build -p vox-lsp

# Run it manually to see errors
target/debug/vox-lsp --stdio 2>&1 | head -20

Check target/debug/vox-lsp.stderr.log if it exists.

Port conflict on vox dashboard

Cause: Port 8080 (default) is already in use.

Fix:

# Check what's using the port
netstat -ano | findstr :8080

# Kill the process by PID (Windows)
taskkill /PID <PID> /F

# Or launch on a different port
VOX_DASHBOARD_PORT=8090 vox dashboard

Shell completions not working

Fix: Generate and source completions for your shell:

# Bash
vox completions bash > ~/.local/share/bash-completion/completions/vox

# Zsh
vox completions zsh > ~/.zfunc/_vox

# PowerShell
vox completions powershell >> $PROFILE

vox_map_agent_session failing

Cause: The session ID is already mapped, or the agent doesn't exist.

Fix: Run vox agent status to see current session-to-agent mappings. If stale, restart the MCP server: cargo run -p vox-mcp.

Workspace compilation errors after update

Cause: A Vox AST or HIR struct gained a new required field (e.g., filter_fields).

Fix: Run cargo check --workspace and read the specific E0063 missing field errors. These are structural changes to the Vox type system and require adding the new field at the construction site.

Agent scoped to the wrong files

Cause: The scope: line in .vox/agents/<agent>.md doesn't match the edited file's path.

Fix { Run vox agent sync to regenerate agents from the current crate graph, or manually edit .vox/agents/<agent>.md to update the scope: field.

Dashboard shows no agents

Cause: The orchestrator has no active agents. Agents are only spawned when tasks are submitted.

Fix: Submit a task via an AI session or run vox orchestrator spawn to create a dev agent, then reload the dashboard.

Compiler Diagnostics & Error Codes

The Vox compiler provides structured diagnostic codes to help you (and AI agents) fix code rapidly.

E0001: Argument count mismatch

Message: Argument count mismatch: expected X arguments, found Y Cause: You called a function with the wrong number of parameters. Fix: Match the function signature. If you want optional arguments, use Option[T].

E0002: Tuple size mismatch

Message: Tuple size mismatch: expected X, found Y Cause: Attempting to destructure or assign a tuple of different lengths.

E0003: Function arity mismatch

Message: Function arity mismatch: expected X, found Y Cause: Occurs during higher-order function passing where the callback signature doesn't match the expected parameter count.

E0063: Missing record fields

Message: Missing record fields: [field_name] Cause: You instantiated a struct or table without providing all required non-Option fields. Fix: Provide the missing fields or update the type definition to use Option[T].

E0101: Immutable assignment

Message: Cannot assign to immutable variable X Cause: Attempting to mutate a variable not declared with mut. Fix: Change let x = ... to let mut x = ....

E0404: Module search failure

Message: Failed to resolve module X Cause: The imported file or crate is missing from the search path. Fix: Check your import paths and ensure the dependency is in your project or listed in vox.lock.

Further Operations

• Vox FAQ — Architectural and conceptual Q&A.
• vox doctor — Automates environment verification.
• Contributor Hub — If you've found a compiler bug.

Known Documentation Gaps & Backlog

This is a living checklist for the Vox open source community and core contributors to track undocumented or under-documented language features.

High Priority

• Add deep dive for workflow and activity compilation phases
• Document difference between query and mutation transactional boundaries natively
• Expand the Codex abstraction API reference
• List all compiler auto-injected properties for @table types (id, created_at, updated_at)

Medium Priority

• Explain the underlying generic instantiation (<T>) algorithm used by HIR logic
• Detail all mcp.tool options regarding rate limits and user confirmation schemas
• Add explicit HTTP request payload mapping examples for @server endpoints

Completed

• Standard library built-ins (completed 2026-04-06)
• Correct @island decorator syntax (completed 2026-04-06)
• Example pipeline validation documentation (completed 2026-04-06)

Crate API: vox-ast (Deprecated Name)

[!WARNING] ARCHIVED COMPONENT: This file was archived on 2026-04-13. It is intentionally excluded from active AI context. It must not be referenced for contemporary development. This crate was merged into the vox-compiler monolith. Please refer to vox-compiler.md.

Crate API: vox-codegen-rust (Deprecated Name)

[!WARNING] ARCHIVED COMPONENT: This file was archived on 2026-04-13. It is intentionally excluded from active AI context. It must not be referenced for contemporary development. This crate was merged into the vox-compiler monolith. Please refer to vox-compiler.md.

Crate API: vox-codegen-ts (Deprecated Name)

[!WARNING] ARCHIVED COMPONENT: This file was archived on 2026-04-13. It is intentionally excluded from active AI context. It must not be referenced for contemporary development. This crate was merged into the vox-compiler monolith. Please refer to vox-compiler.md.

Crate API: vox-dei-sandbox (Deprecated Name)

[!WARNING] ARCHIVED COMPONENT: This file was archived on 2026-04-13. It is intentionally excluded from active AI context. It must not be referenced for contemporary development. The vox-dei-sandbox concept was retired. Please refer to the new HITL doubt module at vox-dei.md.

Crate API: vox-gamify (Deprecated Name)

[!WARNING] ARCHIVED COMPONENT: This file was archived on 2026-04-13. It is intentionally excluded from active AI context. It must not be referenced for contemporary development. The gamification engines were merged into vox-ludus. Please refer to vox-ludus.md.

Crate API: vox-hir (Deprecated Name)

[!WARNING] ARCHIVED COMPONENT: This file was archived on 2026-04-13. It is intentionally excluded from active AI context. It must not be referenced for contemporary development. This crate was merged into the vox-compiler monolith. Please refer to vox-compiler.md.

Crate API: vox-lexer (Deprecated Name)

[!WARNING] ARCHIVED COMPONENT: This file was archived on 2026-04-13. It is intentionally excluded from active AI context. It must not be referenced for contemporary development. This crate was merged into the vox-compiler monolith. Please refer to vox-compiler.md.

Crate API: vox-mcp (Archived)

[!WARNING] ARCHIVED COMPONENT: This file was archived on 2026-04-13. It is intentionally excluded from active AI context. It must not be referenced for contemporary development. This internal MCP server crate was superseded by the split vox-mcp-meta and vox-mcp-registry crates.

Embedded MCP (vox-mcp) talks to the workspace orchestrator for chat, routing telemetry, and codegen tools. See Unified orchestration — SSOT for contract boundaries.

LLM model routing (models.toml)

Model registry and Ludus routing for MCP-backed chat and vox_generate_code are configured through the workspace model stack (including models.toml where present). Env overrides and cost telemetry hooks are documented in the orchestration SSOT and env vars SSOT.

Execution Time Budgeting

The MCP server exposes vox_exec_time_query and vox_exec_time_record to interface with the orchestrator's dynamic budgeting system, replacing static timeouts with data-driven forecasts.

HITL Doubt Integration

The vox_doubt_task tool is exposed to allow agents to formally transition their task into TaskStatus::Doubted. Params matching crate::params::DoubtTaskParams:

• task_id (string): The UUID of the task.
• reason (string): Explanation of the contextual ambiguity or missing permission.
• recommended_human_action (string): Specific guidance for the human operator to resolve the doubt.

Crate API: vox-orchestrator (Deprecated Name)

[!WARNING] ARCHIVED COMPONENT: This file was archived on 2026-04-13. It is intentionally excluded from active AI context. It must not be referenced for contemporary development. The large orchestrator crate vox-dei was renamed to vox-orchestrator. Please refer to vox-orchestrator.md.

Crate API: vox-parser (Deprecated Name)

[!WARNING] ARCHIVED COMPONENT: This file was archived on 2026-04-13. It is intentionally excluded from active AI context. It must not be referenced for contemporary development. This crate was merged into the vox-compiler monolith. Please refer to vox-compiler.md.

Crate API: vox-py (Archived)

[!WARNING] ARCHIVED COMPONENT: This file was archived on 2026-04-13. It is intentionally excluded from active AI context. It must not be referenced for contemporary development. The vox-py crate was deprecated in favor of native Rust tooling and the vox-lang compilation surface.

Crate API: vox-typeck (Deprecated Name)

[!WARNING] ARCHIVED COMPONENT: This file was archived on 2026-04-13. It is intentionally excluded from active AI context. It must not be referenced for contemporary development. This crate was merged into the vox-compiler monolith. Please refer to vox-compiler.md.

Crate API: vox-wasm (Deprecated Name)

[!WARNING] ARCHIVED COMPONENT: This file was archived on 2026-04-13. It is intentionally excluded from active AI context. It must not be referenced for contemporary development. This crate was merged into the vox-compiler monolith. Please refer to vox-compiler.md.

Golden Examples

Working code examples demonstrating Vox language features. Each .vox file is a complete, self-contained program validated by the CI pipeline. See examples/PARSE_STATUS.md for the latest parse matrix and examples/STYLE.md for contribution guidelines.

Hello World

The smallest valid Vox program: a typed function that returns a string. Demonstrates the fn keyword, explicit return type, string concatenation, and ret.

fn hello(name: str) -> str {
    ret "Hello " + name + "!"
}

CRUD API — Table, Query, Mutation, and Endpoint

A complete data layer in one file. @table generates the database schema, @query wires a read-only resolver, @mutation wires a write operation, and @get exposes an HTTP handler — all with the Rust Axum backend generated automatically.

@table type User {
    name: str
    active: bool
}

@query
fn user_count() -> int {
    ret len(db.User.all())
}

@query
fn active_user_count() -> int {
    ret len(db.User.filter({ active: true }))
}

@mutation
fn seed_user(name: str) -> Unit {
    db.User.insert({ name: name, active: true })
}

http get "/api/users" to int {
    ret len(db.User.all())
}

Counter Actor — Stateful Concurrent Actor

Actors are isolated units of concurrency. This actor holds an integer counter in its state and exposes an Increment message handler that returns the new count. Spawning the actor allocates a mailbox and an address.

actor CounterActor {
    on Increment(current: int) -> int {
        ret current + 1
    }
}

Checkout Workflow — Durable Execution with Error Handling

Workflows survive server restarts by journaling each activity result. The charge_card activity is idempotent and retryable. Pattern matching on Result makes both happy-path and error-path explicit.

activity charge_card(amount: int) -> Result[str] {
    if amount > 1000 {
        ret Error("Amount too large")
    }
    ret Ok("tx_123")
}

workflow checkout(amount: int) -> str {
    let result = charge_card(amount)
    match result {
        Ok(tx) -> "Success: " + tx
        Error(msg) -> "Failed: " + msg
    }
}

MCP Tools — AI-Callable Tool and Resource

The @mcp.tool decorator generates a Model Context Protocol tool schema from the function signature. AI agents (including Vox's built-in DEI orchestrator) can discover and call these functions without any glue code.

@mcp.tool "read_file: Reads a file from disk"
fn read_file(path: str) -> str {
    ret "file contents"
}

@mcp.tool "file_uri: Echo path as a logical file URI"
fn file_uri(path: str) -> str {
    ret "file://" + path
}

@mcp.resource("vox://golden/mcp-status", "Static status blob for golden tests")
fn mcp_golden_status() -> str {
    ret "ok"
}

Agent Pipeline — Multi-Agent Message Passing

Demonstrates an actor-based multi-agent system. TaskMessage is a structured message type. WorkerAgent receives HandleTask messages and tracks the number of processed tasks in its actor state.

type TaskMessage =
    | Msg(id: int, payload: str)

fn data_agent_ready() -> str {
    ret "Ready"
}

actor WorkerAgent {
    on HandleTask(id: int, payload: str) -> str {
        ret "Task " + str(id) + " done"
    }
}

Dashboard UI — Layout, Islands, and Routes

Full-stack UI composition. @island marks interactive components that get client-side hydration. layout wraps every route with shared chrome. routes maps URL paths to components.

type DashboardStatus =
    | Loading
    | Ready(data: str)

@island DataChart {
    data: list[int]
}

component DashboardView() {
    view: <div className="dashboard">
        <h1>"Dashboard"</h1>
        <DataChart data=[1, 2, 3] />
    </div>
}

routes {
    "/" to DashboardView
}

Type System — ADTs, Generics, and Traits

Demonstrates algebraic data types with a type parameter, trait definition, and impl block. AppResult[T] is a generic union type (Vox's alternative to exceptions). The Serializable trait requires a serialize method.

type AppResult =
    | Success(value: int)
    | Failure(err: str)

fn serialize_app_result(r: AppResult) -> str {
    match r {
        Success(val) -> "num:" + str(val)
        Failure(err) -> "err:" + err
    }
}

Test Suite — Fixtures, Mocks, and Assertions

@fixture sets up shared test data. @mock replaces external dependencies. @test declares a test function. The |> pipe operator and len built-in demonstrate Vox's functional style.

fn setup_user() -> list[str] {
    ret ["alice", "bob"]
}

fn mock_db_read() -> str {
    ret "mock_data"
}

@test
fn test_user_count() -> Unit {
    let users = setup_user()
    assert(len(users) > 0)
    let db_val = mock_db_read()
    assert(db_val is "mock_data")
}

Config and Deploy — Environment Configuration

Typed configuration blocks and named environment definitions. config generates validated config structs. environment names deployment targets with typed key-value pairs.

type DatabaseConfig =
    | DatabaseConfig(url: str, pool_size: int)

fn sample_database_url() -> str {
    ret "libsql://example.turso.io"
}

fn prod_replica_count() -> int {
    ret 3
}

fn prod_debug_enabled() -> bool {
    ret false
}

Reactive component — state, derived, effect, lifecycle

Counter demo using the current component surface: state, derived, effect, on mount, on cleanup, and a view with click handlers.

/// Reactive counter demo (current `component` surface). Uses `on mount` / `on cleanup`
/// (not bare `mount:` / `cleanup:`). See `crates/vox-compiler/tests/reactive_smoke.rs`.

component Counter(initial: int) {
    state count: int = initial

    derived double = count * 2

    derived label = "Count is " + str(count)

    effect: {
        print("count changed to " + str(count))
    }

    on mount: {
        print("Counter mounted with initial=" + str(initial))
    }

    on cleanup: {
        print("Counter unmounted")
    }

    view: (
        <div class="counter">
            <h2>"Count: {count}"</h2>
            <p>"Doubled: {double}"</p>
            <p>"Label: {label}"</p>
            <button on:click={count = count + 1}>"Increment"</button>
            <button on:click={count = count - 1}>"Decrement"</button>
            <button on:click={count = 0}>"Reset"</button>
        </div>
    )
}

std.http — get_text / post_json

Narrow host HTTP helpers on std.http (dotted path; see parser tests). Suitable for scripting and smoke tests against real endpoints.

// Narrow `std.http` wrapper demo (`get_text` / `post_json`). Requires `http` to parse as a
// dotted path segment (see `parse_ident_name` / `parse_import_path`).

fn main() {
    let ping = std.http.get_text("https://example.com")
    let payload = "{\"source\":\"vox\",\"kind\":\"health\"}"
    let posted = std.http.post_json("https://httpbin.org/post", payload)
    std.log.info("std.http wrapper demo")
    print(str(ping))
    print(str(posted))
}

Mobile handlers (std.mobile surface)

Small UI handlers using the mobile namespace pattern (onclick={fn() { … }}).

// Minimal notify demo — same handler shape as `examples/golden/mobile_camera.vox`.

import std.mobile

component App() {
    view:
        <button onclick={fn() {
            mobile.notify("Hello", "From Vox!")
        }}>"Notify Me"</button>
}

Mesh worker script (minimal main)

Bundled as /opt/vox/mesh-noop.vox in the Docker image for compose-based workers (vox run --mode script).

// Minimal script worker for mesh/compose examples (`vox run --mode script`).
fn main() -> int {
    ret 0
}

Rosetta inventory (multi-language walkthrough)

Two golden files back the Rosetta inventory explanation: core merge + @table in inventory_rosetta_core.vox, and actor / workflow / MCP / UI / capability layers in inventory_rosetta_platform.vox. Use that page for C++ / Rust / Python contrast snippets; Vox sections pull anchored regions from these files.

AI Agent Orchestration

Vox was built from the ground up to blur the lines between traditional application logic and AI agent capabilities. Rather than bolting an AI SDK onto a web framework, Vox uses the Model Context Protocol (MCP) and its internal DEI (Distributed Execution Intelligence) Orchestrator as first-class citizens.

The MCP Bridge

The Model Context Protocol establishes a standard way for AI assistants (like Claude Desktop, Cursor, or your own models) -> safely discover and interact with local data sources and tools.

Vox seamlessly generates MCP servers natively from the logic you've already written.

@mcp.tool

The @mcp.tool decorator tells the Vox compiler to expose a function to any connected LLM.

// vox:skip
@mcp.tool "Calculate the shipping cost including surge pricing"
fn calculate_shipping(weight: float, zip_code: str) -> float {
    // Logic here
}

Behind the scenes, Vox:

1. Derives the JSON Schema for the inputs (weight as a number, zip_code as a string).
2. Generates an asynchronous Rust handler.
3. Maps Vox Result types directly to MCP error structures so the LLM knows why an operation failed without you writing serialization glue.

@mcp.resource

While tools are functions the LLM can call, resources are data the LLM can read.

// vox:skip
@mcp.resource("vox://user/config", "The current user's profile configuration")
fn get_user_profile() -> str {
    return db.query("SELECT context FROM config")
}

The DEI orchestrator handles registering this URI schema. When an LLM requests vox://user/config, the orchestrator routes it directly to this function.

DEI Orchestrator

The Distributed Execution Intelligence (DEI) orchestrator (sometimes referred to as vox-dei) is the runtime engine that manages these agents and tools.

When you run vox run src/main.vox, the orchestrator spins up, discovers all your decorated tools, and starts an MCP endpoint that defaults to Stdio for desktop clients or HTTP/SSE for distributed meshes.

Agent-to-Agent (A2A) Messaging

Agents are scoped types in Vox. While the syntax is still aspirational (@agent type), the DEI orchestrator fundamentally supports Agent-to-Agent (A2A) messaging.

One agent can be granted the tools of another agent, executing what is effectively a sub-agent handoff. Because tools are just compiled Vox functions, a handoff entails an in-memory or fast-WASI call rather than a network hop to a secondary Python server.

Security Controls

Because Vox exposes functions directly to reasoning engines, security is modeled differently than traditional web frameworks. The AI is bounded by the exact strictures of the Vox language: zero-null data, strict ADT matching, and the explicit @require(condition) precondition decorators, ensuring the LLM cannot hallucinate paths to execute invalid data modifications.

Related Topics:

• Build AI Agent Tools
• The Security Model

Actors & Workflows

Vox provides two first-class concurrency primitives: Actors for lightweight message-passing and Workflows for orchestrating activities. Actor behavior is materially implemented today. Workflow durability is currently a mix of language intent, generated async code, and a separate interpreted runtime.

Actors

Actors are isolated processes with their own state and a mailbox for receiving messages. They communicate exclusively via message passing — no shared memory.

Defining an Actor

// vox:skip
actor Counter {
    let mut count: int = 0

    on increment(amount: int) -> int {
        count = count + amount;
        return count;
    }

    on get_count() -> int {
        return count;
    }

    on reset() {
        count = 0;
    }
}

Key concepts:

• state fields hold mutable internal data
• on handlers define message responses
• Each handler returns a typed result

Spawning and Messaging

// vox:skip
fn main() {
    // spawn() creates a new actor instance, returns a handle (ActorRef)
    let counter = spawn Counter();
    let greeter = spawn Greeter();

    // .send() dispatches a message to the actor's mailbox
    counter.send increment(5);
    greeter.send greet("Alice");

    // Actors can receive multiple messages
    counter.send increment(3);
    let total = await counter.get_count(); 
}

Messages

Define typed messages for inter-actor communication:

// vox:skip
type Greeting {
    from_name: str,
    text: str,
}

Durable Actors

Actors can persist state across restarts using state_load and state_save:

// vox:skip
actor PersistentCounter {
    on increment() -> int {
        let current = state_load("counter");
        let next = current + 1;
        state_save("counter", next);
        return next;
    }
}

This compiles to database-backed state management — the actor's count survives process restarts.

[!NOTE] state_load(key: str) -> T and state_save(key: str, val: T) -> Unit are compiler-injected built-ins available only inside actor blocks. They seamlessly marshal generic types directly to the persistence layer.

How Actors Compile

Activities

Activities are retryable units of work that may fail. They are the only place for side effects within workflows.

// vox:skip
activity fetch_user_data(user_id: str) -> Result[str] {
    // Would call an external API in production
    return Ok("User data for " + user_id);
}

activity send_notification(email: str, body: str) -> Result[bool] {
    // External email service call
    return Ok(true);
}

Activities must always return a Result type, since they represent operations that can fail.

Quick Comparison

Workflows

Workflows orchestrate activities with retry and journaling intent.

Current state:

• Implemented semantics: workflow syntax, with { ... } parsing/typechecking, generated async Rust functions, interpreted workflow planning/journaling, stored step-result replay, and retry/backoff for interpreted mesh_* activities.
• Planned semantics: full durable state-machine execution for the generated Rust path and richer replay models for branching/loops.
• Escape hatch / current durable path: the interpreted workflow runtime used by vox mens workflow ....

// vox:skip
workflow onboard_user(user_id: str, email: str) -> Result[str] {
    // Step 1: Fetch user profile
    let profile = fetch_user_data(user_id) with { retries: 3, timeout: "30s" };

    // Step 2: Send welcome email
    let _ = send_notification(email, "Welcome! " + profile) with { retries: 5, timeout: "60s" };

    // Step 3: Return success
    return Ok("Onboarding complete for " + user_id);
}

The with Expression

The with expression carries workflow activity options. Some are honored today in the interpreted runtime, while others only matter on specific runtime paths:

Durable Execution

The interpreted workflow runtime can skip previously completed activities when restarted with the same workflow, run id, and activity ids because it records journal/tracker data before replay and now stores step result payloads for linear replay. Generated Rust workflows do not yet compile into a durable state machine.

Durable spine (today): the supported replay/idempotency story is the interpreted vox mens workflow … runtime (see ADR-019). Rust-emitted async fn workflows are orchestration helpers only until generated code adopts the same journaling contract. Generated-workflow parity remains intentionally out of scope until Vox has a formal replay model and ADR for it (see ADR-021).

How Workflows Compile

Full Example: Order Processing

A complete workflow combining activities with different retry policies:

// vox:skip
type OrderResult {
    Ok { order_id: str }
    Error { message: str }
}

activity validate_order(order_data: str) -> Result[str] {
    let validated = "validated-" + order_data;
    return Ok(validated);
}

activity charge_payment(amount: int, card_token: str) -> Result[str] {
    let tx = "tx-" + card_token;
    return Ok(tx);
}

activity send_confirmation(recipient: str, order_id: str) -> Result[str] {
    let msg = "Order " + order_id + " confirmed for " + recipient;
    return Ok(msg);
}

workflow process_order(customer: str, order_data: str, amount: int) -> Result[str] {
    // Validate with a short timeout and no retries
    let validated = validate_order(order_data) with { timeout: "5s" };

    // Charge payment with retries and backoff
    let payment = charge_payment(amount, "card-123") 
        with { retries: 3, timeout: "30s", initial_backoff: "500ms" };

    // Send confirmation with basic retry
    let confirmation = send_confirmation(customer, "order-001") 
        with { retries: 2, activity_id: "confirm-order-001" };

    return confirmation;
}

Next Steps

• Language Reference — Full syntax and type system reference
• Compiler Architecture — How actors and workflows compile

Durability Taxonomy

Understanding the types of durability is crucial when reasoning about failure recovery in Vox:

1. Persistent Actors (state_load / state_save): State survives restarts because the logic explicitly reads from and writes to the Codex under specific keys. When the actor respawns, it resumes with the last saved state.
2. Workflow Durability (Interpreted Runtime): When running via vox run or vox mens workflow, the engine tracks execution steps natively in the database. If the process dies and restarts, completed activities are short-circuited.
3. Compiled Rust Workflows (Future Parity): Workflows that are compiled strictly down to standard Rust async equivalents do not automatically benefit from step-level replayable durability yet. This remains an active implementation target for parity with the interpreted path (see ADR-021).

Compiler Architecture

The Vox compiler follows a modular pipeline architecture with conceptual stages. The current implementation is consolidated under crates/vox-compiler/src/, where each stage is represented by explicit modules.

Current implementation note: the practical pipeline is currently consolidated under crates/vox-compiler/src/ for lexer, parser, AST, HIR, typecheck, and emitters. This document keeps conceptual stage boundaries while implementation modules may live in one crate.

Pipeline Overview

Source Code (.vox)
    │
    ▼
┌────────────────┐
│     Lexer      │  Tokenization (logos)
└──────┬─────────┘
       │ Vec<Token>
       ▼
┌────────────────┐
│     Parser     │  Recursive descent parser → AST Module
└──────┬─────────┘
       │ Module (AST root)
       ▼
┌────────────────┐
│      AST       │  Strongly-typed AST wrappers
└──────┬─────────┘
       │ Module (Decl, Expr, Stmt, Pattern)
       ▼
┌────────────────┐
│      HIR       │  Desugaring + name resolution + dead code detection
└──────┬─────────┘
       │ HirModule
       ▼
┌────────────────┐
│    Typeck      │  Bidirectional type checking + HM inference
└──────┬─────────┘
       │ Typed HIR + Vec<Diagnostic>
       ▼
┌────────────────┐
│     Web IR     │  HIR→WebIR lower + validate
└──────┬─────────┘
       │ WebIrModule
       ▼
┌────────────────┐
│  App Contract  │  HIR→AppContract (HTTP/RPC/islands/server config)
└──────┬─────────┘
       │ AppContractModule
       ▼
┌────────────────┐
│ Runtime Proj   │  HIR→RuntimeProjection (DB/task capability hints)
└──────┬─────────┘
       │ RuntimeProjectionModule
       ▼
┌──────────────────┬─────────────────────┐
│ vox-codegen-rust │  vox-codegen-ts     │
│  (quote! → .rs)  │  (string → .ts/tsx) │
└──────────────────┴─────────────────────┘

Current path note:

• codegen_ts is still the production TS emitter path.
• VOX_WEBIR_VALIDATE defaults on (WebIR lower/validate gate); set =0 / false / no / off to skip.
• app_contract::project_app_contract is the SSOT for route/RPC/island/server-config codegen inputs.
• runtime_projection::project_runtime_from_hir is the SSOT for orchestration-facing DB capability projection.
• VOX_WEBIR_EMIT_REACTIVE_VIEWS defaults on so reactive view: can use the Web IR TSX bridge when parity checks pass; set =0 / false / no / off for legacy emit_hir_expr views only.

ML Training Pipeline

Vox has a native ML training loop powered by Burn (a pure-Rust deep learning framework):

docs/src/*.md + examples/*.vox
    │
    ▼
vox mens corpus extract   # produces validated.jsonl
    │
    ▼
vox mens corpus pairs     # produces train.jsonl (instruction-response pairs)
    │
    ▼
vox mens train            # native Burn / HF path (default CLI features)
    │
    ▼
mens/runs/v1/model_final.bin

The training loop is defined in crates/vox-cli/src/training/native.rs.

Stage Details

1. Lexer (vox-compiler::lexer)

Purpose: Converts source text into a flat stream of tokens.

Implementation: Uses the logos crate for high-performance, zero-copy tokenization.

Output: Vec<Token> — each token carries its kind and span.

2. Parser (vox-compiler::parser)

Purpose: Transforms a token stream into an AST module.

Implementation: A hand-written recursive descent parser producing ast::decl::Module. The parser is resilient to errors, meaning it continues parsing after encountering invalid syntax — this is critical for LSP support, where the user is actively typing.

Key features:

• Error recovery with synchronization points
• Trailing comma support in parameter lists
• Duplicate parameter name detection
• Indentation-aware formatting (indent.rs)

See crates/vox-compiler/src/parser/descent/mod.rs for the implementation entrypoint.

Output: Module (AST root) with source spans on declarations and expressions.

3. AST (vox-compiler::ast)

Purpose: Strongly-typed wrappers around the untyped CST nodes.

See crates/vox-compiler/src/ast/ for the node hierarchy.

6. Code Generation

Rust Codegen (vox-compiler::codegen_rust)

Emits Rust source using the quote! macro. Each decorator maps to specific Rust constructs:

TypeScript Codegen (vox-compiler::codegen_ts)

Emits TypeScript/TSX in modular files:

Normative strategy for reducing frontend emitter complexity while preserving React interop: ADR 012 — Internal web IR strategy. Detailed implementation sequencing and weighted task quotas: Internal Web IR implementation blueprint. Ordered file-by-file execution map: WebIR operations catalog. Canonical current-vs-target representation mapping: Internal Web IR side-by-side schema. Quantified K-complexity delta for the canonical worked app: WebIR K-complexity quantification. Reproducible per-token-class computation: WebIR K-metric appendix.

Supporting Crates

Adding a Language Feature

The full checklist for adding a new language construct:

1. Lexer — Add tokens to crates/vox-compiler/src/lexer/token.rs
2. Parser — Add grammar rules in crates/vox-compiler/src/parser/descent/
3. AST — Add node types in crates/vox-compiler/src/ast/
4. HIR — Map AST → HIR in crates/vox-compiler/src/hir/lower/
5. Type Check — Add inference rules in crates/vox-compiler/src/typeck/
6. WebIR — Add/update lowering + validation semantics in crates/vox-compiler/src/web_ir/ when the feature affects web-facing behavior
7. Codegen — Emit code in both crates/vox-compiler/src/codegen_rust/ and crates/vox-compiler/src/codegen_ts/
8. Test — Add integration coverage in vox-integration-tests/tests/ and WebIR/parity coverage where applicable
9. Docs — Add frontmatter + code example in docs/src/
10. Training — Run vox mens corpus extract to include the new construct in ML data

Next Steps

• Language Reference — Full syntax and feature reference
• Actors & Workflows — Workflow durability and actor persistence
• Ecosystem & Tooling — CLI commands, package manager, LSP
• Web IR operations catalog — numbered compiler/emitter tasks OP-0001–OP-0320 + supplemental OP-S049–OP-S220 batch map
• Web IR acceptance gates G1–G6 — parser, K-metric, parity, and rollout thresholds

Explanation: Capability-Gated Execution

Vox introduces a "Capability-Gated" mechanism inside its runtime. Because Vox orchestrates dynamic AI agent routines, the security model must assume that non-deterministic paths may attempt to invoke sensitive operations.

The Execution Sandbox

When an Agent evaluates code, or when the orchestrator mounts an untrusted plugin process, it runs within a restrictive sandbox.

Network Constraints

By default, the global HTTP policy (controlled via vox-reqwest-defaults) denies all outbound connections triggered dynamically inside a sandboxed evaluation context unless explicit hostnames have been whitelisted within the project manifest.

Filesystem Constraints

std.fs targets are strictly bounded to the workspace's %TEMP% alias and sandboxed virtual roots. If an LLM-invoked execution attempts:

// vox:skip
std.fs.read("/etc/passwd")?

The runtime immediately terminates the WASI execution step with a Capability Violation.

Database Constraints

All generated data abstractions via Codex are strongly typed. Agents cannot arbitrarily generate direct db.query("DROP TABLE Users") SQL statements because the db.query raw escape hatch is inherently hidden from the exposed @mcp.tool capability domain by default.

Upgrading Capabilities

If you require an Agent or task to legitimately reach the outside network or modify sensitive tables, you establish explicit boundary @mcp.tool functions that validate inputs using @require and encapsulate the permissioned operation securely.

// vox:skip
@mcp.tool "Upload telemetry data to approved vendor"
@require(auth.is_trusted(caller))
fn upload_telemetry(data: str) -> Result[Unit] {
    // This runs in the Trusted context
    let res = std.http.post_json("https://trusted-vendor.com/ingest", data)?
    return Ok(())
}

Related Content:

• Explanation: Security Model
• How-To: System IO

Explanation: Compiler Lowering Phases

Understand how the Vox compiler transforms high-level source code into optimized Rust and TypeScript output.

Implementation note: current production code keeps these stages under crates/vox-compiler/src/ with explicit modules for parser, HIR lowering, typecheck, and dual-target emitters.

1. Syntax to AST (Abstract Syntax Tree)

The parser converts the raw .vox file into a tree of declarations. This phase ensures the code is syntactically valid but does not yet understand types or decorators.

2. AST to HIR (High-level Intermediate Representation)

The Lowering phase begins by transforming the AST into the HIR.

• Symbol Resolution: Linking variable names to their definitions.
• Decorator Processing: Expanding decorators like @server into their underlying architectural primitives (handlers, endpoints, clients).
• Type Inference: Deducing types for all expressions.

3. HIR to WebIR and LIR (Low-level intermediate layers)

ADR 012 introduces WebIR (crates/vox-compiler/src/web_ir/) as the normative structured layer before React/TanStack printers. lower_hir_to_web_ir lowers reactive view: JSX (plus routes { contracts and behavior summaries) into WebIrModule; validate_web_ir checks DOM id references; emit_component_view_tsx is a JSX string preview used for parity tests.

Current production behavior (important for migration planning):

• codegen_ts still assembles production TS/TSX output on the primary path.
• VOX_WEBIR_VALIDATE=1 runs WebIR lower/validate as a fail-fast gate.
• VOX_WEBIR_EMIT_REACTIVE_VIEWS=1 enables reactive view: bridge output via WebIR preview emit only when parity checks pass.
• The two flags are related but not equivalent; validation can be enabled without switching reactive view emission.

Operations catalog + gates: WebIR operations catalog and acceptance gates G1–G6 (includes supplemental OP-S049–OP-S220 rustc/doc gates). Roadmap link pass A (OP-S130, OP-S131, OP-S209–OP-S211): keep lowering docs aligned when renaming validation stages.

Separately, backend-oriented lowering remains optimized for Rust emission (database, actors, HTTP). The older “Frontend LIR” label maps to this split: WebIR for structured web UI, HIR emitters for expedient TS until the printer fully migrates.

3b. HIR to AppContract and RuntimeProjection (contract layers)

Two additional HIR-derived contract layers are authoritative for non-UI emitters and orchestration:

• app_contract::project_app_contract produces AppContractModule (HTTP routes, server/query/mutation functions, client routes, islands, server config).
• runtime_projection::project_runtime_from_hir produces RuntimeProjectionModule (DB planning policy snapshots and inferred task capability hints).

These projections are generated from the same lowered HIR input as WebIR and are validated in parity tests to prevent split semantic ownership.

4. Code Generation (Emission)

The final phase where lowered IR is converted into source files:

• vox-compiler::codegen_rust: Produces generated Rust app files (src/main.rs, src/lib.rs, API client output, and DB scaffolding).
• vox-compiler::codegen_ts: Produces TS/TSX output (App.tsx/route trees, server-fn wrappers, component files, and generated contracts).

For frontend IR layering and migration phases, see ADR 012 — Internal web IR strategy. For detailed implementation sequencing, see Internal Web IR implementation blueprint. For ordered file-by-file migration operations, see WebIR operations catalog. For exact current-vs-target representation mapping, see Internal Web IR side-by-side schema. For quantified token+grammar+escape-hatch savings on the canonical app, see WebIR K-complexity quantification. For reproducible counting registries and equation trace, see WebIR K-metric appendix.

5. Why Lowering Matters?

By having multiple intermediate representations, Vox can perform complex architectural optimizations—like automatically grouping database queries or optimizing actor communication—that would be impossible in a single-pass compiler.

Related Reference:

• Architecture Index — High-level map of the current compiler module layout.
• API Reference: vox-hir (Archived) — Details on the HIR data structures.

Explanation: Durable Execution

Understand the current durability boundary in Vox. Today, durable execution is a workflow feature of the interpreted runtime used by vox mens workflow ..., not a blanket guarantee for every compiled Vox program.

[!NOTE] Interpreted Durability vs Compiled Async: The durable path today specifically relies on the interpreted vox mens workflow runner to track execution steps in the journal. Workflows compiled to Rust under standard operation (vox build) currently execute as standard async fn constructs without the automatic state machine generation built in.

1. The Journal System

In the interpreted workflow runtime, Vox records workflow progress as activity steps complete. The durable truth today is step-oriented: the runtime tracks which activity_id values have already completed for a workflow run and stores the completed step result payload so it can replay that result after a restart.

graph TD
    A[Start Workflow] --> B{Activity Finished?}
    B -- No --> C[Execute Activity]
    C --> D[Write to Journal]
    D --> B
    B -- Yes --> E[End Workflow]

2. Recovery via Replay

If the interpreted runtime crashes mid-workflow, recovery currently works like this:

1. Restart the workflow runner with the same workflow, durable run_id, and stable activity ids.
2. Read durable workflow tracking data from Codex / VoxDb.
3. Load stored results for activities that were already recorded as completed for that run.
4. Continue with the remaining steps.

This is narrower than a full workflow virtual machine. Generated Rust workflows do not yet replay arbitrary local variables, control-flow decisions, or stack state as a durable state machine.

3. Exactly-Once Semantics

Treat the current model as durable step deduplication, not a universal exactly-once guarantee.

• If an activity step was already recorded as completed for the same run, the interpreted runtime can skip it on resume.
• For linear interpreted workflows, the runtime can also replay the stored step result payload into the new journal stream.
• External side effects are only safe when the activity itself is idempotent, meaning it can tolerate retries without corrupting state.
• If you need a stronger guarantee, design the activity to accept an explicit idempotency key such as activity_id.

4. Determinism Requirements

For replay to work, the workflow body should stay deterministic.

• BAD: let d = Date.now() (Time changes on replay)
• GOOD: let d = get_current_time() (Wrap non-deterministic calls in an @activity)

5. Storage Backend

The current durable workflow tracking path uses Codex / VoxDb tables such as workflow_activity_log and workflow_run_log. These tables store durable run identity, step completion status, replayable result payloads, and run lifecycle state for the interpreted workflow path, including single-owner run lease fields used to avoid split-brain execution on the same run_id.

Older docs referenced _vox_journal, sqlite_vox_journal, PostgreSQL, or DynamoDB; treat those as stale unless a newer implementation page says otherwise.

6. Journal Contract (v1)

The interpreted workflow journal now carries journal_version: 1 on event objects emitted by the workflow runtime.

Current event families:

• Lifecycle: WorkflowStarted, WorkflowCompleted
• Step execution: ActivityStarted, ActivityCompleted
• Step replay: ActivityReplayed, followed by the stored step payload
• Retry support: ActivityAttemptRecovered, ActivityAttemptFailed, ActivityRetryScheduled
• Step payloads: LocalActivity, MeshActivity, MeshActivitySkipped
• Legacy fallback: ActivitySkipped when a step is marked complete but no replayable result payload is available

The current SSOT for this contract is the interpreted workflow runtime in:

• crates/vox-workflow-runtime/src/workflow/run.rs
• crates/vox-db/src/facade/workflow.rs
• crates/vox-db/src/workflow_journal.rs
• contracts/workflow/workflow-journal.v1.schema.json
• docs/src/adr/019-durable-workflow-journal-contract-v1.md
• docs/src/adr/021-generated-workflow-durability-parity.md

Codex append for interpreted workflow journals is enabled by default when DB config resolves and can be disabled with VOX_WORKFLOW_JOURNAL_CODEX_OFF=1.

7. Durability Taxonomy

Use these terms distinctly:

• Durable execution: workflow step replay in the interpreted workflow runtime
• Durable state: actor persistence through state_load / state_save
• Durable delivery: inbox/outbox, queue, and lease/ack message semantics
• Durable jobs: background workers or scheduled work surviving restarts
• Durable history / audit: oplogs, lineage, and analytics journals

This keeps Vox from accidentally using one word for several different guarantees.

8. Current Scope

• Supported durable path today: interpreted workflows run through vox mens workflow ...
• Supported today: stored step-result replay for linear interpreted workflows, deterministic if branch decision recording for literal-expression conditions, durable workflow_wait(<duration>) timer replay, durable workflow_wait_signal(\"key\") signal gating, cancellation-state enforcement for cancelled runs, and retry/backoff for interpreted mesh_* activity execution
• Partially implemented: workflow syntax, generated Rust lowering, and broader orchestration semantics
• Not yet true: durable execution for arbitrary compiled Vox programs or generated Rust workflow state machines
• Deferred on purpose: generated-workflow parity, arbitrary-process replay, and general branching/loop replay until Vox has a formal replay model and ADR for those features

Related Reference:

• Workflow Tutorial — Build your first durable process.
• Actors & Workflows — Current implementation boundary and supported workflow semantics.
• Vox Language Reference — Syntax for workflows and activities.

Explanation: Security Model

Vox brings security out of middleware and directly into the language syntax. By enforcing permissions at compile-time and strictly managing secrets from the environment, the language reduces the attack surface for both human-written and AI-authored code.

1. Clavis for Secret Management

Vox completely rejects decentralized environment variable reading throughout the codebase. You cannot use std.env.get("STRIPE_KEY") deep inside business logic.

Instead, all secrets must be declared and managed through Clavis, Vox's centralized secret manager.

To verify a project's secret posture, you run:

vox clavis doctor

This utility checks the system environment against the SecretSpec definition to ensure every required API key, database token, and provider credential is comprehensively mapped and secure, guaranteeing no missing configurations at deploy time.

2. The @require Precondition

Input validation is not an afterthought; it is a structural precondition. The @require decorator evaluates expressions before the function or type instantiation occurs.

// vox:skip
@mcp.tool "Delete user data"
@require(auth.is_admin(caller))
@mutation fn delete_data(id: Id[User]) -> Result[Unit] {
    db.User.delete(id)
    return Ok(())
}

If an LLM or user invokes a function that violates a @require check, the runtime traps the execution at the capability boundary and immediately returns an error. The unauthorized logic never executes.

3. Capability-Gated Execution

Many operations in Vox execute within a Capability-Gated System. A function annotated with the aspirational @task or invoked by an LLM via the DEI orchestrator cannot just read arbitrary files or open random sockets.

Capabilities (network, filesystem, state mutation) are granted down the call graph. If a network call uses the default std.http.post, it runs against the global outbound HTTP policies.

4. WASI/Sandbox Execution Boundaries

Vox code is sandboxed by default in its compiled representation.

• Isolates over Threads: Rather than exposing raw OS thread primitives, Vox utilizes an actor model compiled down to Tokio mpsc channels or isolated WASM/WASI modules (depending on the target).
• No Shared State: Execution memory is walled off. Malicious code attempting to manipulate memory pointers is thwarted by the target compiler (Rust) rejecting the unsafe actions.

5. Type and Memory Safety

The core type system intrinsically blocks entire classes of errors:

• No Nulls: The compiler's absolute enforcement of Option[T] and explicit Result[T, E] exhaustiveness eliminates unhandled crashes.
• SQL Injection Prevention: All db.* accessors use strictly verified parameterized queries generated directly by the compiler.
• XSS Protection: React Islands hydrate with standard cross-site scripting encodings intact, avoiding raw HTML injection from LLM output.

Related Topics:

• Reference: Decorators
• Explanation: The Runtime

Explanation: The Vox Runtime

Understand the inner workings of the Vox runtime—the engine that powers AI-native, stateful applications.

Implementation map

The runtime-facing story in today’s codebase is split across:

• crates/vox-runtime/src/lib.rs: actor/process/runtime primitives and exported runtime modules.
• crates/vox-runtime/src/builtins.rs: standard builtin implementations used by generated Rust code.
• crates/vox-compiler/src/codegen_rust/emit/http.rs: generated Axum app host for routes/server/query/mutation handlers.
• crates/vox-compiler/src/app_contract.rs: app-surface contract projection used to keep route/RPC/server config mapping centralized.

1. Actor-Based Concurrency and Tokio

At its core, Vox is an actor-based system. Unlike traditional shared-memory concurrency (threads + locks), Vox processes communicate via message passing.

• Isolation: Each actor has its own private state.
• Mailbox: Messages are queued and processed sequentially, eliminating race conditions by design.
• Tokio Foundation: The Vox runtime is built natively on top of the Tokio async runtime, allowing it to take full advantage of Rust's modern asynchronous ecosystem for IO and task scheduling.

2. Process Registry and Channels

When Vox code spans actors and sends messages, the compiler lowers these operations to specific Rust primitives:

• Processes: Vox actors compile to Tokio tasks running independently.
• ProcessRegistry: The runtime tracks running actors using a ProcessRegistry, which associates a typed ProcessHandle with the underlying Tokio task.
• mpsc Channels: Actor mailboxes are implemented using bounded mpsc::channel structures. Backpressure is naturally handled by the channel bounds.
• Replies: When an actor expects a return value (like .send()), an inner oneshot channel is used to cleanly route the response back to the caller.

3. Technical Unification

Vox achieves "Technical Unification" by abstracting the boundary between frontend and backend.

• RPC-as-Function: Calling a @server fn from an @island looks like a local function call but is actually a type-safe API call generated into the UI layer.
• State Synchronization: Backend state updates interact directly with the client code through standard HTTP routes built on top of Axum, managed under the hood by the compiler's output.

4. Workflows and Journaling

While actors handle live state and passing messages, Workflows provide durability for orchestration tasks. The runtime provides a secondary interpreted path for vox mens workflow ... executions that allows for persistent step journaling. In standard compiled operation, workflows act as normal async functions coordinating Result-returning activities.

Related Reference:

• Actors & Workflows Explanation — Dive deeper into the runtime behavior of actors and workflows.
• Language Reference — The core syntax for actors and state.

Glossary: Vox Terminology

Actor

A stateful, autonomous unit of computation that communicates via asynchronous messages. In Vox, actors can persist state across restarts using state_load and state_save.

// vox:skip
actor Counter {
    on inc(amount: int) -> int { return 1 }
}

ADT (Algebraic Data Type)

A composite type formed by combining other types. In Vox, this primarily refers to Structs (product types) and Enums (sum types/tagged unions).

// vox:skip
type Status = | Pending | Active(user: str)

AI-Native

A design philosophy where the programming language and toolchain are built to be consumed and generated by LLMs, emphasizing compiler-enforced constraints to eliminate hallucinations.

Arca

The low-level SQL database abstraction and migration layer in the Vox runtime.

Codex

The unified data and knowledge store in Vox (the logical database environment), acting as a high-level facade over Arca (the physical SQLite/Turso layer).

DEI (Distributed Execution Intelligence)

The Vox orchestrator responsible for task dispatch, agent lifecycle management, file affinity, and runtime telemetry.

Durable Execution

The ability of a program (specifically a Workflow) -> persist its state and progress so that it can resume exactly where it left off after an interruption or crash using an interpreted journal.

HIR (High-level Intermediate Representation)

The semantic representation of Vox source code used for type checking and initial lowering phases.

Island

A reactive UI component (compiled to React) that can be embedded in a server-rendered page. Defined using the @island decorator.

// vox:skip
@island UserProfile { user: str }

MCP (Model Context Protocol)

An open standard that enables AI models to safely interact with local data and tools. Vox provides first-class support for exporting functions as MCP tools via @mcp.tool.

// vox:skip
@mcp.tool "Search KB"
fn search_kb(topic: str) -> str { return "ok" }

Mens

Pronounced: 'mens' (Latin for mind) The Vox fine-tuning lane, training pipeline for local model generation, and interpreted workflow runtime layer.

Populi

The Vox control plane and peer-to-peer mesh for distributed execution, serving inferences, and GPU resource orchestration.

SCIENTIA

Pronounced: 'shee-en-tee-ah' (Latin for knowledge) The research and evidence-gathering framework within the Vox ecosystem for validating AI performance and language ergonomics.

TOESTUB

The architectural quality enforcement system in Vox that prevents "skeleton code" (unimplemented stubs or empty bodies) from leaking into production pipelines and tracks architectural debt.

Unit

The empty type, equivalent to void in C/TS or () in Rust.

Workflow

A durable, long-running process defined with the bare workflow keyword, supporting orchestrated activities, retries, timeouts, and state persistence.

// vox:skip
workflow onboard(user: str) -> Result[bool] { return Ok(true) }

Native ML Training Pipeline

Vox "dogfoods" itself: the language, compiler, and documentation all feed a native machine learning loop that trains the Mens code assistant model.

End-to-end map from .vox sources through goldens and corpus extraction to model inputs: Vox source → Mens pipeline SSOT. Training pair contract: Mens training data contract.

Canonical operator fine-tuning: vox mens train with Candle + qlora-rs on Hugging Face weights. --backend qlora and --tokenizer hf are the defaults; no Python training loop. SSOT: Mens native training. PopuliTrainBackend::BurnLora is rejected at runtime in this dispatch — the supported trainer is CandleQlora.

Legacy / side paths: A Burn + wgpu scratch LoRA stack still lives in vox-tensor (vox training native, small VoxTokenizer model) — no Python, optional CUDA only if you build GPU features for other subsystems. Use it for experimentation, not as a substitute for Mens HF QLoRA. Burn also matters for vox mens merge-weights and vox mens serve on merged .bin checkpoints. Objectives and artifacts differ from Candle QLoRA — see Burn vs QLoRA.

GPUs: For QLoRA on an NVIDIA workstation, build mens-candle-cuda and use vox mens train --device cuda. For Burn scratch training, wgpu (Vulkan / DX12 / Metal) is the default GPU path. Use CPU when drivers or CI forbid GPU.

Architecture

┌─────────────────────────────────────────────────────────────┐
│  DATA SOURCES                                               │
│  golden/**/*.vox + examples.ssot.v1.yaml ──┐                │
│  docs … golden .vox ───┤──► vox mens corpus extract         │
│    (+ prose per mix policy)│         │                      │
│  vox-cli generate-data ───┘         │                       │
└─────────────────────────────────────│───────────────────────┘
                                      ▼
┌─────────────────────────────────────────────────────────────┐
│  CORPUS PIPELINE                                            │
│  mens/data/validated.jsonl   (raw Vox → instruction pairs)│
│        │                                                    │
│        ▼                                                    │
│  vox mens corpus validate    (filter malformed pairs)     │
│        │                                                    │
│        ▼                                                    │
│  mens/data/train.jsonl       (rated + filtered pairs)     │
└─────────────────────────────────────│───────────────────────┘
                                      ▼
┌─────────────────────────────────────────────────────────────┐
│  TRAINING (Mens — canonical)                                │
│                                                             │
│  **`vox mens train`** — Candle + **qlora-rs** QLoRA (default) │
│  `--backend qlora` + `--tokenizer hf` + HF safetensors      │
│  Optional **CUDA** (`mens-candle-cuda`) / **Metal**          │
│  SSOT: `reference/mens-training.md`                         │
│                                                             │
│  Legacy / other: `vox training native` — Burn scratch LoRA  │
│  (`VoxTokenizer` JSONL, wgpu/CPU). Not `vox mens` dispatch.   │
│  `vox train` (mens-dei): local bails → `vox mens train …`   │
└─────────────────────────────────────────────────────────────┘
                                      ▼
┌─────────────────────────────────────────────────────────────┐
│  EVAL + BENCHMARK GATES                                     │
│  vox mens corpus eval … → eval_results.json               │
│  VOX_BENCHMARK=1 → spawns vox mens eval-local (held-out)  │
│  Targets: vox_parse_rate ≥70%, coverage ≥50% (CI); VOX_EVAL_STRICT=1 fails promotion │
│  Held-out: VOX_BENCHMARK=1, VOX_BENCHMARK_MIN_PASS_RATE (default 0) │
└─────────────────────────────────────────────────────────────┘

Data Schema

All training pairs follow this JSONL schema (must match across all tools):

{
  "prompt": "Write a minimal Vox program that prints hello",
  "response": "fn main() {\n    print(\"hello\")\n}\n",
  "category": "function",
  "rating": 5,
  "schema_version": "vox_dogfood_v1"
}

Tokenizer (training vs compile)

Compile path: source text is lexed by vox-compiler (logos Token enum)—this is unrelated to Mens model vocabulary. See Vox source → Mens pipeline SSOT.

Mens QLoRA path (default): supervised strings are tokenized with the Hugging Face tokenizer for the chosen --model (tens of thousands of BPE tokens). See Mens native training § Tokenization SSOT.

Lab / Burn scratch: vox-tensor exposes a deterministic small VoxTokenizer (not a mirror of the Vox lexer keyword set):

• 95 printable ASCII characters (IDs 3-97)
• 35 Vox compound tokens (workflow, actor, fn , @island, etc.)
• 3 control tokens: [PAD]=0, [UNK]=1, [EOS]=2
• Total vocab: 133 tokens

// vox:skip
// Vox example — tokenized natively using VoxTokenizer
fn greet(name: str) -> str {
    return "Hello, " + name
}

Encoding uses greedy longest-match on compound tokens before falling back to single chars.

VoxTransformer Architecture (Burn scratch path)

The Burn-backed scratch transformer (crates/vox-tensor/src/vox_nn.rs, gpu feature) used with VoxTokenizer JSONL — distinct from HF QLoRA weights:

Running the Pipeline

1. Generate synthetic training data

vox generate-data --limit 500 --output mens/data/train.jsonl

2. Extract corpus from real Vox files (canonical flow, PowerShell)

.\target\release\vox.exe mens corpus extract examples/golden/ -o mens/data/validated.jsonl
.\target\release\vox.exe mens corpus extract docs/ -o mens/data/validated.jsonl 2>$null
.\target\release\vox.exe mens corpus validate mens/data/validated.jsonl --no-recheck -o mens/data/validated.jsonl
.\target\release\vox.exe mens corpus pairs mens/data/validated.jsonl -o target/dogfood/train.jsonl --docs docs/src/ --docs docs/src/research/ --docs docs/src/adr/
# Rustdoc merge skipped: response is Rust prose, not Vox code

3. Start Mens fine-tuning (canonical — Candle QLoRA, native Rust)

# Build with CUDA for RTX-class GPUs (see mens-training SSOT / AGENTS.md)
# Then minimal path:
.\target\release\vox.exe mens train --device cuda --data-dir target/dogfood --output-dir target/dogfood/run

Legacy Burn scratch (small VoxTokenizer model, wgpu — not HF QLoRA):

$env:VOX_BACKEND="cpu"; .\target\release\vox.exe train --data-dir target/dogfood --output-dir mens/runs/v1
# GPU: omit VOX_BACKEND=cpu when wgpu is available

4. Check eval gate

.\target\release\vox.exe mens corpus eval target/dogfood/train.jsonl -o mens/runs/v1/eval_results.json

Documentation → Training Pair Loop

Every documentation page with training_eligible: true in its frontmatter and a ```vox code block automatically contributes training pairs via vox mens corpus pairs --docs docs/src/.

This creates a closed feedback loop: better docs → more training data → better model → better completions → easier to write docs.

Frontmatter format for training-eligible docs:

---
title: "My Guide"
category: how-to
constructs: [function, workflow]
training_eligible: true
difficulty: intermediate
---

CI Integration

The ML pipeline runs automatically via .github/workflows/ml_data_extraction.yml:

• Nightly: Full corpus re-extraction at 4 AM UTC
• On push: Triggered when *.vox, compiler crates, or docs/src/** change
• Manual: workflow_dispatch with force_train or native_train option
• Grammar drift: Fingerprint check forces full re-extraction when syntax changes

CI training job (GPU runner)

The train job runs on a self-hosted GPU runner when corpus changes or when manually triggered:

• Native path (default): Prefer vox mens train with VOX_BACKEND=cpu for CI compatibility. Older workflows may still invoke vox train; --provider local now bails with the canonical Candle QLoRA command (no Python train_qlora script).
• Workflow_dispatch native_train: false: If still wired to vox train --provider local, expect the bail message directing operators to vox mens train --backend qlora. Use vox mens train directly in updated automation.
• Eval strict mode: VOX_EVAL_STRICT=1 — training fails when eval gate thresholds are not met.
• Benchmark gate: VOX_BENCHMARK=1 — runs held-out benchmark from mens/data/heldout_bench/; VOX_BENCHMARK_MIN_PASS_RATE (e.g. 0.80) fails promotion when pass rate is below threshold.
• Artifact retention: LoRA adapter target/dogfood/run/ uploaded as lora-adapter-$VCS_SHA, retained 90 days. Eval results eval_results.json / eval_gate_failed.json retained 30 days.
• Logging: Training pair count and eval gate result (parse rate, coverage) are printed; eval gate failure writes eval_gate_failed.json and emits a warning.

Runbook: Native training in CI

# CI uses VOX_BACKEND=cpu by default (no GPU drivers required)
VOX_BACKEND=cpu vox mens train --data-dir target/dogfood --output-dir target/dogfood/run

Runbook: Evol-Instruct (optional, gated)

Not wired on the current slim vox binary. Use external tooling or scripts until a corpus evol subcommand lands.

# Intended future shape (not implemented):
# EVOL_GATE=1 vox mens corpus evol …

Runbook: Optional extra corpus merge

Use vox mens corpus mix with mens/config/mix.yaml, or merge JSONL with your own tooling. There is no vox corpus merge subcommand today.

Train matrix (canonical)

Artifact layout: target/dogfood/train.jsonl (canonical input), target/dogfood/run/ (output). Version naming: lora-adapter-$VCS_SHA, eval-gate-$VCS_SHA.

Next Steps

• ADR 003 — Native training over Python — History vs current Candle QLoRA
• ADR 006 — Mens full-graph Candle QLoRA
• Mens native training SSOT
• Actors & Workflows — Build durable constructs for the training pipeline
• CLI Reference — vox mens, vox train
• Architecture Overview — How the compiler pipeline works

OpenClaw Competitive Analysis

Canonical definition (Vox docs): OpenClaw is an open-source TypeScript agent platform—a self-hosted gateway connecting chat platforms to LLMs with local tool access. ClawHub denotes its public skills marketplace (community skill bundles and discovery). Vox does not ship OpenClaw; integration is via vox openclaw (CLI, feature ars) and vox_skills::OpenClawClient. The short glossary entry cross-links here as SSOT.

Status: Research document — Feb 2026

Compares the OpenClaw platform with Vox's agentic infrastructure to identify adoption opportunities and improvement areas.

What is OpenClaw?

OpenClaw is an open-source autonomous AI agent platform (large public GitHub footprint) by Peter Steinberger, built in TypeScript. It is often described as a self-hosted "operating system for AI agents" — a hub-and-spoke gateway connecting chat platforms (WhatsApp, Telegram, Discord, Slack, iMessage) -> LLMs (Claude, GPT, Gemini, local models) with full local tool access (shell, browser, files).

Architectural Comparison

What Vox Does Better

1. Multi-Agent Orchestration

Purpose-built orchestrator with 25+ modules: file-affinity routing, scope guards, file locks, budget management, heartbeat monitoring, continuation engine. OpenClaw is single-agent.

2. Agent-to-Agent Communication

A2A MessageBus: typed messages (PlanHandoff, ContextShare, TaskAssignment, StatusUpdate, CompletionNotice, ErrorReport), unicast/broadcast/multicast, per-agent inboxes, audit trail.

3. Structured Database

VoxDb wraps CodeStore with 25+ typed entry kinds, multi-backend (local SQLite, Turso cloud, embedded replica), transactions, retry logic.

4. Gamification Layer

Achievements, companions with moods, daily quests, bug battles, leaderboards, cost tracking, ASCII sprites — all in MCP response envelopes.

5. Language-Native MCP

@mcp.tool decorator compiles directly to MCP tool definitions from syntax. No glue code.

6. Actor-Based Runtime

Process spawning, supervisors, schedulers, subscription system, and feedback loops. Durable execution in Vox is primarily a workflow story today (interpreted vox mens workflow … step replay with a run id), not a guarantee that every spawned process is automatically crash-resumable; orchestration and Codex surfaces add their own persistence semantics separately.

What OpenClaw Does Better (Improvement Opportunities)

1. Persistent Memory System

• Daily append-only Markdown logs (memory/YYYY-MM-DD.md)
• Curated long-term knowledge (MEMORY.md)
• Pre-compaction memory flush (saves facts before summarization)
• BM25 + vector hybrid search (SQLite-vec + FTS5)
• Human-inspectable and editable

2. Context Window Management

• Automatic compaction (summarizes old turns)
• Context window guards (blocks runs with insufficient context)
• Head/tail preservation (keeps first/last of long messages)
• Turn-based trimming, /compact command

3. Session Lifecycle

• Persistent JSONL session files
• Session resolution and routing
• Session isolation as security boundaries
• Daily reset policies and cleanup

4. Skills Marketplace (ClawHub)

• Public registry with versioned skill bundles
• Vector-search discovery
• CLI install (clawhub install <slug>)
• Community ecosystem and network effects

5. Plugin System

• Channel plugins (new messaging platforms)
• Memory plugins (alternative storage backends)
• Tool plugins (custom capabilities)
• Provider plugins (custom LLM providers)
• Runtime hooks (event-driven automation)

6. Docker Sandboxing

• Tool execution inside Docker containers
• Configurable per-session sandboxing
• Dangerous path blocking (/etc, /proc)

7. Browser Automation

• Full CDP (Chrome DevTools Protocol) integration
• Isolated Chromium instances
• Form filling, scraping, screenshots, PDF export

8. Webhook Ingestion

• HTTP POST endpoints for external triggers
• Event-driven task creation from external systems

9. Cross-Channel Memory

• Shared workspace and memory across chat platforms
• Preferences established in one channel apply everywhere

10. Security Model

• Policy-as-code (AGENTS.md, SOUL.md, TOOLS.md)
• Prompt injection defenses
• Audit and session logging

Summary Scorecard

Native WS-First Interop Contract (Vox, 2026-03)

Vox now treats OpenClaw interoperability as a WS-first runtime contract, not only a skill import path:

• Primary transport: OpenClaw Gateway WebSocket protocol (connect.challenge event, connect request, request/response/event frames).
• Secondary fallback: OpenClaw HTTP compatibility surfaces where needed (/v1/chat/completions, /v1/responses) and existing skills endpoints.
• Internal boundary: OpenClawRuntimeAdapter in Rust (vox-skills) isolates wire protocol details from CLI/runtime consumers.
• Script surface: .vox gets a low-complexity builtin module (OpenClaw.*) that lowers into runtime helper calls and still passes normal parse/type/HIR gates.
• Endpoint SSOT: adapter resolution prefers explicit overrides, then env/Clavis, then upstream discovery (/.well-known/openclaw.json) with cached last-known-good fallback, then deterministic local defaults.
• Packaging posture: Vox bootstrap/upgrade can install a managed openclaw-gateway sidecar from release assets when present in checksums.txt, avoiding hardcoded URL catalogs.

Security and policy posture

• Resolve auth through Clavis (VOX_OPENCLAW_TOKEN) where available.
• Keep TLS verification enabled by default.
• Prefer loopback/tailnet WS URLs in dev (VOX_OPENCLAW_WS_URL), with explicit token/pass-through for remote.
• Treat adapter errors as typed contract failures (transport/protocol/method) for deterministic script/CLI handling.

Contract fixtures

Protocol fixtures are versioned in:

• contracts/openclaw/protocol/connect.challenge.json
• contracts/openclaw/protocol/connect.hello-ok.json
• contracts/openclaw/protocol/subscriptions.list.response.json
• contracts/openclaw/discovery/well-known.response.json
• contracts/openclaw/discovery/well-known.minimal.json

The CI guard vox ci openclaw-contract validates required fixture presence and baseline shape invariants.

Resolver and sidecar lifecycle SSOT: docs/src/reference/openclaw-discovery-sidecar-ssot.md.

Rosetta Inventory: One Scenario, Four Languages

At 2:13 a.m., a player drags six potions onto a stack of seven.

The correct answer is boring:

• the main stack becomes 10
• the overflow stack becomes 3
• a sword does not mysteriously merge with a potion
• a crashed trade settlement does not charge twice
• the UI shows the same truth the server just committed

The interesting part is how many different ways a "tiny inventory merge" can turn into a personality test for your language.

We already have the isolated feature tours elsewhere:

• Why Vox: Compiler-Verified AI Code handles the LLM/runtime argument.
• Golden Examples catalogs the standalone Vox features.

This page keeps one scenario on stage and lets each language embarrass itself in a different way.

The Scenario

We will keep the same request all the way through:

Each language gets exactly one signature failure mode. No repeating the same sermon with different punctuation.

One Joke Each

flowchart TD
    startNode["Inventory Merge Scenario"] --> cppAct["C++23: Iterator Invalidation"]
    startNode --> rustAct["Rust: Shared-State Ceremony"]
    startNode --> pyAct["Python: Mutable Default Aliasing"]
    cppAct --> voxLayers["Vox Layers"]
    rustAct --> voxLayers
    pyAct --> voxLayers
    voxLayers --> typesLayer["Types + Pure Merge"]
    voxLayers --> tableLayer["@table Persistence"]
    voxLayers --> actorLayer["Actor Mailbox"]
    voxLayers --> workflowLayer["Durable Workflow"]
    voxLayers --> mcpLayer["@mcp.tool Surface"]
    voxLayers --> uiLayer["Island UI"]
    voxLayers --> capsLayer["Capability-Gated Import"]

C++23: The Backpack With Loose Screws

The first version looks respectable. It has structs. It has std::vector. It has the confident posture of code that has ruined at least one weekend before.

// vox:skip
struct Stack {
    std::string kind;
    int qty;
    int max_stack;
};

void merge_first_fit(std::vector<Stack>& stash, Stack incoming) {
    for (auto it = stash.begin(); it != stash.end(); ++it) {
        if (it->kind != incoming.kind) continue;

        int room = it->max_stack - it->qty;
        int moved = std::min(room, incoming.qty);
        it->qty += moved;
        incoming.qty -= moved;

        if (incoming.qty > 0) {
            stash.push_back(incoming); // reallocation may invalidate `it`
        }
        return;
    }

    stash.push_back(incoming);
}

That last line is the whole genre in miniature. The inventory math is fine. The footgun is not in the domain model. The footgun is in the furniture. Your potion merge now depends on remembering what push_back thinks about reallocation today.

Rust: The Backpack With Committee Minutes

Rust takes the sharp object away, which is excellent. Then the game designer says, "Great, now make two players merge into the same guild chest at once," and the tiny merge helper graduates into a governance structure.

#![allow(unused)]
fn main() {
// vox:skip
use std::sync::{Arc, Mutex};

#[derive(Clone)]
struct Stack {
    kind: String,
    qty: u32,
    max_stack: u32,
}

type SharedStash = Arc<Mutex<Vec<Stack>>>;

fn merge(stash: &SharedStash, incoming: Stack) -> Result<Option<Stack>, String> {
    let mut guard = stash.lock().map_err(|_| "lock poisoned".to_string())?;
    if let Some(slot) = guard.iter_mut().find(|s| s.kind == incoming.kind) {
        let room = slot.max_stack - slot.qty;
        let moved = room.min(incoming.qty);
        slot.qty += moved;
        let overflow = incoming.qty - moved;
        return Ok((overflow > 0).then_some(Stack { qty: overflow, ..incoming }));
    }
    guard.push(incoming);
    Ok(None)
}
}

Rust is doing its job. That is the joke. The merge logic is no longer the entire story; the story now includes lock acquisition, poison handling, cloned state, return envelopes, and the quiet understanding that the nice pure function left the building three minutes ago.

Python: The Backpack That Remembers Everyone

Python arrives smiling, already halfway done, promising that all of this can be handled in seven charming lines. Python is not lying. Python is simply omitting the sequel.

# vox:skip
def merge_stack(kind, qty, stash={"Potion": [{"qty": 7, "max_stack": 10}]}):
    slot = stash.setdefault(kind, [{"qty": 0, "max_stack": 10}])[0]
    moved = min(slot["max_stack"] - slot["qty"], qty)
    slot["qty"] += moved
    return stash, qty - moved

alice_stash, overflow = merge_stack("Potion", 6)
bob_stash, _ = merge_stack("Potion", 1)
# Bob did not ask to inherit Alice's backpack, but here we all are.

The bug is not theatrical. That is what makes it lethal. Nobody gets a dramatic compiler speech. Two callers just start sharing yesterday's state like a cursed communal lunch.

Vox: The Language That Keeps Closing Tabs

Vox does not win this comparison by shouting louder. It wins by reducing how many places the same idea needs to be true.

Start with the merge. Then keep adding reality without switching languages, frameworks, job systems, schema files, tool manifests, or "temporary" UI glue that will apparently live forever.

Layer 1: Types + Pure Merge

The first repair is not heroic. It is simply explicit. Wrong kinds and invalid caps are values in the language, not comments in the margin.

type MergeError =
    | WrongKind(left: str, right: str)
    | InvalidCap(cap: int)

type MergeOutcome =
    | Applied(primary: int, overflow: int)
    | Rejected(err: MergeError)

fn merge_stacks(kind_a: str, qty_a: int, kind_b: str, qty_b: int, max_stack: int) -> MergeOutcome {
    if max_stack <= 0 {
        ret Rejected(InvalidCap(max_stack))
    }
    if kind_a != kind_b {
        ret Rejected(WrongKind(kind_a, kind_b))
    }

    let total = qty_a + qty_b
    if total <= max_stack {
        ret Applied(total, 0)
    }
    ret Applied(max_stack, total - max_stack)
}

Layer 2: @table Persistence

Now the backpack stops being a rumor. The stack shape becomes schema, query surface, and mutation boundary in one place.

@table type InventoryStack {
    kind: str
    qty: int
    max_stack: int
}

@query
fn stack_count(kind: str) -> int {
    ret len(db.InventoryStack.filter({ kind: kind }))
}

@mutation
fn seed_stack(kind: str, qty: int, max_stack: int) -> Result[str] {
    if qty < 0 {
        ret Error("invalid stack shape")
    }
    if max_stack <= 0 {
        ret Error("invalid stack shape")
    }
    db.InventoryStack.insert({ kind: kind, qty: qty, max_stack: max_stack })
    ret Ok("seeded")
}

Layer 3: Actor Mailbox

Rust needed a summit meeting about shared mutable state. Vox answers with a mailbox: one place receives the merge request, one place owns the sequencing.

actor InventoryActor {
    on MergeRequest(current: int, incoming: int, max_stack: int) -> int {
        let total = current + incoming
        if total > max_stack {
            ret max_stack
        }
        ret total
    }
}

Layer 4: Durable Workflow

Once a merge becomes a trade, the problem changes again. You are no longer merging numbers; you are surviving interruption without charging twice and without inventing a folklore document called trade_retry_final_v2.rs.

activity reserve_slots(amount: int) -> Result[str] {
    if amount <= 0 {
        ret Error("invalid amount")
    }
    ret Ok("reserve_ok")
}

workflow settle_trade(amount: int) -> str {
    let step = reserve_slots(amount)
    match step {
        Ok(code) -> "trade-settled:" + code
        Error(msg) -> "trade-failed:" + msg
    }
}

Layer 5: MCP Tool Surface

If an agent wants to propose the merge, the same language surface can expose it as a tool instead of forcing you to maintain a second ceremony in JSON-schema cosplay.

@mcp.tool "propose_merge: Propose a stack merge and return primary+overflow"
fn propose_merge(kind: str, current: int, incoming: int, max_stack: int) -> str {
    let total = current + incoming
    if total <= max_stack {
        ret kind + ":" + str(total) + "+0"
    }
    ret kind + ":" + str(max_stack) + "+" + str(total - max_stack)
}

Layer 6: UI Island

Eventually someone asks to see the stash. In a lot of stacks, this is where the story forks into a second language and a pile of politely drifting types. Here it stays in the same orbit.

@island StashMeter {
    values: list[int]
}

component InventoryView() {
    view: <div className="inventory-view">
        <h1>{"inventory"}</h1>
        <StashMeter values=[7, 9, 2] />
    </div>
}

routes {
    "/inventory" to InventoryView
}

Layer 7: Capability-Gated Import

And when the backpack finally meets the outside world, the boundary is explicit. Importing loot from a file is not smuggled in as ambient permission; it is named, checked, and therefore discussable.

fn import_loot_csv(capability_token: str, path: str) -> Result[str] {
    if capability_token == "" {
        ret Error("missing capability token")
    }
    ret Ok("imported:" + path)
}

The capability model details are covered in How-To: System I/O and Capabilities.

Why This Page Exists

This is not "Vox does everything and therefore everything must be shown at once." It is a staged reveal:

1. C++ shows how low-level container behavior can leak into domain logic.
2. Rust shows how concurrency correctness expands the surface area around simple logic.
3. Python shows how short code can quietly preserve the wrong state.
4. Vox keeps answering the new problem without changing the fundamental shape of the program.

If you want the feature-by-feature catalog, use Golden Examples. If you want the AI/compiler argument, use Why Vox: Compiler-Verified AI Code. If you want the formal syntax and decorator surface, use Reference: Language Syntax and Reference: Decorator Registry.

Vox Frequently Asked Questions (FAQ)

This page answers product and architecture questions.

For operational fixes, environment issues, or command failures, use the Troubleshooting FAQ.

Language Basics

What is Vox?

Vox is a full-stack programming language and toolchain that aims to keep more of the application structure in one place. The current repository documents a compiler and CLI that generate Rust and TypeScript artifacts, plus a wider ecosystem of orchestration, MCP, and Mens-related tooling.

Is Vox statically typed?

Yes. Vox uses bidirectional type inference: you rarely need explicit types inside function bodies, but all signatures are validated at compile time.

How does Vox handle null?

Null is completely banned. Absent values use Option[T] (Some(value) or None); fallible operations use Result[T, E] (Ok(value) or Error(e)). Both must be explicitly handled — the compiler rejects unhandled cases. See Type System Reference for details.

Installation & Toolchain

How do I install and update Vox?

Build from source with cargo install --locked --path crates/vox-cli.

To discover what your installed binary actually supports, run vox commands --recommended and vox commands --format json --include-nested. The docs intentionally distinguish between the current compiled CLI surface and broader workspace capabilities.

What does vox build do?

vox build lexes, parses, and type-checks your .vox file, then generates Rust and TypeScript output.
Why use it: it gives you a deterministic compile artifact you can inspect before running or bundling.

Can I use existing Rust or NPM libraries?

Yes. Use import rust:<crate> (for example import rust:serde_json as json) for Rust crates and standard NPM imports in frontend blocks.

Architecture & Runtime

• Actor — a stateful unit of concurrency with a private mailbox. Processes one message at a time; no shared-state races.
• Workflow — a long-running orchestration construct. Today, the interpreted workflow runtime provides the repo's durable step-replay path, while generated Rust workflows are not yet full durable state machines (see ADR-021).

What is the Mens?

In current repo language, Mens refers to the model-training lane and local model generation pipeline, while Populi / mesh refers to coordination, inference serving, and distributed execution surfaces. Older docs sometimes used the terms loosely; newer docs keep those lanes separate.

What is the difference between activity and workflow?

A workflow is an overarching orchestrator that tracks progress durably across steps, whereas an activity is an individual, retryable unit of work that performs side effects (like an API call). Workflows run activities but are not meant to contain side effects directly.

What is @island and how does it differ from @island?

@island is the single mechanism for creating client-side UI explicitly using React. @island was an older, deprecated concept removed completely in v0.3 and will result in a hard parser error.

What is Codex and how does it relate to SQLite?

Codex is the logical data environment — the unified data and knowledge store in Vox that application code interacts with. It acts as a high-level facade over Arca, which handles the actual physical storage (SQLite/Turso layer under the hood).

How is Vox different from Go or Erlang/Elixir?

Vox is opinionated about generated outputs, durable workflows, and keeping more application structure in one language. Its design language overlaps with actor and workflow systems, but the repo also includes code generation, contracts, and web-facing lanes that are not trying to be a drop-in clone of Go or Erlang/Elixir.

AI & ML Integration

How does Vox support AI agents?

The repo has native Model Context Protocol (MCP) integration and a growing set of tool-registry contracts. In the current documentation set, the canonical sources are the MCP registry contract pages and the vox-mcp workspace surfaces, not older duplicate reference tables.

What is Mens, and how do I fine-tune a model?

Mens is the repo's native model-training lane. The current default production mix is still code-oriented; documentation prose extraction exists, but architecture Q&A is not the default training objective today.

For the canonical training entrypoint:

vox mens train --backend qlora

See Mens native training SSOT, Mens training data contract, and How To: Train Mens Models.

What is the Socrates Protocol?

An orchestration-layer reasoning protocol (SOP). Before generating or approving code, Vox uses structural prompts to force the underlying LLM to evaluate confidence and structure its reasoning via the MCP control plane.

Deployment & Community

How do I deploy a Vox app?

Deployment surfaces exist, but they are not all equivalent in maturity. Treat the deployment and portability docs as the current source of truth for the lane you are using rather than assuming every repo path is equally production-ready.

Is Vox open source? How do I contribute?

Yes, Apache-2.0 licensed. Start with the Contributor hub, follow STYLE.md, and use the relevant vox ci guards for the area you changed.

Why Vox: Compiler-Verified AI Code

The primary barrier to AI-driven software engineering is not the model's intelligence, but the hallucination boundary of current languages.

1. The Python Problem

When an LLM generates Python code (FastAPI, SQLAlchemy, etc.), it is guessing across a massive, unconstrained state space:

• Runtime Persistence: Did it guess the correct column name?
• Dependency Drift: Is that library version actually installed?
• Dynamic Typing: Will this None propagate into a crash 5 minutes into execution?

In Python, the feedback loop is runtime failure. The model has to run the code, see the crash, and attempt a second guess. This is inefficient and risky for autonomous agents.

2. The Vox Solution: Compiler-Enforced Reality

Vox is designed so that the compiler acts as the guardrail for the LLM.

@table: The Database is the Source of Truth

In Vox, you don't write SQL strings or use a loose ORM. You define your schema with @table.

fn demo_scalars() {
    let i: int = 42
    let f: float = 3.14
    let s: str = "hello"
    let b: bool = true
    let c: char = 'x'
}

// vox:skip
@table type User {
    email: str
    points: int
}

If an LLM attempts to generate code that accesses user.score instead of user.points, the Vox compiler fails immediately. The model receives a precise type error: Field 'score' not found on type 'User'.

Zero-Null Discipline

LLMs frequently forget to check for null. In Vox, null does not exist. You must handle Option[T] using match.

fn handle_state(net_state: NetworkState) {
    match net_state {
        Disconnected -> print("offline")
        Connecting -> print("connecting...")
        Connected(address, port) -> print("connected to " + address)
    }
}

If the LLM omits the None case, the compiler rejects the code for a non-exhaustive match. The model is forced to be correct.

3. Results: Practical Implications

By constraining the LLM's output to a strictly-typed, compiler-verified grammar:

• The compiler provides exact field-name errors rather than runtime stack traces, reducing the iteration cycle for LLM-driven code generation.
• Lower K-Complexity: A single .vox file replaces 10+ files of boilerplate across Rust and TypeScript.

Next Steps:

• Language Reference
• How-To: Build AI Agents
• Installation

[!WARNING] ARCHIVED DOCUMENT: This file was archived on 2026-04-13. It is intentionally excluded from active AI context. It is preserved for potential Vox Scientia publication. Do not reference for contemporary development. See README.md at the repo root.

A unified language designed for human intent and machine execution—empowering developers and intelligent models to build complex systems and accelerate discovery together.

vox-lang.org

Why Vox Exists

Today, developers direct language models to construct systems, but programming languages were designed before the advent of GPT. Unconstrained API surfaces and flexible paradigms—the highly dynamic typing of JavaScript yielding silent runtime failures, the hidden state mutations of C++ pointer arithmetic, or the unverified deep configuration boilerplate prominent in Python—give AI agents too much room to hallucinate, resulting in unintended consequences and unreliable systems.

Furthermore, internet-native code is notoriously slow to move and fragile to change. Decades of bridging the "object-relational impedance mismatch" (Copeland & Maier, 1984)—the fundamental friction between software logic and relational databases⁷—has buried essential architectures beneath layers of ORMs, state management, and network glue code. This bloat rapidly compounds technical debt (Cunningham, 1992)⁸. As codebases expand to manage stateless HTTP connections and fragmented persistence layers, they become extremely difficult for developers—and now AI agents—to safely traverse and refactor.

For Large Language Models, this fragmentation is catastrophic. Agents fail not simply because they hallucinate, but because their reasoning capacity is diluted by excessive contextual noise. While an LLM might technically boast a "one-million token context window," research shows models suffer from severe "context rot" (Liu et al., 2023)⁹ when trying to track complex state transitions spread across multiple REST endpoints and database files.

Vox was purposefully designed to address these constraints. By collapsing the database schema, server execution, and web interactivity into a single, unified intermediate representation, Vox radically reduces the cognitive load and token count required to synthesize full-stack engineering.

Vox is built as a language target for LLMs. By constraining engineering boundaries, it surfaces logical gaps and establishes a self-healing bounds loop that translates human intent into deterministic, executable code.

Vox is not designed to write hardware drivers, but it is fundamentally internet-native. Distributed networks are inherently more durable and often more powerful than isolated processes.

Our systems must be able to hear and be heard by the world before their internal logic can be truly useful. Vox exists to bridge the gap between legacy communication structures and the demands of probabilistic math. Instead of forcing developers and AI agents to manually wire together brittle HTTP endpoints, Vox abstracts online communication into strict, verifiable contracts. The compiler automatically translates high-level intent into stable APIs and interactive web interfaces capable of pausing and resuming execution across stateless connections. This empowers humans to jointly orchestrate distributed systems and power autonomous research with much less friction from legacy infrastructure and boilerplate translation.

(Note: Mobile support is integrated for generated browser-apps and native on-device inference, but deploying the full Vox orchestration runtime directly on mobile devices is not currently supported.)

Platform Architecture & Stability

We stratify the platform based on a single metric: model predictability. For an AI to reliably write code, the underlying rules must be rigid. We lock down the core capabilities first—data, logic, and memory—because they anchor the LLM's understanding. Higher-level surfaces like visual rendering remain fluid as we discover the best ways for AI to construct them.

To make the system comprehensible for both human operators and AI agents, Vox divides its architecture into discrete shapes. This separation ensures that an AI generating a database schema does not accidentally modify how a button renders. Stability is enforced systemically through continuous integration and compiler test boundaries.

The Stability Tiers

• 🟢 Tier 1 (Stable): Production-ready. The rules are locked and mathematically verifiable, ensuring LLMs can generate predictable logic.
• 🟡 Tier 2 (Preview): Functionally complete, but the underlying execution lifecycle or AI-generation pipelines are still being optimized.
• 🚧 Tier 3 (Experimental): Under active architectural planning or gated behind CLI feature flags.

Domain Matrix

The following matrix maps these stability tiers across the core functional boundaries of the Vox platform, detailing how each domain is managed and verified.

Current footprint as of v0.4 — April 2026.

How Vox Solves the Training Paradox

Legacy languages appear to hold a permanent AI advantage because models absorb massive quantities of their text scraped from the internet.

Vox bypasses this requirement. The repository includes local training primitives (vox populi and the MENS neural pipeline) that let developers natively fine-tune any foundation model to master Vox's structural boundaries. Because the platform ships with an inference mesh that scales across diverse hardware architectures, you aren't locked out of AI-assisted engineering just because a model hasn't seen enough of your syntax.

How Vox Works

Code generation fails when an AI navigates fragmented files, hidden states, and chaotic lifecycles. Vox functions as a high-level abstraction that rigorously lowers into safe, deterministic infrastructure.

• High-Level Intermediate Representation (HIR): When an AI writes a .vox file, the parser lowers it into a strictly unified HIR. Database bindings and HTTP handshakes are resolved by the compiler before generation.
• Deterministic Rendering (WebIR): UI compiles directly to a Web Intermediate Representation. Agents don't juggle React hooks or state waterfalls—they emit pure data representations, and WebIR translates it to HTML.
• Semantic Error Feedback: Operations return strict Result[T] constraints. If an agent fails to handle an error state, the compiler catches it immediately and feeds syntax-level feedback to self-correct.
• Native Protocol Projection: AI capabilities aren't a bolted-on SDK. The AST inherently recognizes decorators like @mcp.tool. The compiler automatically projects these into Model Context Protocol manifests, meaning external agents can execute your logic without hand-written REST scaffolding.

The Language

Here's a complete Vox program — a task tracker with a database table, a server endpoint, and a page:

// vox:skip
@table type Task {      // defines database schema
    title: str
    done:  bool
}

@server fn complete_task(id: Id[Task]) to Result[Unit] {
    db.Task.delete(id)
    ret Ok(Unit)        // signals success; the caller must handle failure too
}

@island TaskList {      // a live, interactive component in the browser
    tasks: list[Task]
}

component TaskPage() { // the static page that hosts it
    view: <div><TaskList tasks=[...] /></div>
}

routes { "/" to TaskPage }

One file. The compiler generates the SQL schema, the server endpoint, and the browser-side code that connects them. No separate ORM configuration, no hand-written API route, no TypeScript interface to keep in sync.

Step 1 — Declare your data

In most projects, a data type lives in three places at once: a database schema, a server model, and a client type. They drift apart silently. Vox collapses all three into one declaration:

// vox:skip
@require(len(self.title) > 0)    // the compiler rejects empty titles on insert
@table type Task {
    title:    str
    done:     bool
    priority: int
    owner:    str
}

@index Task.by_owner on (owner)  // the database index, declared next to the type

@table generates the SQL table and handles schema migrations automatically. @require is baked into every write path — not just a runtime check, it can't be bypassed. @index creates a database index for fast lookups by owner.

Step 2 — Write server functions

// vox:skip
@query
fn recent_tasks() to list[Task] {
    // read-only; becomes a GET /api/query/recent_tasks endpoint automatically
    ret db.Task.where({ done: false }).order_by("priority", "desc").limit(10)
}

@server fn get_task(id: Id[Task]) to Result[Task] {
    let row = db.Task.find(id)
    match row {
        Some(t) -> Ok(t)           // task found: return it
        None    -> Error("not found")  // task missing: return an error
    }
}

@mutation
fn add_task(title: str, owner: str) to Id[Task] {
    // writes are wrapped in a transaction automatically
    ret db.insert(Task, { title: title, done: false, priority: 0, owner: owner })
}

@query exposes a read-only endpoint — Vox enforces that it never changes data. @mutation wraps the write in a database transaction; if something goes wrong, the whole operation rolls back. The return type Result[Task] forces every caller to handle both the found and not-found cases. The compiler won't build code that ignores the error.

Step 3 — Build the UI

Modern web apps split into two concerns: the server, which renders initial HTML and handles data, and the browser, which handles interactivity. Vox solves this with two distinct primitives:

// vox:skip
// An island is a piece of the page that's interactive in the browser.
// React lives inside the generated artifact — not in your .vox source.
@island TaskList {
    tasks: list[Task]              // same Task type from Step 1 — no duplication
    on_complete: fn(str) -> Unit   // a callback the browser can call
}

// A component is server-rendered — fast initial load, no JavaScript needed.
component TaskPage() {
    view: <div className="task-list">
        <TaskList tasks=[...] on_complete={complete_task} />
    </div>
}

routes { "/" to TaskPage }

@island marks the boundary where the browser takes over. The compiler generates the React component, the browser lifecycle wiring, and the typed client stub — none of that appears in your .vox) source. component` stays on the server: rendered to HTML, fast to load, written entirely in Vox syntax. React's mental model — hooks, lifecycle, client state — is confined to the generated layer.

v0.dev integration: vox island generate TaskDashboard "A minimal sidebar dashboard" calls the v0.dev API (requires V0_API_KEY) and writes the generated component into islands/src/TaskDashboard/. The @v0 build hook triggers this automatically during vox build.

Step 4 — Durable logic and AI tools

// vox:skip
// An activity is a step that can be retried independently if it fails
activity charge_card(amount: int) to Result[str] {
    if amount > 1000 { ret Error("Amount too large") }
    ret Ok("tx_123")
}

// A workflow orchestrates activities and survives crashes — its state is durable
workflow checkout(amount: int) to str {
    let result = charge_card(amount)
    match result {
        Ok(tx)     -> "Success: " + tx
        Error(msg) -> "Failed: " + msg
    }
}

// One decorator makes this function callable by Claude, Cursor, or any AI agent
@mcp.tool "Search the knowledge base"
fn search_knowledge(query: str) to str {
    "Result for: " + query
}

// Tests live in the same file, run with `vox test`
@test
fn test_search() to Unit {
    assert(search_knowledge("hello") is str)
}

workflow tracks its own progress — if the server restarts halfway through checkout, it picks up where it left off. An actor is a named entity that receives typed messages and holds its own state across many calls. @mcp.tool connects your function to the Model Context Protocol in one line, making search_knowledge directly invocable from Claude, Cursor, or any compatible agent.

More examples: examples/golden/.

For a side-by-side comparison with C++, Rust, and Python solving the same problem, see docs/src/explanation/expl-rosetta-inventory.md.

Quick Start

macOS / Linux:

curl -fsSL https://raw.githubusercontent.com/vox-foundation/vox/main/scripts/install.sh | bash

Windows (PowerShell):

irm https://raw.githubusercontent.com/vox-foundation/vox/main/scripts/install.ps1 | iex

# Create your first project
vox init my-app
cd my-app
vox build src/main.vox -o dist
vox run src/main.vox

vox init [name]          Scaffold a new project (templates: chatbot, dashboard, api)
vox build <file>         Compile → TypeScript + Rust output
vox check <file>         Fast type validation
vox run <file>           Development server (Axum + TanStack dev proxy)
vox dev <file>           Hot-reload dev mode
vox test <file>          Run @test functions
vox fmt <file>           Format source
vox bundle <file>        Full production build: codegen → pnpm build → single binary
vox doctor               Verify toolchain, environment, and secret health

Full command reference: docs/src/reference/cli.md.

The CLI

Run vox commands --recommended for a curated first-time map of subcommands. For repository hygiene, vox ci gui-smoke runs deterministic Web Intermediate Representation (WebIR) routing tests and can opt into Vite (VOX_WEB_VITE_SMOKE=1) or Playwright (VOX_GUI_PLAYWRIGHT=1) lanes documented in the same CLI reference.

Agent Orchestration & AI Capabilities

Multi-agent coordination

The orchestrator (vox-orchestrator) assigns tasks to agents by file affinity and role. vox-dei handles human-in-the-loop review — pausing, reassigning, or confirming work before it proceeds. The control surface is available as MCP tools, usable from the VS Code sidebar or any MCP-compatible agent:

vox_pause_agent      Suspend a running agent and queue its tasks
vox_resume_agent     Resume a paused agent
vox_retire_agent     Retire an agent and release all locks
vox_reorder_task     Change dispatch priority of a queued task
vox_queue_status     Show orchestrator queue and agent states

Agent-to-agent messaging

In most systems, passing results between agents means building your own protocol — a shared table, a queue, a webhook. In Vox, agent-to-agent messaging is built into the runtime. Agents exchange typed, encrypted messages; because both sides use the same declared Vox type, the compiler catches mismatches before anything runs.

The in-process message bus is active in every session. Cross-machine relay is available with the populi-transport feature.

The Populi mesh

vox populi is a node registry for machines running Vox. Each node detects and advertises its hardware — CPU, CUDA, Metal, VRAM — on startup. The orchestrator routes training and inference jobs to the machines that can handle them.

VOX_MESH_ENABLED=1 VOX_MESH_NODE_ID=my-node vox populi serve

Model selection & provider routing

vox populi status --quotas   # view per-provider usage and remaining budget

Local GPU & Native Training (MENS)

The MENS neural pipeline lets developers fine-tune foundation models to generate Vox code natively. vox-tensor and vox-populi run in Rust using Burn and Candle — no Python, no pip install, no virtual environments.

vox populi probe detects your local hardware topology (CUDA, Metal, WebGPU) and orchestrates multiple parallel AI pipelines:

1. QLoRA Fine-Tuning: Train specialized adapter weights from your team's internal src/ repositories.
2. Speech-to-Code (ASR): Run real-time structured inference using local Whisper/Qwen models to map vocal commands to AST modifications.
3. Local Mesh Serving: Deploy models via an OpenAI-compatible /v1/completions endpoint for offline agentic orchestration.

# Automatically profile hardware and begin a QLoRA fine-tune
vox populi train --config qlora.toml

# Expose the fine-tuned adapter over the local mesh network
vox populi serve --model mens/runs/latest/model_final.bin --port 8080

Documentation

Vox documentation is structured around the Diátaxis framework, explicitly separating tutorials, how-to guides, explanations, and pure reference material.

Looking to contribute? We actively track undocumented surfaces. Check our Known Documentation Gaps & Backlog to see where the community needs help.

Architectural Guardrails

Vox applies the same philosophy to itself that it applies to user code: machine-verifiable constraints over style-guide suggestions. The rules below aren't enforced through code review — they fail CI. Each one exists because we've seen what happens without it.

No skeleton code (vox-toestub)

todo!(), unimplemented!(), empty function bodies, and hollow arrow functions in production paths are a build blocker. The vox-toestub crate runs a suite of detectors — StubDetector, EmptyBodyDetector, HollowFnDetector, ReachabilityDetector, and others — as part of every CI matrix pass under vox ci toestub-scoped.

Why it matters for AI codebases: AI agents produce plausible-looking scaffolding. An agent that returns a todo!() didn't finish the job — it silently deferred it. TOESTUB makes that deferral a build failure rather than a runtime surprise. The VictoryClaimDetector goes further, flagging comments like "implementation complete" adjacent to unimplemented!() calls.

vox stub-check --path crates/my-crate   # run locally before pushing
vox ci toestub-scoped                   # full workspace scan in CI

Complexity bounds (GodObjectDetector, SprawlDetector)

No struct or impl block may exceed 500 lines or 12 methods. No directory may contain more than 20 files. Both limits are enforced by dedicated detectors in vox-toestub.

Why it matters: An LLM's ability to reason about a module degrades sharply when the module exceeds its coherent processing window. The 500-line limit isn't aesthetic — it's calibrated so the entire struct fits comfortably within a 32K-token context window alongside the surrounding codebase. The 20-file directory limit forces domain decomposition before a module becomes a grab-bag. The vox-orchestrator crate documents this explicitly in its own module comment: "decomposed from the original god-object."

All credentials routed through Clavis (secret-env-guard, operator-env-guard)

Direct std::env::var calls for secrets are a CI failure. All credentials are declared as SecretId variants in crates/vox-clavis/src/lib.rs and resolved via vox_clavis::resolve_secret(...). The vox ci secret-env-guard command scans changed files for raw environment reads and fails the build if any are found outside a strict allowlist.

Why it matters: Hidden environment variables cause deployment drift and make it impossible to audit what capabilities an application possesses. When an agent introduces a new API key, it must go through Clavis — which means it appears in vox clavis doctor, gets picked up by vox ci clavis-parity, and is visible to every operator. There's no path for a credential to sneak in through a casual env::var("SOME_API_KEY"). The SecretDetector in vox-toestub catches hardcoded credentials as a separate failure class.

Documentation is compiler-verified (vox-doc-pipeline, SchemaComplianceDetector)

// vox:skip
All `.vox` code blocks in `docs/src/` must either use `{{#include}}` to pull from a verified file in `examples/golden/`, or be marked `// vox:skip`. Loose code snippets that can't be compiled are a CI failure via `SchemaComplianceDetector`.

Why it matters: Documentation that silently diverges from working code is worse than no documentation — it actively misleads both human readers and AI agents that use docs as retrieval context. The golden file pipeline (examples/golden/) means every snippet in this README and the docs site has been compiled against the current compiler before it shipped.

Context isolation is centrally managed (.voxignore → vox ci sync-ignore-files)

.voxignore is the single source of truth for what files are excluded from AI context. Derived files (.cursorignore, .aiignore, .aiexclude) are regenerated automatically. Editing them directly causes a CI drift failure.

Why it matters: Generated artifacts, telemetry logs, and build outputs are noise that degrades model attention. Without a centrally managed exclusion surface, each tool gets its own ad-hoc ignore file that drifts out of sync, and agents start reading their own previous outputs as source of truth. Centralizing this in .voxignore means the boundary is enforced once, not maintained four times.

No DRY violations, deprecated symbols, or unwired modules

vox-toestub ships additional detectors that catch structural debt before it accumulates: DryViolationDetector flags copy-pasted logic blocks; DeprecatedUsageDetector blocks use of retired crate names and environment variables (see the retired-symbols table in AGENTS.md); UnwiredModuleDetector catches modules declared but never imported. These run in CI alongside the structural checks above.

vox ci toestub-scoped --report    # full findings report with severity breakdown

Acknowledgements & Lineage

Many of the design paradigms that underpin Vox are not entirely unique to this project. Beyond specific frameworks, Vox is heavily influenced by the philosophies that constitute timeless, robust software engineering. We stand on the shoulders of giants.

Systems & Protocols

• Durable Execution (workflow): The concept of writing long-running, fault-tolerant code that magically survives server restarts was pioneered by systems like Azure Durable Functions, and later Cadence & Temporal (created by Maxim Fateev and Samar Abbas)¹.
• Islands Architecture (@island): The approach of sending static HTML and selectively hydrating dynamic "islands" of interactivity was coined by Katie Sylor-Miller at Etsy (2019) and popularized by Jason Miller (creator of Preact) in 2020². Modern frameworks like Astro further normalized this server-first approach.
• Model Context Protocol (@mcp.tool): The standard providing AI models safe, authenticated access to tools and file systems was developed by Anthropic³.
• Unifying Distributed Logic: The philosophy of treating a distributed system as a single cohesive program rather than disjointed microservices owes much of its modern exploration to projects like the Unison language⁴.

Foundational Philosophies

• Accidental vs. Essential Complexity: As outlined by Fred Brooks in The Mythical Man-Month, much of software engineering is bogged down by "accidental complexity"—the tooling, ORMs, and glue code required just to make systems talk to each other. Vox eliminates accidental complexity by natively generating the API and database boundaries, enabling humans and AI to focus squarely on the "essential complexity" of the application logic⁵.
• "Constraints Liberate": Echoing the philosophy of Tony Hoare and the design of strongly typed languages like ML, Haskell, and Rust, Vox relies on rigid schemas and compiler assertions to reject invalid states. By forcing an AI model into a mathematically verifiable corridor, we use constraints as a self-healing bounds loop, proving that strict rules unlock, rather than hinder, generative capability.
• Data-Driven Architecture: "Show me your flowcharts and conceal your tables, and I shall continue to be mystified. Show me your tables... and they'll be obvious." — Fred Brooks. Vox organizes its architecture explicitly around data definitions (@table), radiating logic out from the schema rather than trying to reconcile an ORM with an arbitrary state hierarchy.
• Fail-Fast & The Actor Model: Joe Armstrong's "Let it crash" philosophy from Erlang/OTP informs Vox's durable execution and agent orchestration. Instead of attempting to anticipate and catch every possible local exception natively within an AI model, the system isolates execution into independent activities that can fail, report their status, and securely restart via a centralized orchestrator⁶.

Community, Backing & License

Backing Vox (Open Collective)

The Vox Foundation operates as a transparent, community-backed entity through Open Collective. Every dollar raised and spent is public. Sponsorship funds developer grants, CI hardware for MENS neural training, and academic bounties.

Open Collective →

License

Vox is licensed under Apache 2.0. You can use it to build commercial or closed-source applications without opening your own code. Contributors grant explicit patent rights. You can modify the compiler, runtime, or standard library as long as you retain the original copyright notices.

LICENSE · github.com/vox-foundation/vox

Get Involved

Vox Scientia is a publication pipeline for aggregating and surfacing community research — pulling from wherever developers are talking, not constraining where they talk. Roadmap decisions and architectural questions are tracked in GitHub Discussions because that's the format our tooling can index, parse, and feed back into the system. Come wherever you are.

• GitHub Discussions: Architecture questions, language design feedback, and roadmap input.
• RSS Feed: vox-lang.org/feed.xml — changelogs and architectural decision records.

References

[1] Fateev, M., & Abbas, S. (2019). Temporal. Temporal Technologies. https://temporal.io [2] Miller, J. (2020). Islands Architecture. JasonFormat. https://jasonformat.com/islands-architecture/ [3] Anthropic. (2024). Model Context Protocol. https://modelcontextprotocol.io [4] Unison Computing. Unison Language: A new approach to distributed programming. https://unison-lang.org [5] Brooks, F. P. (1987). "No Silver Bullet—Essence and Accidents of Software Engineering." IEEE Computer, 20(4), 10-19. DOI: https://doi.org/10.1109/MC.1987.1663532 [6] Armstrong, J. (2003). Making reliable distributed systems in the presence of software errors [Ph.D. thesis, Royal Institute of Technology, Stockholm]. https://erlang.org/download/armstrong_thesis_2003.pdf [7] Copeland, G., & Maier, D. (1984). "Making Smalltalk a Database System." SIGMOD '84, 316–325. DOI: https://doi.org/10.1145/602259.602287 [8] Cunningham, W. (1992). "The WyCash Portfolio Management System." Addendum to the proceedings of OOPSLA '92, 29-30. DOI: https://doi.org/10.1145/157709.157715 [9] Liu, N. F., Lin, K., Hewitt, J., Paranjape, A., Bevilacqua, M., Petroni, F., & Liang, P. (2023). "Lost in the Middle: How Language Models Use Long Contexts." Transactions of the Association for Computational Linguistics. arXiv: https://arxiv.org/abs/2307.03172

ADR 002 — Diátaxis Three-Tier Documentation Architecture

Status: Accepted Date: 2026-03-02

Context

Vox needed a reader-facing documentation structure, but the repository also grew contributor governance, machine-readable contracts, research notes, and planning material that do not fit a prefix-only Diataxis model.

The early policy in this ADR leaned on filename prefixes such as tut- and ref-. That helped the first migration, but the current repository organizes most docs by directory, frontmatter category, and intended audience:

• docs/src/ is the published mdBook corpus.
• docs/src/architecture/ contains both current architecture pages and research or roadmap material.
• docs/src/reference/ mirrors machine-backed contracts in reader-facing prose.
• docs/src/contributors/ and docs/agents/ serve contributors and automation.
• contracts/ contains machine-readable SSOT.

Decision

Keep Diátaxis as the reader-facing organizing principle for user documentation, but ground the overall documentation system in audience and authority boundaries rather than filename prefixes alone.

Reader-facing categories