One .vox file compiles to a database schema, a typed server, a browser app, and the artifacts to deploy them. Initiated by Bertrand Reyna-Brainerd.

voxlang.org

---

"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)

---

Why Vox

Mainstream languages predate LLMs by decades. They tolerate implicit state — nulls, exceptions, schemas restated three times across the stack. That's tractable for a person; it's a minefield for a statistical code generator. A million-token context window doesn't help when most of it is integration boilerplate.

Fragmentation in Traditional Web Development
Traditional development requires restating data models and logic across frontend, API, backend, and database layers. This duplication creates significant maintenance overhead and increases the risk of integration drift.

Vox is what falls out when you design the language after the model: collapse the duplications, push errors into the type system, draw the browser/server boundary in one place, and build durability and tool exposure into the grammar instead of layering them on top.

Killer Features

Vox collapses the massive fragmentation of modern web and AI development into a single, cohesive ecosystem.

• Local AI Inference & Fine-Tuning: Run models natively on your GPU without touching Python. Execute open-weights models or train them via QLoRA using Rust-native acceleration (CUDA and Apple Metal).
• One File to Rule the Stack: A single .vox file emits database migrations, a typed API server, reactive frontend components, and deployment artifacts. Zero integration boilerplate.
• Distributed Mesh Computing: Securely network laptops and cloud servers. The orchestrator automatically routes AI workloads to the nodes with the best available hardware.
• Native Desktop GUI: Compile .vox files into fully native, cross-platform graphical applications powered by Tauri, complete with native IPC bridges.
• Wire format — Data and tool contracts are the single source of truth; schemas are generated, not restated.
• Autonomous RAG & Research — Deploy agents equipped with persistent long-term memory, fact-checking (the Socrates protocol), and autonomous web-search.

---

Install

Vox is currently in pre-1.0 active development. Official installation packages (voxup, .msi, .deb, Homebrew) are configured in the CI pipeline but have not yet been formally released.

Building from Source

Prerequisites: Ensure you have Rust and Cargo installed.

git clone https://github.com/vox-foundation/vox.git
cd vox
cargo install --path crates/vox-cli

Quick Start

vox init my-app
cd my-app
vox run src/main.vox

The full CLI surface, including every vox ci, vox populi, and vox mens subcommand, lives at docs/src/reference/cli.md. Run vox commands --recommended for first-time discovery.

---

Ecosystem & Plugins

Vox is highly modular. The core binary covers compile, run, bundle, and package; heavier capabilities are provided through optional extensions.

CLI Extensions

Extensions ship as separate binaries; vox will notify you if one is required but missing.

Extension	Adds	Purpose
vox-ml-cli	vox mens, vox populi, ...	Rust-native ML (Candle, Whisper) for training and serving.
vox-schola	vox schola, vox scientia	Autonomous research and fact-checking.
vox-gui	vox gui	Native Tauri desktop application environment.

Agent Skills

The Vox AgentOS dynamically loads capabilities (Skills) through a stable ABI. First-party skills include:

• ML & Audio: mens-candle-cuda, mens-candle-metal, oratio-mic, populi-mesh
• Execution: runtime-container (Docker), runtime-wasm, script-execution
• Agent Skills: skill-git, skill-memory, skill-orchestrator, skill-rag, skill-testing
• Infrastructure: api, cloud, host, types, webhook

→ See the Plugin Catalog for detailed signatures.

How Vox works

Unified Compilation from a Single Source
Vox uses a single .vox file to derive the entire technology stack. The compiler uses this unified source of truth to generate synchronized database schemas, API servers, and reactive UI components simultaneously.

Pillar 1: One source of truth

@table type Task {
    title: str
    done:  bool
    owner: str
}

The declaration is the schema, the wire format, and the typed client. @index Task.by_owner on (owner) lives next to it. Migrations come from the diff against the previous schema.

→ @table reference · migration guide

Pillar 2: Errors in the type system

@query
fn recent_tasks() to list[Task] {
    return db.Task.where({ done: false }).limit(10)
}

@mutation
fn add_task(title: str, owner: str) to Result[Id[Task]] {
    if title is "" {
        return Error("title required")
    }

    return Ok(db.insert(Task, {
        title: title,
        done: false,
        owner: owner
    }))
}

A Result[T] caller must handle both arms — no exceptions, no null, no implicit propagation. The compiler refuses to build code that drops Error. vox-lsp surfaces the same diagnostics live in the editor.

@query, @mutation, and @server are the three endpoint kinds. They replace the previous @endpoint(kind: …) form (deprecated 2026-05-23; auto-migrated by vox fmt).

→ decorator reference

Pillar 3: One file → running deployment

component TaskPage(tasks: list[Task]) {
    view: column() {
        tasks.map(fn(t) { 
            row() { 
                text() { t.title } 
            } 
        })
    }
}

routes { 
    "/" to TaskPage 
}

vox build emits React/TSX components, a generated vox-client.ts RPC bridge, and — via vox-deploy-codegen — Dockerfile, Compose, Kubernetes, Fly, Coolify, and systemd targets, all derived from the same module graph. External React, TanStack, or mobile apps can import the emitted components or call the endpoints over the bridge.

→ external interop plan · deployment

Pillar 4: Agents, MCP, and the orchestrator

@mcp.tool and @mcp.resource expose typed functions to any Model Context Protocol client.³ The tool description, parameter schema, and return type are all derived from the function signature.

@mcp.tool "Process a checkout for the given amount"
fn checkout(amount: int) to Result[str] {
    if amount > 1000 {
        return Error("amount too large")
    }
    return Ok("tx_123")
}

@mcp.resource("vox://orders/recent", "Recent orders this hour")
fn recent_orders() to list[Order] {
    return db.Order.where({ created_at: hour_ago() })
}

vox-orchestrator routes work to agents by file affinity and ten policy modules (tier cascade, plan-mode trigger, risk matrix, budget gate, circuit breaker, calibration, …). Capabilities are extensible: dozens of first-party plugins (compiler, git, memory, RAG, testing, Mens-Candle-CUDA/Metal, WASM and OCI runtimes) load through vox-plugin-host behind a stable ABI.

Durable execution

workflow and activity are keywords, not a library. The runtime in vox-workflow-runtime checkpoints every activity result to a per-run journal (ADR-019, v1 contract). A crash mid-run resumes on restart with the completed activities replayed from the journal; only the remaining steps re-execute. @scheduled functions run on a persistent scheduler loop with crash-safe state. Supported subset documented in ADR-021; completion ADR is ADR-041. The supported subset ships today; unrestricted control-flow replay remains future work.^{1, 2}

→ orchestration policy research · vox-skills · ADR-041: durable functions completion

Pillar 5: Built for LLM authorship

The shape of the four pillars above is downstream of one decision: design the language after the model. Three subsystems make that concrete.

• Grammar-constrained decoding. vox-constrained-gen is an Earley/PDA decoder⁵ with a deadlock watchdog. Token-stream constraint, not post-hoc validation — invalid Vox cannot be sampled.
• Measurable detectors. Rules live in rules.v1.yaml with a JSON Schema and an F1 bench scorer over fixture corpora. Stub, hollow-fn, victory-claim, AI-laziness, secret, magic-value, deprecated-symbol, and effect-system rules are all scored against ground truth, not vibes.
• Local training. Vox is new; mainstream languages saturate the public training corpus, Vox doesn't. vox populi runs QLoRA⁴ fine-tunes and OpenAI-compatible serving on detected CUDA / Metal / WebGPU — Burn + Candle, no Python. Requires the gpu cargo feature.

→ examples/golden/ · Rosetta comparison · why Vox for AI

---

Touches you'll see everywhere

A few language-level decisions show up in almost every snippet:

Phonetic operators. Vox spells comparisons and booleans as words: is, isnt, and, or, not. The bare != form parses, but the lexer emits a diagnostic pointing at isnt. Words appear in language-model training data far more often than punctuation patterns — so a model is more likely to predict the word than the symbol, and a human reads it aloud unambiguously.

