vx

What vx is

Task orchestration with a cache you can trust, on a core you can extend. Each task is one shell command with declared inputs and outputs; vx runs them in dependency order and replays results from a content-addressed cache.

Quick start

In a git repo:

bunx @vzn/vx init   # installs vx, writes an empty root vx.config.ts and the lockfile plugin

A prebuilt binary for Linux (glibc, not Alpine's musl) and macOS, x64 and arm64. Windows: run vx inside WSL2.

A task runs its tool directly, never through a package script. Cache one by saying what it reads and writes:

// packages/app/vx.config.ts
import { defineProject } from '@vzn/vx/config'

export default defineProject({
  tasks: {
    build: {
      exec: { command: 'tsc -b' },
      dependsOn: ['^build'], // dependencies build first
      inputs: { files: ['src/**', 'tsconfig.json'] },
      cache: {
        outputs: { files: ['dist/**'] },
      },
    },
  },
})

vx run build --all    # builds, in dependency order; stores the results
vx run build --all    # nothing changed: up-to-date, in milliseconds
rm -rf packages/*/dist
vx run build --all    # restored from the cache, not rebuilt

When to run vx lock

init also writes .vx/projects.lock.json, every project's config as it evaluated. Commit it. Every run reads its configs from the lock, so run vx lock and commit the lock again after you:

• edit any vx.config.ts or .vx/workspace.ts,
• update dependencies or plugins,
• change a file a config imports.

Otherwise runs keep the old configs. On CI, vx lock --check fails a stale lock before any task runs.

Starters: examples/basic, and examples/ci with a GitHub Actions workflow; CI runs both on every commit. The CI guide explains the workflow. More: Quickstart · Configure · CLI · every config field.

A foundation you own

• A cache you can trust: TypeScript configs are evaluated before hashing, so imports and computed values are in the key. Outputs are wiped before every run and restore: no stale file survives.
• Sandboxed tasks: opt in per task; a workspace file the task did not declare is out of its reach, so it cannot poison the cache.
• Clean exits: Ctrl-C reaps each task's process group.
• Plugins at every stage (15 hooks, commands included): remote cache, remote execution, telemetry, CLI verbs. Core ships none and needs none.
• Free: MIT. No paywall, no cloud, no account.

Plugins

What vx can do, not what it is limited to. Declared in .vx/workspace.ts; without any, vx runs and caches locally.

Package	What it adds
@vzn/vx-migrate	Migrate from Turbo or Nx: write native configs, keep its remote cache
@vzn/vx-reapi	Remote cache and remote execution over Bazel's REAPI (NativeLink, BuildBuddy)
@vzn/vx-lockfile	Key each project on its own lockfile slice: pnpm, bun, npm, yarn
@vzn/vx-otel	OpenTelemetry traces, metrics and logs, no SDK
@vzn/vx-ci	GitHub Actions job summary
@vzn/vx-history	Schedule by the critical path learned from past runs
@vzn/vx-cache	Remote cache for CI jobs, on a vx cache server
@vzn/vx-cache-server	The cache server you host: Bun or Docker with S3, or Workers with R2
@vzn/vx-history-server	The task timings server vxHistory() reads: Bun, Docker or Workers

Hosting the three servers: servers docs.

Write your own: plugin guide · architecture.

Coming from Turbo or Nx

Beside turbo.json or nx.json, bunx @vzn/vx init runs @vzn/vx-migrate: it writes a vx.config.ts per package from turbo.json or the Nx graph, and you keep those and delete the old config. vx init --keep writes only a .vx/workspace.ts that maps the old config instead, and its lock: a temporary start, not a way to run the repo. The benchmark below uses native vx config. Migration guide.

How it compares

	vx	Turborepo	Nx
Config	TypeScript, evaluated into the cache key	JSON (static)	JSON (static)
Output ownership	Strict: wiped before exec and restore	Additive (stale files survive)	Additive
Clean-tree hashing	No source reads (git index OIDs)	git OIDs	re-hash / daemon
Daemon	None	None for turbo run	On by default
Per-task sandbox	Yes: kernel-level, opt-in, local	No	On Nx Cloud only
Plugin API	Yes: every pipeline stage	No	Yes (TS-tied)
Install	Single binary; no Bun, Node optional	npm + Node	npm + Node

Every gap, and when another tool is the better pick: comparison · vx, Turborepo, Nx, Bazel.

Fast, without trading correctness

• Nothing boots per task: no daemon, no Node process; vx spawns your command.
• No source-file reads to hash: on a clean tree, keys come from git's index; each project's package.json and the lockfile are still read.
• One pass: one git walk per run; each stat and lookup happens once.

The head-to-head against Turborepo, Nx and Vite Task, each in its own native config, is re-measured on every change to vx and published on the site: benchmarks.

Status

Pre-alpha, dogfooded: this repo lints, tests and builds itself with vx. The schema may still change; 1.0's promise: versioning-1.0.md.

Issues

vx is maintained by VZN and takes issues, not pull requests: report a bug or ask for a feature in issues.

License

vx is MIT licensed. The prebuilt binaries embed Bun and a few npm packages under permissive licenses; their notices ship as THIRD_PARTY_NOTICES.txt in each platform package and GitHub release.