Skip to main content
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: V8 commands (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 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:
  1. VERTZ_RUNTIME_BINARY env var — explicit path override (fail-fast if set but missing)
  2. Monorepo local build — native/target/release/vtz or native/target/debug/vtz
  3. npm package — @vertz/runtime resolves the platform-specific binary
  4. Error — if none found, prints installation instructions and exits

​
Supported platforms

​
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

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: