> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vertz.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Runtime

> The Vertz native runtime — fast dev server, built-in test runner

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](/guides/testing-unit)) |
| `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                     |

**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.).

<Tip>
  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.
</Tip>

## Installation

### Install script (recommended)

Install the `vtz` binary directly — works on macOS and Linux, both x64 and ARM:

```bash theme={null}
curl -fsSL https://raw.githubusercontent.com/vertz-dev/vertz/main/install.sh | sh
```

This installs to `~/.vtz/bin/` and creates a `vertz` symlink. The script auto-detects your platform and architecture.

To install a specific version:

```bash theme={null}
VTZ_VERSION=0.2.47 curl -fsSL https://raw.githubusercontent.com/vertz-dev/vertz/main/install.sh | sh
```

### 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:

```bash theme={null}
vtz add -d @vertz/runtime
```

### From source

For contributors working on the Vertz monorepo:

```bash theme={null}
cd native
cargo build --release
# Binary is at native/target/release/vtz
```

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

| 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:

```bash theme={null}
vtz dev              # Start development server
vtz test             # Run tests
vtz install          # Install dependencies
vtz add <pkg>        # Add a package
vtz remove <pkg>     # Remove a package
vtz update [pkg]     # Update packages (or all if no pkg specified)
vtz run <script>     # Run a package.json script
vtz exec <cmd>       # Run a command from node_modules/.bin
vtzx <cmd>           # Shorthand for vtz exec (like npx)
vtz self-update      # Update the vtz binary itself
```

### Dev server options

```bash theme={null}
vtz dev --port 3000       # Set port (default: 3000)
vtz dev --host 0.0.0.0   # Set host (default: localhost)
vtz dev --open            # Open browser on start
vtz dev --no-typecheck    # Skip TypeScript checking
vtz dev --inspect         # Enable Chrome DevTools debugging
vtz dev --inspect-brk     # Debug from the first statement
```

For full debugging setup (Chrome DevTools, VS Code, breakpoints), see [Debugging with Chrome DevTools](/guides/debugging).

## Updating

### Self-update (recommended)

The fastest way to update the `vtz` binary:

```bash theme={null}
vtz self-update
```

This downloads the latest release from GitHub and replaces the current binary in place. To update to a specific version:

```bash theme={null}
vtz self-update --version 0.3.0
```

### Via npm

If you installed the runtime through npm, update the package instead:

```bash theme={null}
vtz update @vertz/runtime
```

### Automatic update notifications

`vtz` checks for new versions automatically after running `dev` and `install` commands. When an update is available, you'll see:

```
  Update available: 0.2.46 → 0.2.47
  Run `vtz self-update` to update
```

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):

```bash theme={null}
VTZ_NO_UPDATE_CHECK=1 vtz dev
```

## Verifying your installation

```bash theme={null}
vtz --version
# vtz 0.2.47
```

If you see a version mismatch warning between the CLI and the runtime, update both:

```bash theme={null}
vtz self-update          # update the runtime binary
vtz update @vertz/cli    # update the CLI package
```