vox
Health Warn
- License — License: Apache-2.0
- Description — Repository has a description
- Active repo — Last push 0 days ago
- Low visibility — Only 5 GitHub stars
Code Pass
- Code scan — Scanned 12 files during light audit, no dangerous patterns found
Permissions Pass
- Permissions — No dangerous permissions requested
No AI report is available for this listing yet.
The Vox programming language, compiler, capability-sandboxed interpreter, MCP agent orchestrator, trust-tiered RAG index, and pure-Rust QLoRA training suite.
An experimental full-stack programming language, compiler, and verification suite
Declare schemas, server queries, reactive UI, durable workflows, and MCP agent tools in one .vox module — projected without drift across SQLite/Turso, Rust/Axum, and React/TypeScript.
Led by Bertrand Reyna-Brainerd · Stewarded by the Vox Foundation (in formation) · Apache-2.0 · Pre-1.0 Research Prototype (v0.6.0 Workspace)
voxlang.org · Getting Started · Syntax Reference · Stability Matrix · Vox Axis GUI
[!WARNING]
Last reviewed: 2026-11-10 (v6.8/0.6.0workspace). Vox is an active pre-1.0 research project, not production software.
- Working & CI-gated on
main(16,491passing tests across 3 Linux shards): recursive-descent parser & type checker (vox check), capability-sandboxed interpreter (vox run --interp --caps), SQLite/Turso data layer (vox-db, schema baseline97), Tantivy + RRF hybrid knowledge base (vox kb), EBNF/JSON-Schema grammar export (vox grammar), VoxDiagram toolchain (vox diagram), model router (vox model), Clavis secret resolver (vox secrets), and 33crates.iodry-run verified foundation crates (vox ci publish-dry-run).- Prototypes: full-stack Rust/React codegen (
vox build), durable workflow replay (VoxDbTracker), the Tauri 2 desktop workbench (Vox Axis), multi-source research (vox research), and pure-Rust QLoRA training (vox mens, with public Qwen3 adapters on Hugging Face).- Install from source: There is no stable release tag yet; build from
mainwith Cargo (Trying It).
"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)
Animated Language, Compiler & Verification Suite Tour
The Vox Language, Compiler & Verification Flywheel (vox-foundation/vox)
Five architectural plates cycling through: (I) Single-file .vox declaration projected across SQL, Rust/Axum, React/TSX, and MCP; (II) Instant capability-sandboxed interpreter (vox run --caps) vs. native full-stack compilation (vox build); (III) Event-sourced durable workflows (VoxDbTracker), actor file locks (ADR-025), and BLAKE3/HMAC tool receipts (ADR-029); (IV) Multi-turn compiler-feedback evaluation (The central claim) & pure-Rust Candle QLoRA; and (V) 6-layer zero-cycle workspace architecture (L0–L5) with 33 crates.io packages.
Contents
- Why Vox
- A First Look at
.voxCode & Dual Execution Lanes - Architecture & Separation of Concerns Across Repositories
- Tradeoffs: Engineering Costs & Operational Constraints
- How It's Built & Project Stewardship
- Status (All 48 Subsystems Verified
2026-11-10) - Log
- Trying It
- The CLI
- Contributing, Sponsors & License
- Intellectual Lineage, Prior Art & References
Why Vox
A typical web app restates one domain model in four places:
- A database schema (SQL or an ORM migration).
- A backend (Rust, Go, Python, or Node) that validates and serves it.
- A wire contract, usually JSON.
- A frontend (TypeScript/React) that reads that JSON.
Names and types can drift at each boundary. People and coding agents both spend time keeping the copies aligned.
One field, written four times
completed_at, completedAt, and isDone are the same fact. Each boundary renames it or changes its type. A Vox table states it once, and every layer keeps that name and type.
These are the choices that follow from that, and what each one buys.
One declaration, projected. A second schema, written by hand, drifts, and an agent copying it drifts the same way. A table is the source. SQL, the server types, the JSON shape, and the TypeScript client are generated from it. vox build emits SQLite/Turso, Rust (Axum), and React/TypeScript, because one stack is what the tests can actually cover. Django, Vue, and other frameworks are outside that path.
Missing values and failures are typed. Generated code skips a failure it cannot see. Option[T] is Some(x) or None. Result[T] is Ok(x) or Error(msg). Code that ignores either case does not type-check. ? returns the error to the caller.
Ids are typed. A task id and a user id are different facts. A boundary takes Id[Task] rather than a bare string, so the two cannot be swapped.
Keywords open scopes. Decorators modify them. table, query, mutation, server, component, workflow, activity, tool, and resource each open a scope. @auth, @pure, @durable, and @uses change how a declaration runs. One spelling means people and agents copy the same form. A new behavior is a decorator, so the keyword list stays stable.
The same file runs now, or compiles. Scripts, repo automation, and the browser playground should start without a Rust build. A shipped app should be ordinary Rust and TypeScript. vox run interprets the file. --caps is the list of effects the host grants (filesystem, network, and the rest). vox build emits the database, the server, and the client from that same file. The two executors are still being matched, and a generated server build needs a Vox source checkout (VOX_REPO_ROOT).
A tool is a function in the same file. An agent tool kept in a side schema drifts like a hand-written JSON contract. tool is a typed function plus a short description. The program and an MCP client call that declaration, and a failure comes back as Result.
Measured comparison with TypeScript under multi-turn compiler feedback: see The central claim[^11].
A First Look at .vox Code & Dual Execution Lanes
Here is a complete, runnable .vox program declaring a relational table, a read query, an MCP-callable agent tool, a reactive UI component, and a script entrypoint in one file:
// 1. Relational schema: Vox automatically synthesizes a phantom-typed primary key (`Id[Task]`).
table Task {
title: str
done: bool
}
// 2. Read-only database query: compiled to a typed SQL read + HTTP GET route.
query get_tasks() to int {
return len(db.Task.all())
}
// 3. Agent & application tool: callable directly in Vox or exposed over Model Context Protocol (MCP).
// `Result[str]` makes failure explicit in the type signature; `?` propagates errors cleanly.
tool "Mark a task complete" complete(id: Id[Task]) to Result[str] {
db.Task.delete(id)?
return Ok("done")
}
// 4. Reactive UI component: projected to typed React 19 / TSX by `vox build`.
component TaskBoard() {
view: column(raw_class="task-card") {
heading(level=3) { "Active Tasks" }
text() { "Synchronized across SQLite/Turso, Rust/Axum, React/TSX, and MCP" }
}
}
// 5. Script entrypoint: executed immediately in memory by `vox run`.
fn main() to Result[str] {
let id = db.Task.insert({ title: "Learn Vox", done: false })?
print("Tasks queued: " + str(get_tasks()))
let status = complete(id)?
print("Tasks remaining: " + str(get_tasks()))
return Ok(status)
}
Two Execution Lanes for One Language
Instant Sandboxed Interpretation (vox run) vs. Full-Stack Native Emission (vox build)
The same type-checked AST lowers either to the in-memory capability-gated evaluator or to standalone SQL DDL, Rust/Axum server code, React/TSX components, and MCP tool schemas.
| Execution Lane | Command | Runtime & Security Boundary | Primary Use Cases |
|---|---|---|---|
| 1. Interpreter & Sandbox Lane | vox run file.voxvox run --interp --caps deterministic file.vox |
Evaluates the type-checked AST directly in memory with an embedded SQLite VoxDb instance and explicit object-capability grants (--caps)[^3]. Zero Cargo/rustc invocation. |
Fast local iteration, repository automation (scripts/*.vox), CI gates, and the public /v1/eval browser sandbox. |
| 2. Full-Stack Compile Lane | vox build file.vox -o distvox compile file.vox |
Emits SQLite/Turso DDL, a typed Rust (Axum) HTTP server (src/target/generated/), a React 19 / TypeScript client (dist/), and optional Tauri 2 desktop bundles[^1]. |
Shipped full-stack web applications, native desktop apps, and compiled integration test suites (vox test). |
Architecture & Separation of Concerns Across Repositories
Vox started as a single-file compiler, but empirically testing whether a language improves LLM code generation required building the surrounding agent orchestrator, trust-tiered knowledge base, operator console, and QLoRA evaluation harness.
Inside vox-foundation/vox, crates are organized into a strict 6-layer directed acyclic graph (L0–L5) enforced on every commit by vox-arch-check (docs/src/architecture/layers.toml, 0 circular dependencies):
| Architectural Area | Engineering Scope in vox-foundation/vox |
Primary CLI Entrypoints & Leaf/Core Crates |
|---|---|---|
1. Language & Compiler (L0–L1) |
Lexer, recursive-descent parser (57 EBNF productions), Hindley-Milner + effect/capability type checker[^1][^2], capability-sandboxed interpreter[^3], layout-safe formatter, LSP server, and Rust/Axum + React/TSX + SQL codegen + durable workflow replay journals[^4]. | vox check, vox run, vox build, vox emit, vox fmt, vox lsp, vox diagram, vox grammar (vox-ast, vox-compiler, vox-codegen, vox-workflow-runtime) |
2. Agent Harness & MCP (L2–L4) |
Multi-agent actor orchestrator (vox-orchestrator-d)[^5], 376-tool Model Context Protocol server (vox mcp)[^6], BLAKE3/HMAC-SHA256 formal-intent tool receipts (ADR-029), per-file hopper locks (ADR-025), and self-maintaining OpenRouter/local model routing[^7]. |
vox mcp, vox serve, vox chat, vox model, vox skill, vox plan (vox-orchestrator, vox-mcp-dispatch, vox-orchestrator-mcp, vox-skills) |
3. Trust-Tiered KB & Research (L1–L3) |
Curated documentation index combining Tantivy 0.22 BM25 with dense vector Reciprocal Rank Fusion (vox kb)[^8], 4 database-level retrieval trust tiers (SystemVerified → Untrusted), W3C SKOS + Nanopublication facets[^9], and steerable multi-source academic/web research. |
vox kb, vox research, vox scientia, vox graph (vox-db, vox-search-core, vox-search, vox-scientia-core, vox-scientia, vox-kb-facets) |
4. Native ML Lane — MENS (L3–L4) |
Pure-Rust (Candle) QLoRA fine-tuning[^10] across Qwen3 (0.6B–32B) on Metal, CUDA, and CPU; AST-verified <think> JSONL corpora (eval-gates-ladder.yaml); and paired McNemar + Holm statistical evaluation (vox model eval-compare)[^11]. |
vox mens train, vox mens serve, vox model eval-compare, vox populi (vox-populi, vox-ml-cli, vox-tensor) |
5. Governance, Crypto & Secrets (L0–L4) |
Application cryptography facade (vox-crypto: ChaCha20-Poly1305, BLAKE3, Ed25519), unified secret resolver (Clavis / vox secrets), static source-policy detectors (vox audit code), and architectural layer/retirement ratchets. |
vox doctor, vox ci, vox audit, vox secrets, vox shell check (vox-crypto, vox-secrets, vox-arch-check, vox-code-audit, vox-cli-core) |
Multi-Repository Separation of Concerns (vox-foundation)
To keep incremental Rust compile times fast (-28% to -89% via leaf facade splits), isolate heavy frontend/documentation toolchains, and enforce a hard air-gap around private telemetry while keeping vox 100% standalone offline, the ecosystem is federated across four repositories with strict Single-Source Documentation Ownership (README-SYNC-MAP):
| Repository | Visibility & License | Canonical Scope (What Lives Here) | What Does Not Live Here (Anti-Duplication Rule) |
|---|---|---|---|
vox-foundation/vox(This Repository) |
Public (Apache-2.0) |
Core .vox language, compiler, interpreter, CLI, MCP server, VoxDb (v97), MENS QLoRA engine, 33 crates.io-publishable crates, docs/src/ Markdown corpus, and the 48-row suite status matrix. |
Does not inline the 32 GUI screenshot tables (owned by vox-axis) or private ClickHouse/GPU billing adapters (owned by vox-ops). |
vox-foundation/vox-axis(Mirrors crates/vox-gui/) |
Public (Apache-2.0) |
Vox Axis Tauri 2 desktop workbench: all 32 SURFACE_REGISTRY views, the VRBS ROMA 3D/2.5D Codebase Simulator[^12], AQVAEDUCTUS hydraulic cascade, 4-profile WCAG theme contract (arcane, slate, glacier, high-contrast), and Local IPC / Remote TOFU TLS transport. |
Does not duplicate .vox language tutorials, EBNF grammar rules, or compiler status rows; links back to vox-foundation/vox. |
vox-foundation/voxlang.org(Mirrors docs-astro/) |
Public (Apache-2.0) |
Public Astro 7.4 + Starlight 0.42 site (voxlang.org), vox-doc-pipeline compiler-verified .vox doctests, Diátaxis + W3C SKOS taxonomy, /voxup bootstrap scripts, and the Coolify eval.voxlang.org /v1/eval deterministic sandbox. |
Does not duplicate hand-maintained CLI/MCP tables (*.generated.md are emitted from vox) or GUI surface catalogs. |
vox-foundation/vox-ops(Private Sibling Repo) |
Private (Proprietary) |
Optional remote OTLP/ClickHouse telemetry receiver (vox-ops-telemetry-ingest, telemetry.voxlang.org), Ed25519-signed leaderboard snapshots, and commercial spot GPU adapters (vox-plugin-cloud: RunPod, Vast.ai, Together AI). |
Zero compile or runtime edges into vox-foundation/vox (enforced by vox ci standalone-sovereignty); synced solely via 55 BLAKE3-hashed schemas (vox ci cross-repo-parity). |
Tradeoffs: Engineering Costs & Operational Constraints
The benefits of each language and harness decision are stated in Why Vox above. Below are the engineering costs and constraints those decisions impose:
| Design Choice | Engineering Cost & Operational Constraint |
|---|---|
Single-file full-stack projection (table, query, mutation, component, tool in one .vox module) |
Target stack lock-in. vox build targets SQLite/Turso, Rust/Axum, and React 19 / TypeScript exclusively. Teams requiring Django, Spring, or Vue cannot use the full-stack codegen lane. |
No null + mandatory Option[T] & Result[T] |
Upfront ceremony. Every fallible database read, HTTP call, or MCP tool invocation must be explicitly unwrapped, pattern-matched, or propagated with ? before vox check succeeds. |
Dual execution lanes (vox run --interp vs. vox build) |
Dual-backend parity & source-checkout dependency. Semantics between the AST interpreter and emitted Rust must be conformance-tested continuously, and compiling emitted Rust servers outside the workspace still requires VOX_REPO_ROOT. |
| 4-tier retrieval trust & cryptographic tool receipts | Promotion latency. External web scrapes land in kb_findings as Untrusted and cannot enter system prompts or MENS training sets until they clear the 5-stage Socrates verification gate. |
Federated multi-repo + 6-layer DAG (L0–L5) |
Uneven maturity across peripheral surfaces. While the core parser, interpreter, VoxDb, KB, and CI ratchets are Working, peripheral surfaces (mobile targets, hosted .vox package registry, multi-node QUIC mesh) remain Prototype or Research. |
| Pre-1.0 research velocity | Immediate retirement of legacy syntax. Superseded decorators (@table, @endpoint, @island) become immediate hard parse errors (vox audit retirement) rather than carrying multi-year deprecation shims. |
How It's Built & Project Stewardship
I'm the sole human maintainer, and I build Vox alongside AI coding agents (Claude Code, Cursor, Antigravity). That is a core part of the research thesis: roughly nine in ten commits are authored or co-authored by coding agents operating under mechanical architectural ratchets (vox-arch-check, vox-code-audit, vox-doc-pipeline, vox ci ssot-drift, and vox ci cross-repo-parity). When an adversarial audit finds that a surface is overstated, drifted, or incomplete, the critique is committed directly under docs/src/architecture/ and tracked to closure.
Vox is stewarded by the Vox Foundation (in formation). All code and documentation in vox, vox-axis, and voxlang.org are open source under the Apache 2.0 License. Community funding is managed transparently on Open Collective.
Status
Every surface is graded into one of four honest states:
- Working. Does its basic job reliably when tried and is covered by automated tests on
main. Not production-hardened; no long-term stability promise yet. - Prototype. Real implementation exists and works on primary paths, but expect rough edges, source-checkout requirements, or incomplete edge cases.
- Research. Exploratory or mid-redesign; not working end-to-end as intended yet.
- Not started. Planned only, or an unimplemented stub.
Verification pass (2026-11-10, commit b2ce949b4, tag v6.8): Every row in the six tables below was re-verified on 2026-11-10 against main via live CLI execution (vox check, vox run --interp --caps, vox fmt --check, vox grammar --format ebnf, vox diagram, vox emit, vox explain, vox features, vox kb status, vox shell check, vox repo status, vox repo catalog list, vox secrets doctor, vox doctor, vox audit retirement, vox ci cross-repo-parity, vox ci publish-dry-run, vox ci standalone-sovereignty, vox ci federated-symbol-graph) and the full 3-shard CI test suite (16,491 / 16,491 tests passing: Shard 1 5,469, Shard 2 5,316, Shard 3 5,706). Historical bug-level notes live in the suite status audit.
1. Language & compiler
| Component | State | Checked | Notes (2026-11-10 Verification) |
|---|---|---|---|
Parser & type checker (vox check) |
Working | 2026-11-10 | Verified live on examples/golden/hello.vox (Check passed with 0 warning(s)) and across the 128-program vox_think reasoning slice. Bare keywords (table, query, mutation, server, component, workflow, activity, actor, tool, resource) open scopes; @decorators (@pure, @auth, @durable, @uses, @ai) modify declarations. |
Interpreter & sandbox (vox run, --interp, --caps) |
Working | 2026-11-10 | Verified live via vox run --interp --caps deterministic examples/golden/hello.vox. Evaluates scripts and declaration-only modules (table/query/tool without fn main()), enforces capability grants (crates/vox-compiler/src/eval/caps.rs), equates Option::None == null, and powers scripts/*.vox and eval.voxlang.org. |
Full-stack codegen (vox build) |
Prototype | 2026-11-10 | Emits React 19 / TSX (dist/), a typed Rust/Axum server (src/target/generated/), and SQLite/Turso DDL; verified by TS emit typecheck (ts-noemit) in CI. Compiling generated Rust servers outside the workspace still requires a local Vox checkout via VOX_REPO_ROOT (design). |
OpenAPI & client emit (vox emit) |
Prototype | 2026-11-10 | Verified vox emit client (emits vox-client.ts, types, schemas, openapi.json) and vox emit openapi (standalone OpenAPI 3.1 JSON spec). Standalone component-only emit without server routes remains partial. |
Formatter (vox fmt) |
Prototype | 2026-11-10 | Verified live (vox fmt --check). Enforces the layout_only token-equivalence guard: refuses to overwrite any .vox file when formatting would alter non-whitespace tokens or drop unsupported comment trivia (hello.vox safely left unchanged on round-trip mismatch). |
Tests (vox test, @test) |
Prototype | 2026-11-10 | Lowers @test functions through Rust codegen + Cargo test execution; shares vox build's VOX_REPO_ROOT source-checkout requirement. |
REPL (vox repl) |
Prototype | 2026-11-10 | Extracted into crates/vox-cli-research/src/repl.rs (Phase 394) with capability-enforced evaluation (eval::caps). Evaluates single expressions; top-level let/fn bindings do not yet persist across REPL lines. |
Dev loop (vox dev) |
Working | 2026-11-10 | Watches .vox sources and triggers incremental rebuilds via vox-compilerd. |
Durable workflows (workflow / activity) |
Prototype | 2026-11-10 | VoxDbTracker in vox-workflow-runtime persists deterministic activity call ordinals, workflow.version patches (workflow_patch_log), signals (workflow_signal_log), and timers (workflow_run_log); codegen emits __vox_run_workflow (ADR-019, ADR-021, ADR-041). |
Desktop packaging (vox compile) |
Prototype | 2026-11-10 | Scaffolds and compiles Tauri 2 desktop bundles from .vox modules (including table declarations, #633). |
Mobile (--target mobile, React Native) |
Research | 2026-11-10 | vox compile --target mobile emits an Expo / React Native scaffold (Mobile EAS Build workflow is manual/opt-in); on-device runtime parity is not yet complete. |
LSP (vox lsp) |
Prototype | 2026-11-10 | vox-lsp provides diagnostics, hover, completion, document symbols, semantic tokens, and code actions (capabilities SSOT); cross-module go-to-definition remains partial. README updated in Phase 401. |
Scaffolding (vox init, vox new) |
Working | 2026-11-10 | Scaffolds new .vox projects and preset templates (vox new web) with Vox.toml, .voxignore, and starter src/main.vox. |
Packages (vox add / remove / lock / sync) |
Prototype | 2026-11-10 | Manages local Vox.toml dependencies and lockfiles (vox-pm). |
Package registry (vox pm) |
Not started | 2026-11-10 | CLI client (search, publish, vendor) exists, but no public Vox package registry is hosted yet. (Rust foundation crates publish to crates.io instead — 33 crates verified via vox ci publish-dry-run). |
Diagrams (vox diagram) |
Working | 2026-11-10 | Verified live (check, fmt, render deterministic SVG, export Mermaid, import Mermaid, #681). Powers structured diagrams across docs/src/. |
Grammar export (vox grammar) |
Working | 2026-11-10 | Verified live (vox grammar --format ebnf): auto-generates 57 EBNF production rules directly from parser/descent/, plus Lark and JSON Schema formats. |
Deploy & share (vox deploy, vox share) |
Prototype | 2026-11-10 | vox deploy targets OCI, Docker Compose, Kubernetes, or SSH from Vox.toml [deploy]; vox share is modularized in crates/vox-cli-share. |
2. Agent harness & orchestration
| Component | State | Checked | Notes (2026-11-10 Verification) |
|---|---|---|---|
Orchestrator daemon (vox-orchestrator-d) |
Prototype | 2026-11-10 | Supervises agent lifecycles, SQLite file-affinity resource locks (hopper_inbox.resource_id, ADR-025), and persistent term.* PTY sessions (crates/vox-cli-research/src/daemon_tool.rs). |
MCP server & HTTP gateway (vox mcp, vox serve) |
Prototype | 2026-11-10 | Dispatches all 376 canonical MCP tools (contracts/mcp/tool-registry.canonical.yaml) through the modularized dispatch_domains/*.rs & vox-mcp-dispatch leaf crate (Phase 392), verified by yaml_registry_tools_have_dispatch_match_arms and real_files_yield_sane_counts. Emits BLAKE3/HMAC receipts (ADR-029). |
Model registry & routing (vox model) |
Working | 2026-11-10 | Verified live (discover, rollup, scoreboard, list, show, preferences, explain, bench, eval, eval-compare). Routes via vox_actor_runtime::llm using live OpenRouter ~family-latest aliases (contracts/orchestration/model-defaults.v1.yaml, #682) and snake_case task categories (code_gen, debugging, research, planning). |
Chat (vox chat) |
Prototype | 2026-11-10 | Multi-turn CLI/GUI chat routed through vox_actor_runtime::llm with relevance-ranked tool offering (#686), BPE context compaction receipts, and retrieval trust-tier filtering. |
Capability discovery (vox explain, vox features) |
Working | 2026-11-10 | Verified live: vox explain check and vox features resolve CLI/MCP/GUI equivalents across compiler, orchestrator, mesh, ml, and research from contracts/capabilities/capability-index.v1.json. |
Harness eval (vox harness eval) |
Working | 2026-11-10 | Evaluates agent harness trajectories and tool-selection accuracy against offline golden tasks. |
Skills (vox skill) |
Prototype | 2026-11-10 | Discovers and indexes agentskills.io SKILL.md directories (crates/vox-skills/skills/superpowers/ and crates/vox-plugin-catalog/catalog.toml); validated by vox ci agentskills-compliance and plugin-skill-parity. |
Plugins & bundles (vox plugin, vox bundle) |
Prototype | 2026-11-10 | Manages loadable capability bundles and MENS hardware backend plugins (mens-candle-metal, mens-candle-cuda, mens-candle-cpu); verified by distribution-parity CI gate. |
Policy & exec-policy (vox policy, vox shell check) |
Working | 2026-11-10 | Verified live (vox shell check --payload "cargo test -p vox-cli" → shell check: OK (exec policy)) and across all 184 ci-gate rows in contracts/policy/policy-registry.v1.yaml (parity_passes_for_default_domains_against_committed_yaml). |
Planning / rollback (vox plan, vox rollback) |
Prototype | 2026-11-10 | Generates structured execution plans and coordinates state rollback over vox-orchestrator-d. |
Identity & auth (vox auth, vox login) |
Prototype | 2026-11-10 | Manages local Clavis vault credentials (vox login / vox logout); multi-tenant cloud auth remains unexercised. |
3. Knowledge base, search & research tools
| Component | State | Checked | Notes (2026-11-10 Verification) |
|---|---|---|---|
Curated KB Library (vox kb, vox_kb_*) |
Working | 2026-11-10 | Verified live (vox kb status: Tantivy 0.22 lexical backend + kb_ids-sections-v2 chunker, vox_kb_search / get / cite). Schema baseline 97; legacy VoxKB CRUD tools are retired (0 legacy entries). |
| Retrieval trust tiers & findings inbox | Working | 2026-11-10 | Enforces 4 database-level tiers (SystemVerified, Trusted, Advisory, Untrusted) on search_documents.trust_tier and quarantines external web findings in kb_findings (vox-search-core leaf split in Phase 398). |
Deep & quick research (vox research) |
Prototype | 2026-11-10 | Dispatches steerable multi-source retrieval across OpenAlex, arXiv, Wikipedia, SearXNG, and Tavily with per-provider RRF diversity caps and domain-misguidance decay penalties. |
SCIENTIA & publication (vox scientia) |
Prototype | 2026-11-10 | Split into vox-scientia-core (L1 leaf types) and vox-scientia (Phase 398) to decouple evidence types from heavy HTTP/LLM pipelines. Supports claim-span checks and manuscript scaffolding (vox-manuscript-scaffold). |
| Socrates evidence gate | Prototype | 2026-11-10 | 5-stage human-in-the-loop verification stepper (Planning → Retrieving → Verifying Claims → Judge Inspector → Sentry Audit) wired into task submission and surfaced in the Axis research and needs-you views. |
Code & symbol graph (vox graph) |
Working | 2026-11-10 | Verified live alongside vox ci federated-symbol-graph: indexes 404 symbol nodes (crates, tools, contracts) and 227 cross-repo edges across vox, vox-axis, voxlang.org, and vox-ops into .vox/cache/federated-symbol-graph.v1.json. |
Multi-repo catalog (vox repo, vox catalog) |
Working | 2026-11-10 | Verified live (vox repo status and vox repo catalog list): resolves all 4 federated repositories (vox, vox-axis, voxlang.org, vox-ops) from .vox/repositories.yaml via vox-repository-core (Phase 393). |
4. Interfaces
| Component | State | Checked | Notes (2026-11-10 Verification) |
|---|---|---|---|
Operator GUI (vox-gui, Vox Axis / Tauri 2) |
Prototype | 2026-11-10 | Dedicated repository at vox-foundation/vox-axis (crates/vox-gui/README.md). Ships 32 catalog-generated views in the v6.6 Sunlit Imperial Roman Carrara White & Gold design system, the VRBS ROMA 3D/2.5D Codebase Simulator[^12], AQVAEDUCTUS 3-tier hydraulic cascade, and 4-profile WCAG theme contract (10/10 Playwright visual regression checks passing). |
Terminal sessions (vox term, vox-terminal-core) |
Prototype | 2026-11-10 | Ratatui terminal shell backed by daemon-hosted SessionHost and term.* ring-buffer replay RPCs (#641). |
| Public docs site (voxlang.org) | Working | 2026-11-10 | Dedicated repository at vox-foundation/voxlang.org (docs-astro/README.md). Astro 7.4.5 + Starlight 0.42.9 + starlight-links-validator 0.27.0 + dual-chevron collapsible reader layout (#687); verified by Docs Quality CI gate. |
Browser eval sandbox (eval.voxlang.org) |
Working | 2026-11-10 | Executes untrusted browser snippets via vox run --interp --caps deterministic behind /v1/eval, deployed on Coolify (vox ci coolify-eval sync-compose --compose vox-eval.compose.yml). |
VS Code extension (vox-vscode) |
Prototype | 2026-11-10 | Located in apps/editor/vox-vscode/ (README audited in Phase 401); connects to vox lsp. Not yet published to the VS Code Marketplace. |
Installer & updater (voxup, vox upgrade) |
Prototype | 2026-11-10 | /voxup and /voxup.ps1 bootstrap scripts are served and Playwright-tested on voxlang.org with Clavis forge token resolution. No stable release tag yet; build from source. |
Speech-to-code (vox speech / vox oratio) |
Research | 2026-11-10 | Delegates to vox-ml-cli (vox-speech / vox-tauri-stt) for ASR filler normalization and spoken-operator lowering. |
Visual review (vox visus) |
Research | 2026-11-10 | Feature-gated behind --features dei for multimodal UI screenshot inspection. |
5. ML lane (MENS)
| Component | State | Checked | Notes (2026-11-10 Verification) |
|---|---|---|---|
Fine-tuning (vox mens train) |
Prototype | 2026-11-10 | Verified CLI & preset contracts (contracts/mens/training-presets.v1.yaml, including qwen3_6g and qwen3_12g VRAM presets). select_mens_backend routes across mens-candle-metal (handling untied Qwen3 lm_head.weight), mens-candle-cuda, and mens-candle-cpu. |
Serving (vox mens serve) |
Prototype | 2026-11-10 | Registered in vox-ml-cli; serves local non-streaming /v1/completions and /generate endpoints. |
Corpus & statistical eval (eval-corpus, vox model eval-compare) |
Working | 2026-11-10 | Verified 128-row BLAKE3-pinned benchmark slices (mens/config/eval-gates-ladder.yaml: gsm8k_think, math500_think, and vox_think with pure non-trivial .vox programs verified by the_ladder_pins_every_slice_and_the_checked_in_files_match and programs_are_pure_and_nontrivial). Paired McNemar + Holm + bootstrap evaluation runs via vox model eval-compare[^11]. |
| Quantization / GGUF export | Prototype | 2026-11-10 | merge-qlora --gguf-out exports merged adapters via vox-quantize / llama.cpp tooling. |
Mesh control plane (vox populi) |
Prototype | 2026-11-10 | Verified live: vox populi delegates to vox-ml-cli when compiled with --features populi (default vox-ml-cli build without --features populi omits the subcommand). Multi-node Iroh QUIC mesh transport remains experimental (ADR-047). |
| Grammar-constrained decoding | Not started | 2026-11-10 | vox-constrained-gen exists as a standalone crate (crates.io dry-run verified), but is not yet wired into vox mens serve or vox scientia publication emission. |
| Published adapters (Hugging Face) | Prototype | 2026-11-10 | Public cards & anonymous fetch verified (crates/vox-populi/tests/hf_metadata_rules.rs): Qwen3 0.6B, 1.7B, 4B, and the adapter index. vox mens hub download requires --features mens-hf-hub. |
6. Dev infrastructure
| Component | State | Checked | Notes (2026-11-10 Verification) |
|---|---|---|---|
CI gate runner (vox ci) |
Working | 2026-11-10 | All 22 GitHub Actions jobs passed on main (b2ce949b4), including CI/Linux, 3 test shards (16,491 tests), ssot-autoregen, publish-dry-run (33/33 crates.io crates pass), cross-repo-parity (55/55 shared contracts), standalone-sovereignty, and federated-symbol-graph. |
Architecture checker (vox-arch-check) |
Working | 2026-11-10 | Verified via vox audit arch: enforces docs/src/architecture/layers.toml, 0 dev-dependency cycles (Phase 389), and leaf facade splits (vox-cli-core, vox-mcp-dispatch, vox-repository-core, vox-search-core, vox-scientia-core). |
Drift checker & docs pipeline (vox-doc-pipeline) |
Working | 2026-11-10 | Verified in Docs Quality CI (0 errors across 907+ docs): enforces YAML frontmatter, W3C SKOS topic/domain facets, shrink-only facet backlog, executable .vox doctests, and why_vox byte-parity with docs/src/index.mdx. |
Source-policy & effort audits (vox audit) |
Working | 2026-11-10 | Verified live (vox audit retirement, vox audit arch, vox audit code across all 3 CR-L8 CI shards): enforces vox-crypto boundaries, vox_actor_runtime::llm vendor-hostname bans, and GUI theme-contract rules. |
Secrets (Clavis, vox secrets) |
Working | 2026-11-10 | Verified live (vox secrets doctor, vox ci secrets-parity, vox ci secret-env-guard): enforces vox_secrets::resolve_secret and flags unmanaged .env keys for vault migration. |
Local database (VoxDb, vox-db) |
Working | 2026-11-10 | Schema baseline 97 (vox_db::schema::BASELINE_VERSION and contracts/db/baseline-version-policy.yaml): includes kb_findings, search_documents.trust_tier, workflow_patch_log, model_benchmark_results, and hopper_inbox.resource_id. |
Environment & build diagnostics (vox doctor) |
Working | 2026-11-10 | Verified live (vox doctor, modularized in crates/vox-cli-diagnostics): validates Rust 1.98.1, Node/pnpm, .voxignore sync, secrets-parity, secret-env-guard, --caps executor support, and binary freshness. |
The central claim
| Component | State | Checked | Notes |
|---|---|---|---|
| Evidence that Vox improves LLM code generation | Working | 2026-11-10 | Benchmark harness & 128-row BLAKE3-pinned vox_think slice verified on 2026-11-10; latest empirical run (2026-10-14, Empirical Benchmark: Vox vs. TypeScript under Multi-Turn Compiler Feedback, $N=100$, McNemar $p = 0.0031$) achieved Pass@1 82.0% vs. TypeScript 68.0%, and Pass@3 94.0% vs. 81.0%[^11]. |
Longer-horizon targets: v1.0 release criteria · Stability Matrix · Flywheel & Multi-Repo SSOT.
Log
Newest first.
- 2026-11-10: Re-verified all 48 rows of the Status tables on
main(b2ce949b4, tagv6.8,16,491 / 16,491tests passing across 3 CI shards); generated bespokev6.6Sunlit Imperial Roman Carrara White & Gold artwork and animated.webptours for each of the 4 repositories (vox,vox-axis,voxlang.org,vox-ops) so zero animations or hero banners are duplicated across repos; eliminated all machine-local/Users/...paths from satellite READMEs/scripts; and updated GitHub repository descriptions, homepages, and topics acrossvox-foundation. - 2026-11-10: Completed Milestones
v6.7&v6.8(Phases 387–401, Flywheel & Multi-Repo SSOT): federated the workspace acrossvox-foundation/vox,vox-foundation/vox-axis,vox-foundation/voxlang.org, and privatevox-ops; extractedvox-cli-core,vox-mcp-dispatch,vox-repository-core,vox-search-core, andvox-scientia-core(cutting warm incremental leaf check/test times by 28%–89%); expandedcrates.iodry-run verified crates from 2 to 33 (vox ci publish-dry-run); adversarially audited all 46 repository and sub-crateREADME.mdfiles withREADME-SYNC-MAPdomain ownership and footnoted prior-art attribution; and updated Vox Axis (crates/vox-gui/README.md) with 50v6.6Roman White & Gold Playwright captures and theVRBS ROMA3D/2.5D Simulator. - 2026-11-02: Why Vox states the reason and the benefit for each language choice (one declaration,
Option/Result,Id[T], keywords versus decorators,vox runversusvox build, andtoolas a function). The same text is synced to thevoxlang.orghomepage. - 2026-11-02: Verified published Qwen3 adapters on Hugging Face (0.6B, 1.7B, 4B, index),
VoxDbschema baseline97, relevance-ranked chat tool offering (#686), and dual-chevron docs sidebars (#687). - 2026-10-31: Re-verified tutorials and docs CI on the mounted roadmap (
#683). Model defaults moved from pinned versions to live~family-latestaliases (#682). - 2026-10-30: VoxDiagram, a typed diagram DSL, replaced Mermaid as the authoring surface. Mermaid stays an import/export target (
#681). - 2026-10-19: Closed the v1.7 social/leaderboard split, the v1.9 five-spoke MENS evaluation, and the v2.0 eight-spoke benchmark (phases 89–111), plus the v1.8 operator-GUI surface pass.
- 2026-10-16: Closed the v1.5 unified stream and the v1.6 MENS flywheel (phases 01–88).
- 2026-10-14: Replaced the abstract spaghetti diagram with a 4-layer schema-fragmentation schematic, added
schema_version: 1acrosscontracts/profiles/*.v1.yaml(CR-A2100%), made thevox-doc-pipelinedrift baseline resilient to line-number shifts, and cleared thestdlib-coveragefalse positive intutorial-test-runner.vox. - 2026-10-13: Fixed the browser playground
/v1/evalsandbox (vox run --interpnow registerstool/resource/@exampledeclarations, handles declaration-only modules withoutfn main(), and passes--caps deterministic), and updated Coolify deployment triggers in.github/workflows/deploy-hetzner.ymlandvox ci coolify-eval. - 2026-10-13: Completed
v1.5Wave 0 unified branch convergence (Phase 05) atVoxDbschema baseline96and regenerated all CLI, MCP, and capability contracts. - 2026-10-12: Merged
feat/true-workflow-durability(host-bridge workflow execution, run-stable per-function activity call ordinals, SQL-persistedworkflow.versionpatches,workflow_signal_logsignal parking,workflow_run_logtimer parking, and generatedVoxDbTracker/__vox_run_workflow) andwip/fmt-safety-2026-10-12(comment preservation andlayout_onlytoken-equivalence guard invox fmt). - 2026-10-11: Landed
Phase 12code-generation benchmark & provenance plumbing (12-01..12-08): seeded sampling (seed,top_p) throughvox_actor_runtime::llmand Candle samplers, unbiasedpass@kineval-local, schema-2 completeness-gated eval reports, QLoRA adapter lineage cards,vox model eval-compare(McNemar, Holm, paired bootstrap), and multi-turn compiler-feedback repair ineval-corpus. - 2026-10-10: Landed Remote Axis and capability profiles (
vox serve --bind/--tls-cert/--tls-key/--behind-tunnel,/v1/profile,GatewayClientwith TOFU TLS certificate pinning, keyring token storage, and daemon-backed GUI surfaces) plus daemon-hosted terminal sessions (vox-terminal-core,SessionHost,term.*RPCs with ring-buffer replay,#641). - 2026-10-09: Completed KB Phases 1–4 (
#645) and Discoverability Phases 06.1–06.3: Tantivy 0.22Libraryindex (vox kb,vox_kb_search/get/cite), four-tier retrieval trust enforcement (SystemVerified..Untrusted) andkb_findingsquarantine inbox, SKOS taxonomy (contracts/documentation/kb-taxonomy.v1.yaml), generated capability index (vox explain,vox features), and the GUI⌘KOmnibar. - 2026-10-06: Unblocked
voxlang.orgCloudflare deployments and completed Docs Freshness v1.3 (Phases 20–24,#635,#640). - 2026-10-02: Completed Phase 5 (
MESH-01,TRUST-01): cryptographicvox-cryptoHMAC receipts around every MCP tool dispatch (vox_verify_task_claims, ADR-029) and SQLite hopper resource locks (hopper_inbox.resource_id, ADR-025). - 2026-09-27: Landed end-to-end multi-source chat and deep research (
OpenAlex,arXiv,Wikipedia,SearXNG,Tavily) and Qwen3 untiedlm_head.weight+mens-candle-cpuplugin fixes in MENS. - 2026-09-22: Fixed generated Axum handler parameter typing, DB-writing mutations (
db.T.insert(...)?), starter app-lane routing invox run,vox doctorexit codes, externalVOX_REPO_ROOTresolution in generatedCargo.toml, andOption::None == nullequality in the interpreter. - 2026-09-21: Audited the whole suite against the code (findings and bug handoff) and rewrote this README around dated 4-state tables.
- 2026-09-08: ADR-048 makes the interpreter the execution and sandbox tier, retiring the WASM, container, and microVM isolation modes.
- 2026-08-09: Core-syntax convergence (
#469). - 2026-06-30: Retired
@-decorator spellings became hard parse errors; data-layer declarations are now bare keywords. - 2026-05-26:
v0.6.0(CHANGELOG):@endpointretired, telemetry unified, single-machine multi-agent orchestration. - 2026-05-12: The Tauri operator GUI replaced the old Axum dashboard.
- 2026-05-08: Plugin system redesign: slim core, runtime-loadable plugins, skill marketplace.
- 2026-02-17: Git history begins, with an import of the initial compiler (lexer, parser, type checker, LSP, and Rust/TypeScript codegen).
Trying It
Because Vox is pre-1.0, there is no stable release tag yet. Build vox from source with Cargo. Draft nightly GitHub releases are not the supported install.
Prerequisites
- Rust
1.98.1(automatically selected byrustupviarust-toolchain.toml) and your platform's standard C compiler (xcode-select --installon macOS,build-essentialon Ubuntu/Debian, or Visual Studio C++ Build Tools on Windows). - Node.js and
pnpm(optional for.voxscripts and the interpreter lane; required only when bundling generated React frontends or building thevox-guidesktop app).
1. Build and Install the vox CLI
git clone https://github.com/vox-foundation/vox.git
cd vox
cargo install --locked --path crates/vox-cli
vox doctor
2. Run a .vox Program Immediately (Interpreter Lane)
The built-in interpreter requires no frontend bundler or secondary Rust compilation step:
vox check examples/golden/hello.vox
vox run --interp --caps deterministic examples/golden/hello.vox
3. Scaffold and Build a Full-Stack Application (Codegen Lane)
To generate a complete TypeScript/React frontend and Rust/Axum backend from a single .vox module:
vox init my-app
cd my-app
vox check src/main.vox
vox build src/main.vox -o dist
- The generated TypeScript and React 19 components are written to
dist/. - The generated Rust (Axum) HTTP server and SQLite/Turso schema are written to
src/target/generated/.
Things to keep in mind (
2026-11-10):
- Running
vox run src/main.voxon a module containingcomponentorserverdeclarations selects the app lane, which bundles the React frontend and requirespnpmin yourPATH. Usevox run --interpto force pure interpreter evaluation.- When compiling a generated Rust server outside the Vox repository, keep your local
voxsource clone on disk (or setVOX_REPO_ROOTto point to it) so Cargo can resolve Vox's runtime crates.
More details: Installing Vox · Getting Started Tutorial · First Full-Stack App.
The CLI
Vox exposes a unified CLI covering compilation, agent orchestration, knowledge-base indexing, model routing, diagram authoring, and CI guardrails.
- First-time discovery: Run
vox commands --recommendedto list core everyday commands, orvox featuresandvox explain <term>to search the capability index across CLI commands, MCP tools, skills, and crates. - Full reference: Every
vox,vox ci,vox kb,vox model,vox diagram,vox populi, andvox menssubcommand is generated directly from the Rust clap surface intodocs/src/reference/cli.mdanddocs/src/reference/cli-command-surface.generated.md.
Contributing
Curiosity, bug reports, sceptical benchmarks, and experiments are welcome. Expect internals to move quickly.
- Start here: Contributor Hub
- Where code lives: Concept-to-Crate Lookup Table and Architectural Layers (
layers.toml) - CI & quality gates: TOESTUB Contributor Guide
- Agent & contributor policy:
AGENTS.md
Sponsors
Apache-2.0 project. Maintainer: Bertrand Reyna-Brainerd. GitHub org: Vox Foundation (legal entity still in formation). Sponsorship pays for eval.voxlang.org, CI, and vox model eval-compare runs.
- Open Collective · GitHub Sponsors · Grant notes
- Suggested amounts, if you want a default: $500/mo, $50/mo, or $5/mo. The ledger is public.
License & Contact
Licensed under Apache 2.0. Questions and bug reports: GitHub Issues. Support the Vox Foundation: Open Collective.
Intellectual Lineage, Prior Art & References
Vox synthesizes established ideas from programming language theory, distributed systems, information retrieval, and agentic software engineering. We explicitly credit the systems, papers, and authors whose work informs each layer of the stack:
[^1]: Unified Reactive Schema & Typed Id[T] Projection (table, query, mutation, server): Co-locating the relational schema, transactional server queries/mutations, and phantom-typed primary keys (Id[Task]) draws directly from Convex (James Cowling, Sujay Jayakar, & Jamie Turner, 2021–2026), Blitz.js / TanStack Start zero-API RPC projections, and Ezra Cooper, Sam Lindley, Philip Wadler, & Jeremy Yallop, "Links: Web Programming Without Tiers", FMCO 2006.
[^2]: Algebraic Error Handling & Effect Modifiers (Option[T], Result[T], @pure, @uses): Replacing null and unchecked exceptions with sum types and ? propagation follows Rust (std::option::Option, std::result::Result), OCaml / Haskell (Maybe / Either), and algebraic effect row polymorphism from Koka (Daan Leijen, "Koka: Programming with Row Polymorphic Effect Types", MSFP 2014).
[^3]: Capability-Sandboxed Interpreter (vox run --interp --caps): Denying ambient authority in scripts and the /v1/eval browser sandbox unless granted via --caps follows Jack B. Dennis & Earl C. Van Horn, "Programming Semantics for Multiprogrammed Computations", CACM 9(3), 1966, Mark S. Miller's object-capability security model (Robust Composition, PhD dissertation, Johns Hopkins, 2006), and the Bytecode Alliance WASI capability model.
[^4]: Durable Execution & Deterministic Replay (workflow, activity, VoxDbTracker): Persisting per-function call ordinals, version patches (workflow.version), signals, and timers to a replay journal builds on Temporal / Uber Cadence (Maxim Fateev & Samar Abbas) and Sebastian Burckhardt et al., "Durable Functions: Semantics for Stateful Serverless", OOPSLA 2021.
[^5]: Actor Supervision & Hopper Lock Coherence (actor, vox-orchestrator, ADR-025): Message-passing actor isolation and supervision draw from Carl Hewitt, Peter Bishop, & Richard Steiger (IJCAI 1973) and Joe Armstrong's Erlang/OTP supervision trees (Making Reliable Distributed Systems in the Presence of Software Errors, 2003).
[^6]: Model Context Protocol & Portable Agent Skills (tool, resource, vox mcp, vox skill): Compiler-emitted tool/resource schemas target Anthropic's Model Context Protocol (MCP) specification; portable SKILL.md directories follow the open agentskills.io specification and Jesse Vincent's Superpowers agentic workflow library (crates/vox-skills/skills/superpowers/).
[^7]: Multi-Provider LLM Routing & Static Hygiene (vox model, vox-code-audit): Self-maintaining OpenRouter/local model routing and static V8/CSS/SQL transfer-budget detectors adapt patterns from Theo Browne's pingdotgg/t3code and Vibhek Soni's vibheksoni/t3router (see t3-vox-toestub-rules-and-enforcement-research-2026.md).
[^8]: Hybrid Lexical + Semantic Retrieval (vox-search, vox kb): Combining BM25 inverted indexes (Tantivy, Paul Masurel / Quickwit) with dense embeddings via Reciprocal Rank Fusion (RRF) follows Gordon V. Cormack, Charles L. A. Clarke, & Stefan Buettcher, "Reciprocal Rank Fusion Outperforms Condorcet and Individual Rank Learning Methods", ACM SIGIR 2009.
[^9]: Controlled Taxonomies, Nanopublications & Diátaxis (vox-kb-facets, vox-doc-pipeline): Documentation structure follows Daniele Procida's Diátaxis framework; controlled topic/domain facets follow W3C SKOS (Miles & Bechhofer, 2009); and machine-verifiable assertion/provenance blocks draw from Paul Groth, Andrew Gibson, & Jan Velterop, "The Anatomy of a Nanopublication", 2010.
[^10]: Pure-Rust QLoRA Fine-Tuning (vox mens, vox-populi): Low-rank quantized adapter training in pure Rust builds on Tim Dettmers, Artidoro Pagnoni, Ari Holtzman, & Luke Zettlemoyer, "QLoRA: Efficient Finetuning of Quantized LLMs", NeurIPS 2023, Hugging Face Candle (Laurent Mazare), and the Qwen3 base model family (Alibaba Cloud Qwen Team).
[^11]: Unbiased pass@k & Paired Non-Parametric Evaluation (vox model eval-compare): Unbiased pass@k estimation follows Mark Chen et al., "Evaluating Large Language Models Trained on Code" (Codex, 2021); paired binary significance testing uses Quinn McNemar (Psychometrika 12(2), 1947) with Sture Holm's step-down multiple-testing correction (Scand. J. Stat. 6(2), 1979).
[^12]: 3D Software City Metaphor & Imperial Roman Civic Architecture (VRBS ROMA, AQVAEDUCTUS, Vox Axis): Representing live software modules, crates, and agent workstreams as an interactive 3D/2.5D city draws from Richard Wettel & Michele Lanza, "Visualizing Software Systems as Cities" (CodeCity, VISSOFT 2007), combined with the Severan Marble Plan (Forma Urbis Romae, c. 203–211 CE), Vitruvius's De Architectura (firmitas, utilitas, venustas), and Impressions Games' Caesar III (1998) civic walker/inspector loop.
Reviews (0)
Sign in to leave a review.
Leave a reviewNo results found