fn classify(score: int, override: bool) to str {
    if override is true { return "admin" }
    if score >= 90 and score isnt 100 { return "expert" }
    if score < 50 or not is_calibrated() { return "novice" }
    return "regular"
}

Opaque ID types. Id[User] and Id[Post] are distinct types. Passing the wrong-table ID to db.Post.find(user_id) is a compile error, not a 4 AM runtime crash.

? propagation + match exhaustiveness. The ? postfix unwraps Ok(value) or short-circuits the function with the Error. The only way to consume a Result is match, and match arms must cover both Ok and Error — the compiler refuses to build silent error-swallowing code.

Sandboxed execution tiers. vox run --isolation wasm script.vox runs untrusted scripts under Wasmtime (vox-wasm-engine). --isolation container runs them in an OCI sandbox via vox-container. vox-bounded-fs caps reads by size; vox-exec-grammar classifies shell-out risk before execution. Useful when an agent generates code you don't want to run on the host.

vox audit runs the rule pack — stub, hollow-fn, victory-claim, AI-laziness, secret, magic-value, deprecated-symbol, and effect-system detectors — each F1-scored against fixture corpora. Rules are calibrated, not vibes.

---

Engineering invariants

Properties enforced on the project itself, invisible from the language surface:

• Layered crate graph. All 101 workspace crates declare a layer (L0 pure types → L5 surfaces) in layers.toml. vox-arch-check blocks inversions, fan-in violations, LoC budget overruns, and orphaned modules.
• Sandboxed execution. vox-wasm-engine (Wasmtime), vox-container (OCI), vox-bounded-fs (size-capped reads), vox-exec-grammar (shell risk classifier). Tiers are selectable on vox run.
• Declared capabilities. vox-capability-registry gates what tools can do; vox-identity signs with ed25519 against a trust ledger; vox-secrets is the only path to a secret value.

---

Automation: VoxScript-first

Project automation is .vox, not .ps1, .sh, or .py. Vox scripts are type-checked, cross-platform, and telemetry-observable by default.

vox run scripts/clean-cache.vox
vox run --isolation wasm scripts/process-untrusted-data.vox

Key Commands:

• vox share publish — Create a short-lived public tunnel for local previews.
• vox audit — Run the rule-pack against your codebase.
• vox telemetry doctor — Verify sink health and event wiring.

---

Distributed AgentOS (Mesh)

Cross-machine orchestration is opt-in. Nodes advertise hardware capabilities (CUDA/Metal/VRAM) on startup, and the orchestrator automatically routes workloads to the best-equipped peer. Agent-to-agent communication is type-safe; wire mismatches are caught at compile time.

VOX_MESH_ENABLED=1 VOX_MESH_NODE_ID=my-node vox populi serve
vox populi status --quotas

Local models and cloud providers are managed through a unified policy layer with per-node quotas. See the model routing how-to.

---

Stability & Path to 1.0

Vox is marching toward a production-hardened v1.0 release. Surfaces are graded by their architectural stability and proximity to the v1 criteria.

Feature Area	Status	Context & Maturity
Core Intelligence
Orchestrator Core	🔵 Stable	Thread-safe dispatch, agent lifecycle, and Superpowers orchestration.
Agent Skills (MCP)	🟣 Mature	Full MCP v1.0 compliance with 100+ first-party tools.
Socrates Research	🟡 Preview	Socrates protocol for automated fact-checking and retrieval.
Language Platform
Compiler Core	🟣 Mature	Wave 2 complete: pure-HIR lowering and stable syntax grammar.
LSP & IDE Tools	🟣 Mature	Production-grade vox-lsp with full cross-reference support.
Durable Runtime	🔵 Stable (interpreter) / 🟡 Preview (codegen)	Interpreter path: journal-backed replay for the supported subset (ADR-019 / ADR-021) ships; @scheduled runs on a persistent scheduler with crash-safe state. Codegen path: generated binaries link but current_hir_module() registration in emitted main() is a tracked Phase-5 follow-up — see ADR-041. Unrestricted control-flow replay is explicit non-goal.
Data & Foundation
Database Engine	🔵 Stable	vox-db with Turso integration and zero-downtime migrations.
Secrets & Safety	🔵 Stable	Clavis hardened vault and Rule Pack CI guards.
Telemetry Facade	🟣 Mature	Unified vox-telemetry with trace propagation and cost rollups.
AI/ML Engine
Inference (Mens)	🟡 Preview	Native CUDA/Metal/CPU inference with Candle/Burn.
Training (Populi)	🟠 Emergent	QLoRA native pipeline; loss-parity verification in progress.
Visus (Vision)	🟠 Emergent	Voice of Vision for automated GUI bug detection.
Platform & UI
CLI & DX	🟣 Mature	Rich diagnostic surface (vox audit, vox ci, vox drift-check).
Native GUI (Tauri)	🟡 Preview	Tauri 2.0 integration with Dashboard, Agent Flow, and Superpowers catalog.
Distributed Mesh	🟠 Emergent	Node discovery and workload routing functional across peers.

Stability Tiers:

• 🟢 Production Candidate: Hardened for 1.0; feature-complete and regression-free.
• 🔵 Stable: API locked; high test coverage; used in core production internal loops.
• 🟣 Mature: Core logic stable; focus on ergonomics, documentation, and performance.
• 🟡 Preview: Feature-complete; API may shift based on early adopter feedback.
• 🟠 Emergent: Core logic functional; major feature parity or scaling remaining.
• 🚧 Experimental: Proof of concept; breaking changes are frequent and expected.
• 🔬 Research: Internal prototypes; not yet exposed in the standard CLI surface.

v1.0 criteria: docs/src/architecture/v1-release-criteria.md. Roadmap: GUI-native phases. History: CHANGELOG.md.

Roadmap execution minimizes syntactic redundancy to stabilize the compiler primitives prior to v1.0. Retired symbols: AGENTS.md retired-surfaces table.

---

Documentation

Docs follow the Diátaxis framework.

Intent	Start here
Learning	Getting Started · First full-stack app
Task recipes	How-To Guides · AI Agents & MCP
Understanding	Why Vox for AI · Compiler architecture
Reference	CLI · Decorators
Architecture	Master index · Contributor hub
Operations	Deployment · CI runner

---

Contributing

Start at the Contributor Hub. The Contribution Loop explains the write → verify → train cycle. If CI flags a gate failure, the TOESTUB Guide covers the common causes. Undocumented surfaces are tracked in DOC_GAPS.md.

---

Beyond the rule pack, the CI environment enforces repo-wide invariants:

Guard	Purpose
vox arch-check	Blocks layer inversions, fan-in violations, and LoC budget overruns.
vox ci secret-env-guard	Blocks raw std::env calls; enforces vox-secrets as the only secret source.
vox ci sync-ignore-files	Ensures .voxignore is synced to IDE-specific ignore files.
vox-drift-check	Detects semantic drift in multi-language workspace artifacts.

Rationale and the full detector inventory live in AGENTS.md.

---

Backing, license, contact

Funded via Open Collective — every transaction is public. Sponsorships fund developer grants, MENS training hardware, and academic bounties.

Apache 2.0: commercial use, patent grant, modification with attribution. LICENSE.

Discussion: GitHub Discussions. Changelogs and ADRs: RSS.

---

References

[1] Fateev, M., & Abbas, S. (2019). Temporal. Temporal Technologies. https://temporal.io

[2] 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

[3] Anthropic. (2024). Model Context Protocol. https://modelcontextprotocol.io

[4] Dettmers, T., Pagnoni, A., Holtzman, A., & Zettlemoyer, L. (2023). QLoRA: Efficient Finetuning of Quantized LLMs. arXiv. https://arxiv.org/abs/2305.14314

[5] Earley, J. (1970). An efficient context-free parsing algorithm. Communications of the ACM, 13(2), 94-102. https://dl.acm.org/doi/10.1145/362007.362035