Voxup Omnibus Installer Spec

May 2026

Motivation

While Vox ships as a single CLI binary (vox), building and executing full-stack applications locally still silently delegates to external system toolchains: Node.js/pnpm for frontend bundling, rustup for WASM standard libraries, and Cargo for ML execution.

Relying on the user’s host OS environment causes significant friction, as users often lack these dependencies or have incompatible versions. vox doctor --auto-heal attempts to fix this, but fails if the foundational tools (like npm or curl) are entirely missing or permission-gated.

The solution is voxup: an omnibus installer modeled after rustup. It bootstraps the Vox environment by securely fetching hermetic, pre-compiled, and portable versions of all required toolchains into an isolated ~/.vox/toolchains/ directory, completely bypassing the host OS package managers.

Architecture

1. The Bootstrap Script

Users will install Vox via a single command that does not require brew, dpkg, or .msi:

# macOS/Linux
curl --proto '=https' --tlsv1.2 -sSf https://voxlang.org/voxup | sh

# Windows (PowerShell)
Invoke-WebRequest -Uri https://voxlang.org/voxup.ps1 -OutFile voxup.ps1; .\voxup.ps1

The bootstrap script is intentionally minimal. Its only job is to detect the host architecture (e.g., x86_64-apple-darwin, aarch64-unknown-linux-gnu), download the voxup Rust binary for that target, and execute it.

2. The voxup Binary

The voxup binary acts as the local toolchain multiplexer and installer. It manages:

• ~/.vox/bin/ (where the vox proxy executable lives, added to $PATH)
• ~/.vox/toolchains/ (where isolated toolchains live)

Core Commands:

• voxup install default (Installs the latest stable vox-cli and mandatory toolchains)
• voxup update (Updates the CLI and toolchains)
• voxup toolchain add <name> (e.g., node-v22, wasm-sysroot)

3. Hermetic Toolchain Management

When voxup install runs, it resolves a manifest (channels/stable.toml) that defines the exact matrix of required dependencies for Vox to operate on the current platform.

It then downloads these as isolated bundles into ~/.vox/toolchains/:

1. Vox CLI: The actual vox executable.
2. Hermetic Node.js: A minimal, portable Node.js binary + pnpm specifically for Vox’s internal usage. The user’s system node is ignored.
3. Script runtime: The vox binary is enough for script-shaped files (ADR-048). cargo / rustc / wasm32-wasip1 are not required.
4. LLVM/Mold (Linux): If required for fast ML inference compilation.

4. CLI Path Execution

When the user types vox build, the shell executes the ~/.vox/bin/vox proxy. This proxy sets up the isolated environment:

export PATH=~/.vox/toolchains/node-v22/bin:~/.vox/toolchains/wasm-sysroot/bin:$PATH

It then forwards the command to the actual vox binary. The vox CLI now reliably finds pnpm and node in its PATH without polluting the user’s global system PATH.

Implementation Status

Phase	Description	Status
1	crates/voxup scaffold — directory layout, hard-link, WASM sysroot stub	✅ Done
2a	Channel resolution — GitHub Releases API (channel.rs)	✅ Done
2b	Download + SHA-256 verification (download.rs)	✅ Done
2c	Archive extraction (.tar.gz Unix, .zip Windows)	✅ Done
3a	Shell PATH persistence (shell.rs)	✅ Done
3b	Proxy execution — execv Unix, spawn+exit Windows (proxy.rs)	✅ Done
3c	voxup update — semver comparison + conditional upgrade (update.rs)	✅ Done
4	Bootstrap scripts (install.sh, install.ps1) hosted at voxlang.org	⬜ Plan B
5	Hermetic Node.js + WASM bundle download	⬜ Future
6	Ed25519 signature verification of archives	⬜ Future
7	Deprecate direct .msi, brew, dpkg install instructions	⬜ After Plan B