Skip to content

installation.md

Latest commit

 

History

History
266 lines (197 loc) · 9.78 KB

installation.md

File metadata and controls

266 lines (197 loc) · 9.78 KB
Raw
title Installing Vox
description The single canonical guide to installing the Vox CLI and toolchain on macOS, Linux, or Windows, and what each install path actually does today.
category Getting Started
status current
training_eligible true
schema_type TechArticle

Installing Vox

This is the canonical installation page. Every other install snippet in the repository is one command plus a link back here.

Vox is pre-1.0 (workspace version 0.6.0). The path that works today is cargo install from a checkout. voxup is the intended rustup-style installer, but there are no published GitHub Releases for it to download — see Packaging status.

Quick install (from source)

Prerequisites: Rust 1.98.1 (rust-toolchain.toml; workspace rust-version is 1.96), Node.js >= 18 (frontend scaffolding), pnpm >= 9, and a C compiler (gcc / clang / MSVC).

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

Always pass --locked: it installs against the workspace Cargo.lock. This exact argument vector is the CARGO_INSTALL_CLI_FROM_SOURCE constant in crates/vox-cli/src/utils/install_policy/mod.rs.

Restart your terminal if vox is not on PATH, then verify:

vox --version

cargo install puts vox on your Cargo bin path (~/.cargo/bin by default).

Planned: voxup (not working end-to-end)

When a published (non-draft) GitHub Release exists, voxup is the intended one-liner. Do not pipe the live URL into a shell today — https://voxlang.org/voxup has 404'd, and voxup ignores draft releases that CI creates.

The in-repo scripts (no arguments, no flags) are what the published URLs will serve:

sh scripts/install.sh        # macOS / Linux
.\scripts\install.ps1        # Windows (PowerShell)

docs-astro/public/voxup and docs-astro/public/voxup.ps1 must stay byte-identical to scripts/install.sh and scripts/install.ps1 (enforced by documented_install_urls_are_served). Edit one, copy to the other in the same commit.

What the script will do once releases exist:

  1. Detect your platform and map it to a release target (x86_64-unknown-linux-gnu, x86_64-apple-darwin, aarch64-apple-darwin, x86_64-pc-windows-msvc). aarch64 Linux has no release asset and the script tells you to build from source.
  2. Query the GitHub Releases API for the newest published release of vox-foundation/vox (drafts are skipped).
  3. Download voxup-<tag>-<target>.tar.gz and checksums.txt, and verify SHA-256.
  4. Extract and run voxup install default.

Targets and artifact layout: binary release contract.

When that path works, it will install:

Path Contents
~/.vox/bin/vox The Vox CLI (real binary from the release archive)
~/.vox/bin/vox-lsp The standalone Language Server Protocol binary — vox lsp and editor integrations (e.g. the VS Code extension) spawn this from PATH
~/.vox/bin/voxup The installer binary (used by voxup update)
~/.vox/toolchains/vox-<version>/ Versioned toolchain directory
~/.vox/toolchains/active Active version number (plain text)

~/.vox/bin is appended to your shell PATH. Update with voxup update once a newer published release exists.

Building from source (development)

For a development build without installing:

cargo build -p vox-cli

Installing voxup itself from source

cargo install --locked --path crates/voxup
voxup install default

Beyond the CLI

cargo install --locked --path crates/vox-cli and voxup give you the CLI only. vox doctor will keep reporting these as missing until you add them separately — see CONTRIBUTING.md for the full table.

The one that is easy to get wrong:

cargo install --locked --path crates/vox-ml-cli --features populi

populi is a non-default feature of vox-ml-cli. A bare cargo install --path crates/vox-ml-cli compiles the default mens-base feature set and yields a binary with no mesh transport, so vox populi cannot serve. The path and required feature are recorded as SOURCE_INSTALL_ML_CLI_REL_PATH and CARGO_INSTALL_ML_CLI_FROM_SOURCE in crates/vox-cli/src/utils/install_policy/mod.rs.

The Language Server (vox lsp)

vox lsp (crates/vox-cli/src/commands/lsp.rs) does not run the language server in-process — it spawns a separate vox-lsp binary from PATH and proxies its stdio. cargo install --locked --path crates/vox-cli does not build or install vox-lsp; you must install it separately:

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

Once published releases exist, voxup's default and full tiers install vox-lsp alongside vox automatically (see the Packaging status table above for why the one-liner doesn't work yet). The VS Code extension (apps/editor/vox-vscode) defaults to cargo run -p vox-lsp --release -- in a dev checkout, or a custom vox.lsp.serverPath setting pointing at an installed vox-lsp binary.

Packaging status

Channel Status today
cargo install --locked --path crates/vox-cli Working. Requires a checkout and a Rust toolchain.
voxup one-liner (https://voxlang.org/voxup, /voxup.ps1) Not published. Script exists in-repo; live URL has 404'd; voxup needs a published (non-draft) GitHub Release.
GitHub Release archives Not published. CI can create draft releases; nothing is published for voxup to consume.
Homebrew tap Not published. The release job builds and hashes a macOS tarball but the tap-update step is a placeholder; no vox-foundation/homebrew-vox formula is dispatched.
Windows .msi Not published. The cargo wix --no-build job has no preceding cargo build --profile dist, so it has no binary to package, and nothing is uploaded.
Debian .deb Not published. cargo deb does build the package, but no step uploads it to the release.

Do not tell users to brew install, download an .msi, or apt install vox until those jobs actually publish artifacts.

Verify your environment

vox doctor
Check Required? How to fix
Rust 1.98.1 (rust-toolchain.toml; workspace rust-version is 1.96) Yes rustup.rs
Node.js >= 18 Optional nodejs.org
pnpm >= 9 Optional pnpm.io
Git Yes git-scm.com
C compiler (MSVC / gcc / clang) Yes Platform-specific, see below
clang / LLVM Optional The workspace patches aegis with pure-rust defaults, so a typical Windows + MSVC build does not need clang-cl for Turso. Install LLVM only if you hit a toolchain that still expects native crypto builds.
Google AI Studio key Recommended Free at aistudio.google.com/apikey
OpenRouter key Optional openrouter.ai/keys
Ollama Optional ollama.com
VoxDB directory writable Yes ~/.vox/ must exist and be writable

Example output:

  ✓  Rust / Cargo              cargo 1.98.1
  ✓  Node.js                   v20.11.0 (>= v18)
  ✓  pnpm                      v9.1.0 (>= v9)
  ✓  Git                       git version 2.44.0
  ✓  C Compiler                MSVC Build Tools found
  ✓  Google AI Studio Key      configured (free Gemini models available)
  ○  OpenRouter Key (optional) not configured
  ○  Ollama Local (optional)   not running
  ✓  VoxDB directory           C:\Users\you\.vox (writable)

  ✓ All checks passed — you're ready to build with Vox!

AI provider keys

Vox uses a three-layer model cascade — you get free AI with just a Google account.

Layer 1: Google AI Studio (free, primary)

No credit card required. Provides Gemini 2.5 Flash, Flash-Lite, and Pro.

export GEMINI_API_KEY=YOUR_KEY

Layer 2: OpenRouter (optional)

A free key unlocks dozens of :free models; a paid key unlocks frontier models.

export OPENROUTER_API_KEY=YOUR_KEY

Layer 3: Ollama (optional, local)

Zero-auth local inference. Install Ollama, pull a model, and Vox auto-detects it on localhost:11434.

ollama pull llama3.2

Docker

# Build from source
docker build -t vox .

# Optional: image with `vox populi` (HTTP control plane)
docker build -t vox:mens --build-arg VOX_CLI_FEATURES=mens .

# Run MCP server
docker run -e GEMINI_API_KEY=... -p 3000:3000 vox

# MCP + in-container mens sidecar (background `vox populi serve` on 9847)
docker run -e VOX_MESH_MESH_SIDECAR=1 -e GEMINI_API_KEY=... -p 3000:3000 -p 9847:9847 vox:mens

# Full stack with docker compose
cp .env.example .env  # fill in GEMINI_API_KEY
docker compose up

An example multi-service mens compose file lives at examples/mens-compose.yml.

Platform notes

Windows

  • MSVC (C++): winget install -e --id Microsoft.VisualStudio.2022.BuildTools (include the Desktop development with C++ workload when prompted).
  • clang-cl (Turso / aegis): winget install -e --id LLVM.LLVM so clang-cl.exe is on PATH (usually C:\Program Files\LLVM\bin). Only needed if a native crypto build is required.
  • WSL: running sh scripts/install.sh inside WSL avoids MSVC / clang-cl friction for some workflows.

macOS

  • C compiler: xcode-select --install (ships clang).
  • Turso: usually satisfied by the Xcode Command Line Tools; if aegis still fails, brew install llvm and follow Homebrew's PATH notes.

Linux

  • C compiler: sudo apt-get install build-essential (Debian / Ubuntu).
  • clang (recommended for Turso): sudo apt-get install clang.