Vertz ships a native runtime (vtz) — a standalone Rust binary with an embedded V8 JavaScript engine. It starts in ~5ms and includes a dev server with SSR + HMR, a built-in test runner, and a package manager. No Node.js required.
How it works
vtz is the primary Vertz CLI. Run it directly — no extra configuration needed.
Command architecture
Not all vtz commands work the same way. Understanding the distinction helps avoid surprises:
| Command | Engine | What it does |
|---|
vtz dev | V8 (built-in) | Dev server with SSR, HMR, and TypeScript compilation |
vtz test | V8 (built-in) | Test runner with Vitest-compatible API (details) |
vtz run <script> | Shell (spawns process) | Executes a package.json script via sh -c |
vtz exec <cmd> / vtzx | Shell (spawns process) | Runs a binary from node_modules/.bin via sh -c |
vtz install / add / remove | Rust (native) | Package management with native dependency resolution |
dev, test) run JavaScript inside the vtz binary’s own V8 engine. They use Vertz’s module loader, compiler, and runtime APIs (like @vertz/test and vertz:sqlite).
Shell commands (run, exec) spawn a child process through your system shell. They add node_modules/.bin to the PATH, then hand off execution — similar to npm run or npx. The spawned process uses whatever runtime the script calls for (Node.js, Bun, etc.).
Use vtz test to run your tests — it’s the built-in test runner with watch mode, coverage, and a
Vitest-compatible API. Running a third-party test runner via vtz run or vtz exec spawns it as
a separate process and won’t use the Vertz test runtime.
Installation
Install script (recommended)
Install the vtz binary directly — works on macOS and Linux, both x64 and ARM:
This installs to ~/.vtz/bin/ and creates a vertz symlink. The script auto-detects your platform and architecture.
To install a specific version:
Via npm (existing projects)
If you already have a project with package.json, the vertz meta-package includes @vertz/runtime as an optional dependency. Running vtz install (or npm install) resolves the platform-specific binary automatically.
To add the runtime explicitly:
From source
For contributors working on the Vertz monorepo:
The CLI automatically detects local monorepo builds — no extra config needed.
Binary resolution
The CLI resolves the runtime binary in this order:
VERTZ_RUNTIME_BINARY env var — explicit path override (fail-fast if set but missing)- Monorepo local build —
native/target/release/vtz or native/target/debug/vtz
- npm package —
@vertz/runtime resolves the platform-specific binary
- Error — if none found, prints installation instructions and exits
| Platform | Architecture | npm package |
|---|
| macOS | ARM (M1/M2/M3/M4) | @vertz/runtime-darwin-arm64 |
| macOS | Intel (x64) | @vertz/runtime-darwin-x64 |
| Linux | x64 | @vertz/runtime-linux-x64 |
| Linux | ARM64 | @vertz/runtime-linux-arm64 |
CLI commands
The vtz binary supports the following commands:
Dev server options
For full debugging setup (Chrome DevTools, VS Code, breakpoints), see Debugging with Chrome DevTools.
Updating
Self-update (recommended)
The fastest way to update the vtz binary:
This downloads the latest release from GitHub and replaces the current binary in place. To update to a specific version:
Via npm
If you installed the runtime through npm, update the package instead:
Automatic update notifications
vtz checks for new versions automatically after running dev and install commands. When an update is available, you’ll see:
The check is non-blocking (won’t slow down your workflow), cached for 24 hours, and silently skipped if the network is unavailable.
To disable update checks (e.g. in CI):
Verifying your installation
If you see a version mismatch warning between the CLI and the runtime, update both:
