DEV Community: VX

Branch caches a server enforces

VX — Wed, 21 Oct 2026 18:19:30 +0000

A pull request reuses everything main built. Nothing it builds can
land in main's cache, so one bad build cannot poison the next run.

Decision	Who makes it	From what
Where a write lands	the server	the CI's signed OIDC token
Which branches a read sees	the client	one header, own branch first, then `main`

The token decides writes

The server checks the CI's signed OIDC token against its trust policy. A
matching token writes the trusted cache. Any other token from the repo
writes only its own branch. No token writes nothing.

No header or key can change that.

One header steers reads

HEAD /v8/artifacts/0a1b2c3d4e5f6789
x-artifact-read-scopes: refs/heads/feat-x, refs/heads/main

The server returns the first hit in that order. Keys are the same on
every branch, so a hit on main is the bytes feat-x would have built.
A server that ignores the header keeps one shared cache.

CI refs come from env (GITHUB_HEAD_REF or GITHUB_REF, then
GITHUB_BASE_REF; CI_COMMIT_REF_NAME, then
CI_MERGE_REQUEST_TARGET_BRANCH_NAME).

On a laptop they come from git: the current branch, then origin/HEAD.

Two client modes

`scope`	Key	Read request	For
`'header'` (default)	`hash(inputs)`	plain key + `x-artifact-read-scopes`	servers that implement the rules below
`'key'`	`hash(inputs + ref)`	one batch with each ref's key, first hit wins	servers that ignore the header (Vercel)

// .vx/workspace.ts
import { defineWorkspace } from '@vzn/vx/config'
import { turboCache } from '@vzn/vx-migrate'

export default defineWorkspace({
  plugins: [turboCache({ scope: 'key' })], // a server that ignores the header
})

// .vx/workspace.ts
import { defineWorkspace } from '@vzn/vx/config'
import { turboCache } from '@vzn/vx-migrate'

export default defineWorkspace({
  plugins: [turboCache({ scope: 'key' })], // a server that ignores the header
})

'key' separates branches but secures nothing: anyone can compute
main's key. Only a server can enforce, so 'header' is the default.

nxCache() sends plain requests, since the Nx spec has no batch query.

Building the server half

Everything below is the Turbo artifacts API (/v8/artifacts) plus one
header.

Server config

vx's own cache server does this over its
/v1 wire. For a server on the Turbo wire, here is an example: a trust
policy per team.

A rule names token claims; each value is an exact string, a glob, or a
list.

A token matches a rule when every claim in it matches.

export default {
  trust: [
    // GitHub: main and merge queue, only from the main-branch workflow
    {
      iss: 'https://token.actions.githubusercontent.com',
      repository_id: '123456789',
      event_name: ['push', 'merge_group'], // pull_request_target and issue_comment run PR code with ref=main
      ref: ['refs/heads/main', 'refs/heads/gh-readonly-queue/main/*'],
      ref_protected: 'true', // an unprotected branch can be pushed with unreviewed code
      job_workflow_ref: 'org/repo/.github/workflows/ci.yml@refs/heads/main',
    },
    // GitLab: protected main, on our own runners
    {
      iss: 'https://gitlab.com',
      project_id: '4567',
      ref_path: 'refs/heads/main',
      ref_protected: 'true',
      pipeline_source: ['push', 'schedule'], // a manual pipeline can inject CI variables
      runner_environment: 'self-hosted',
    },
  ],
}

Pin repository_id or project_id, not the name: after a rename or
delete, another repository can take the name, never the id.

Trusted is main and its merge queue only: anyone who can push can tag
any commit, so a tag's run writes to its own scope, as a branch does.

Write scope

Built into the server, not configurable. A token that matches no rule
writes to:

GitHub: refs/heads/<head_ref> on a PR run, otherwise ref. A PR run writes to its head branch, so a laptop finds it from git alone.
GitLab: ref_path.

Rules

Auth. Accept GitHub and GitLab OIDC tokens as Authorization: Bearer, and verify the signature (the issuer's JWKS), iss, aud and exp.

Every read needs a token. Each developer creates their own read-only
token, and a shared read-only token may serve other CIs; neither ever
writes.

Audience. aud must be this server's own, so a token minted for another service can't be replayed here.
Trust match. As above: every claim a rule names must match.
Write (PUT /v8/artifacts/:hash). A token that matches a rule stores to trusted. Any other token stores to its write scope. A token from a repository or project no rule names writes nothing. Entries are immutable.
Read (GET and HEAD /v8/artifacts/:hash, and the batch POST /v8/artifacts). For each ref in the header, in order: if it matches a rule's ref glob, look in trusted; otherwise look in that ref's scope. Return the first hit.
No header. Read from trusted only, so plain Turbo clients keep working.
Per repository. Every scope, trusted included, lives in that repository's own bucket, taken from the token (repository_id, project_id, or the read token's repository). One team's repositories never share a branch.
Header limits. Each entry must be a refs/... string; dedupe the list and cap it at 8 refs. vx sends at most 8.
Merge queue. It writes to trusted before its code lands, so a queued PR that drops out leaves trusted entries behind. That is accepted: queue code is approved code.

GitHub

Run	Token holds	`x-artifact-read-scopes`	Server reads (first hit)	Server writes
main push	`ref=refs/heads/main`	`refs/heads/main`	trusted	trusted
merge queue	`ref=refs/heads/gh-readonly-queue/main/…`	`refs/heads/gh-readonly-queue/main/…, refs/heads/main`	trusted	trusted
PR #12 (feature→main)	`ref=refs/pull/12/merge`, `head_ref=feature`, `base_ref=main`	`refs/heads/feature, refs/heads/main`	feature, trusted	`refs/heads/feature`
branch push	`ref=refs/heads/feature`	`refs/heads/feature, refs/heads/main`	feature, trusted	`refs/heads/feature`
fork PR	no token	`refs/heads/<head>, refs/heads/main`	nothing (no token)	nothing
local on main	personal token (read-only)	`refs/heads/main`	trusted	nothing
local on feature	personal token (read-only)	`refs/heads/feature, refs/heads/main`	feature, trusted	nothing

GitLab

Run	Token holds	`x-artifact-read-scopes`	Server reads (first hit)	Server writes
main pipeline	`ref_path=refs/heads/main`	`refs/heads/main`	trusted	trusted
merge train	`ref_path=refs/heads/feature`	`refs/heads/feature, refs/heads/main`	feature, trusted	nothing (client read-only)
MR or merged results (feature→main)	`ref_path=refs/heads/feature`	`refs/heads/feature, refs/heads/main`	feature, trusted	`refs/heads/feature`
branch pipeline	`ref_path=refs/heads/feature`	`refs/heads/feature, refs/heads/main`	feature, trusted	`refs/heads/feature`
fork MR	fork project's token	`refs/heads/feature, refs/heads/main`	nothing (wrong project)	nothing (wrong project)
local on main	personal token (read-only)	`refs/heads/main`	trusted	nothing
local on feature	personal token (read-only)	`refs/heads/feature, refs/heads/main`	feature, trusted	nothing

A GitLab token has no merge-train claim, so the server would store a
train's results in the source branch's scope.

Those results are built from the branch merged with main and the MRs
ahead of it, so the branch almost never reuses them. The CI knows it is
a train, so turn writes off there:

build:
  rules:
    - if: $CI_MERGE_REQUEST_EVENT_TYPE == "merge_train"
      variables:
        VX_CACHE_POLICY: local:rw,remote:r
    - when: on_success

A stacked PR (feature-b→feature) reads feature-b, feature, main in CI
and feature-b, main on a laptop.

What the client sends

Task keys reach every remote plain.
turboCache() sends x-artifact-read-scopes on every read; a PUT names no scope.
VX_CACHE_SCOPE, github({ cacheScope }) and gitlab({ cacheScope }) scope only what plugins store themselves (ctx.cache, run records).

The remote cache page's cache scopes and tokens has the setup.
More at vznjs.github.io/vx.

Originally published on the vx blog. vx is open-source (MIT) task orchestration with a build cache: vznjs.github.io/vx · GitHub.

Written with AI assistance.

When running beats downloading

VX — Wed, 21 Oct 2026 18:18:38 +0000

If a download would take longer than running the task, vx runs the task.
Here 500 tasks are remote hits, and 20 of them are 8 MB on a 4 MB/s
link:

$ vx run build --all --dry
500 task(s) planned, 500 cache hits (500 remote, 153 MB).

$ vx run build --all
  cache     local 20↑ · remote 480↓ 129 KB
  time      1.02s

Those 20 would take 2 s each to download. Their tasks run in
milliseconds, so vx ran them here (local 20↑) and downloaded the
other 480.

The remote says	Full run	Downloaded
size and task time	1.15 s	129 KB
size only	3.12 s	153 MB

Min of 3 interleaved runs, empty local cache · private/vx-bench/generate.ts, 500 projects, 20 writing 8 MB · Turborepo-protocol stub 30 ms away at 4 MB/s, turboCache() · Linux x64, 4 cores · vx 22f6eb7 · 2026-10-23

Weigh the download against the task

The remote has to tell vx the entry's size and its task's time. Turbo's
cache API sends both (Content-Length, x-artifact-duration), and
turboCache() passes them on.

Twice the task time, because a run here also saves its outputs. The task
counts as a miss and uploads nothing.

A remote that doesn't send the time is always waited for, as in the
second row. vx won't guess.

Know what a run will pull

The footer shows the bytes each way. --dry shows what the remote hits
would download, before anything runs.

For plugin authors

A remote's has returns { size, durationMs }, either one, {}, or
null for a missing key. hasMany returns a Map of the same. Send a
size and you get the --dry figure.

Send a duration too and you get the slow-download check. Your own
cache shows a whole remote.

Setup: Remote cache. More at
vznjs.github.io/vx.

Originally published on the vx blog. vx is open-source (MIT) task orchestration with a build cache: vznjs.github.io/vx · GitHub.

Written with AI assistance.

Every task has a key

VX — Wed, 21 Oct 2026 18:18:37 +0000

A task you don't cache still has a key. Change a code generator's env,
and the cached build after it runs again.

import { defineProject } from '@vzn/vx/config'

export default defineProject({
  tasks: {
    codegen: {
      exec: {
        command: 'mkdir -p gen && echo "export const api = \"$API_URL\"" > gen/api.ts',
        env: { passThrough: ['API_URL'] },
      },
      inputs: { files: ['schema.json', '.env.local'], env: ['API_URL'] },
    },
    build: {
      dependsOn: ['codegen'],
      exec: { command: 'mkdir -p dist && cat gen/api.ts > dist/app.js' },
      inputs: { files: ['src/**'] },
      cache: { outputs: { files: ['dist/**'] } },
    },
  },
})

$ API_URL=https://a.example vx run packages/e#build
  cache     local 1✓ 1∅

$ API_URL=https://b.example vx run packages/e#build
  cache     local 1∅ 1↑
$ cat packages/e/dist/app.js
export const api = https://b.example

$ vx why packages/e#build
  verdict    cache key changed: upstream packages/e#codegen
  what changed (1 component, 3 unchanged):
    changed upstream  packages/e#codegen  35dfe1115aedc6d6 → a7a53dc4d9e0bde9

codegen never caches (∅), but its key goes into build's key. A
new API_URL builds again instead of restoring a dist/ made for the
old one.

Demo workspace · vx 69617eb · 2026-10-23

Inputs live on the task

inputs sits on the task, next to exec. It sets the key whether the
task caches or not, as in Turbo and Nx. cache holds only outputs
and inputStability.

A task with a command and no inputs has no key. vx won't guess one.
Every task after it runs again and saves nothing:

$ vx run packages/e#build      # codegen without inputs
  cache     local 1∅ · 1 not saved
$ vx run packages/e#build
  cache     local 1∅ · 1 not saved

A missing input costs a re-run, never a wrong cache hit. Every rule is
on the Caching page.

A gitignored file can still be an input

.env.local is gitignored. Editing it still changes the key:

$ echo "TOKEN=2" > packages/e/.env.local
$ vx run packages/e#build
  cache     local 1∅ 1↑

vx reads tracked files' hashes from git. A path you name outright
(.env.local), or a glob whose fixed part git ignores (gen/**), is
read from disk.

A broad glob like src/** still skips ignored files, and node_modules
is never walked.

--affected sees only what git sees, as in Nx. An ignored file never
picks a task by itself, but the key still changes when the task runs.

The full key, part by part: Caching. More at
vznjs.github.io/vx.

Originally published on the vx blog. vx is open-source (MIT) task orchestration with a build cache: vznjs.github.io/vx · GitHub.

Written with AI assistance.

What a run does not do

VX — Tue, 20 Oct 2026 22:32:30 +0000

A warm run is fast mostly because of work it skips. Here is what a vx
run never does.

Cleanup runs when you choose

$ vx cache clean --older-than 30d --max-size 10G
› vx cache clean  nothing to free

$ vx cache clean --max-size 100K
✓ vx cache clean  freed 94 MB

  999 entries

Cleanup at the end of every run would be seven DELETEs, four of them
full scans, and it grows with history. Run vx cache clean from cron or
a scheduled CI job instead.

There is no cache.retention setting.

The shared store opens by its index

The store under ~/.vx opens by its index file. A run never lists its
entries or checks their folders.

The footer shows only what it measured

  [2mtime    [0m  63ms [2m·[0m [2mmax 8ms[0m [2m·[0m [2mavg 6ms[0m [2m·[0m [2mmin 4ms[0m

That is wall time, then the slowest, average and fastest task. Adding
up the stored time of every cache hit would overstate the saving.
Tasks that would have run side by side cost the clock only once.

What each run does, stage by stage: Architecture.
More at vznjs.github.io/vx.

Originally published on the vx blog. vx is open-source (MIT) task orchestration with a build cache: vznjs.github.io/vx · GitHub.

Written with AI assistance.

Brackets in a glob mean brackets

VX — Tue, 20 Oct 2026 22:31:49 +0000

In a vx glob, [jt] matches one character, j or t. A Next.js route
folder like app/[id] needs escaping.

Glob	Matches
`src/*.[jt]s`	`.js` and `.ts` files in `src`
`app/[id]/**`	`app/i/`, `app/d/`
`app/\[id\]/**`	the `app/[id]/` folder

Turbo, Nx and shells read brackets the same way. A glob you copy from
turbo.json or an Nx project means the same thing in vx.config.ts.

See it in a run

route: {
  exec: { command: 'ls src app/*' },
  inputs: { files: ['src/*.[jt]s', 'app/\\[id\\]/**'] },
  cache: { outputs: { files: [] } },
}

The double backslash is the escape inside a TypeScript string.

$ echo "// e" >> app/i/x.ts          # not an input
$ vx run packages/c#route
  cache     local 1✓

$ echo "// e" >> 'app/[id]/page.ts'  # the escaped route
$ vx run packages/c#route
  cache     local 1↑

$ echo "// e" >> src/j.js            # matched by [jt]
$ vx run packages/c#route
  cache     local 1↑

Linux x64 · vx 69617eb · 2026-10-23

An edit to an input runs the task again (1↑). Any other edit is a
cache hit (1✓). @vzn/vx-migrate keeps Turbo's and Nx's brackets as
they are, and escapes brackets in any path it writes.

Glob rules: Caching. More at
vznjs.github.io/vx.

Originally published on the vx blog. vx is open-source (MIT) task orchestration with a build cache: vznjs.github.io/vx · GitHub.

Written with AI assistance.

Cache transfers wait on the network

VX — Tue, 20 Oct 2026 22:30:57 +0000

Cache uploads and downloads mostly wait on the network, so vx runs up
to 64 at once even on a 4-core machine. 1,000 uploads to a cache 30 ms
away take 2.5 s. With only 4 at once:

$ time vx run build --all --cache-concurrency-upload 4
  cache     remote 1000↑ 269 KB
  time      2.27s
real    0m8.345s

$ time vx run build --all
  cache     remote 1000↑ 269 KB
  time      2.38s
real    0m2.649s

The run's time ends with its last task. Uploads finish in the
background, and the process exits when they are done.

Lane limit	Upload all 1,000	Restore all 1,000 from the remote
1	31.6 s	9.0 s
4	8.4 s	8.4 s
16	2.7 s	2.6 s
default (64)	2.5 s	1.6 s

Min of 3 interleaved runs · private/vx-bench/generate.ts, 1,000 projects, build --all · Turborepo-protocol cache that answers after 30 ms, turboCache() · CI=1 · Linux x64, 4 cores · vx a1786b3 · 2026-10-23

Three lanes, three limits

Lane	Default	Why
`download`	min(96, max(cores × 3, 64))	mostly waiting on the network
`upload`	min(96, max(cores × 3, 64)), per remote	the same, and it runs in the background
`restore`	twice `run.concurrency`	local disk work, closer to a task

The network formula is pnpm's: at least 64 at once, at most 96. If your
server wants fewer connections, set fewer:

// .vx/workspace.ts
import { defineWorkspace } from '@vzn/vx/config'

export default defineWorkspace({
  cache: { concurrency: { download: 32, upload: 16 } },
})

vx run build --all --cache-concurrency-upload 16

A missing key costs no request

Before tasks start, vx asks each remote in one batch which keys exist.
A missing key costs nothing more. A key it has costs one download.

One request per plugin read

Plugins keep entries in the same cache, like the timings
@vzn/vx-history learns. ctx.cache.get, has and hasMany
each make one request.

Settings: schema. Flags: CLI reference.
More at vznjs.github.io/vx.

Originally published on the vx blog. vx is open-source (MIT) task orchestration with a build cache: vznjs.github.io/vx · GitHub.

Written with AI assistance.

A cache hit is a file copy

VX — Tue, 20 Oct 2026 22:30:55 +0000

A local cache hit is a file copy the kernel does. 1,000 hits of 96 KiB
restore in 411 ms. With dist deleted:

$ rm -rf packages/*/dist && time vx run build --all
  cache     local 1000↓
  time      214ms
real    0m0.411s

$ rm -rf packages/*/dist && time VX_CACHE_STORE_DECOMPRESS=false vx run build --all
  cache     local 1000↓
  time      618ms
real    0m0.686s

Same entries, two ways to keep them on disk:

Store (`cache.store.decompress`)	Restore all 1,000	Store on disk
plain files (`true`, default)	411 ms	111 MB
one `tar.zst` each (`false`)	686 ms	99 MB

Min of 5 restores, 3 interleaved arms, fresh store per arm · private/vx-bench/generate.ts, 1,000 projects, 96 KiB random output each · Linux x64, 4 cores · vx a1786b3 · 2026-10-23

The kernel does the copy

Archives exist only on the network. Locally, each entry is stored as
plain files, unpacked once.

A hit hands each file to the kernel: copy_file_range on Linux, or a
clone on APFS, Btrfs or XFS. A clone shares blocks until one side
writes, so a big output restores without copying bytes.

vx never hard-links. A hard link would be faster, but then editing
dist/index.js in place would edit the cache too, and the next hit
would restore your edit. A copy or clone keeps the cache safe.

Small entries stay in the index

A thousand tiny outputs as a thousand folders is more work than the
bytes are worth. So an entry up to 32 KiB stays in the SQLite index as
one compressed row. You can change the limit:

// .vx/workspace.ts
import { defineWorkspace } from '@vzn/vx/config'

export default defineWorkspace({
  cache: { store: { embeddings: '64KiB' } }, // false keeps every entry as files
})

If disk matters more than speed, decompress: false keeps each entry
as one tar.zst, as in the table.

A local hit checks nothing

Only vx writes to its local store, so checking each file on a hit would
guard against nothing and slow every save.

Anything from the network is checked: a remote entry ends with a CRC-32,
and a wrong sum is a miss.

A download is decompressed once

Up to 4 MiB is fetched whole, decompressed once and written into the
store, then checked. Larger ones go through a temp file, still
decompressed once.

Storage layout and settings: Caching and the
schema. More at
vznjs.github.io/vx.

Originally published on the vx blog. vx is open-source (MIT) task orchestration with a build cache: vznjs.github.io/vx · GitHub.

Written with AI assistance.

vx on real repos: wall times

VX — Wed, 14 Oct 2026 22:01:32 +0000

Seven open-source monorepos that already use Turborepo or Nx, each moved
to native vx config and timed under both on one machine. Slower rows
included.

4 vCPU Xeon 2.10GHz, 15 GB, Linux · Bun 1.4.2, Node 22.22.0 · vx 522c23b (create-t3-turbo, react-email, trpc, typescript-eslint), 731cf92 (vercel/ai, medusa, TanStack query), 1ee058c (react-email clone) · configs from bunx @vzn/vx-migrate --native --no-install · concurrency 10 for all · local cache only, no daemon · 3 reps alternating, min shown, every run exit 0

Seconds, min of 3. Shorter bars are less time; each table is one click
away.

create-t3-turbo vs Turborepo 2.5.8

build typecheck, 11 tasks, commit 8f945b7.

Arm	Turborepo 2.5.8	vx
cold	13.63 s	10.97 s
restore	0.28 s	0.09 s
edit	4.69 s	4.89 s
edit, clean: false	4.61 s	3.83 s
clone	0.28 s	0.11 s

Both edit rows: vx 5b2b0a1, same machine, min of 3. By default vx
deletes a task's outputs before a miss, tsc's tsbuildinfo too, so tsc
rebuilds from scratch.

cache.outputs.clean: false on the three tsc tasks keeps it.

react-email vs Turborepo 2.9.14

build, 4 tasks, commit 1531a39.

Arm	Turborepo 2.9.14	vx
cold	28.92 s	25.11 s
restore	0.32 s	0.22 s
edit	28.23 s	26.29 s
clone	0.34 s	0.26 s

trpc vs Turborepo 2.10.12

build, 7 tasks, commit d756e59.

Arm	Turborepo 2.10.12	vx
cold	9.29 s	7.48 s
restore	0.17 s	0.15 s
edit	9.40 s	7.04 s
clone	0.16 s	0.13 s

vercel/ai vs Turborepo 2.9.14

build, 82 tasks, commit e8c8e32.

Arm	Turborepo 2.9.14	vx
cold	144.96 s	135.33 s
restore	0.92 s	0.45 s
edit	156.38 s	145.61 s
clone	0.97 s	0.65 s

medusa vs Turborepo 1.13.4

build build:plugin, 83 tasks, commit 5018ab67.

Arm	Turborepo 1.13.4	vx
cold	316.57 s	307.81 s
restore	3.56 s	3.45 s
edit	268.92 s	259.96 s
clone	2.59 s	3.54 s

Clone row

vx's clone takes what its restore takes (3.54 s and 3.45 s, all 83 hits).
Turborepo's clone takes less time than its own restore.

TanStack query vs Nx 23.2.1

build, 25 tasks, commit 817bd02.

Arm	Nx 23.2.1	vx
cold	35.01 s	29.37 s
restore	0.94 s	0.32 s
edit	34.10 s	29.03 s
clone	0.96 s	0.58 s

Clone row

Nx's first clone rep missed its cache (36.42 s): Nx 23 indexes its local
cache in the checkout's own .nx/workspace-data. The chart shows the
minimum.

typescript-eslint vs Nx 23.2.0

build, 18 tasks, commit 57e7cccce.

Arm	Nx 23.2.0	vx
cold	52.50 s	41.77 s
restore	4.45 s	5.32 s
edit	40.69 s	38.97 s
clone	4.15 s	5.37 s

Restore and clone rows

vx hits 16 of 18, Nx 17. ast-spec#build stays a miss: its own test
may rewrite its committed snapshots, and vx never trusts a key on files
another task can write.

Nx's first clone rep missed its cache (56.82 s), as with TanStack query.

Run it on yours

bunx @vzn/vx init
vx run build --all

Then time your runner's command and vx run on the same machine, each
on its own cache. More at vznjs.github.io/vx.

Originally published on the vx blog. vx is open-source (MIT) task orchestration with a build cache: vznjs.github.io/vx · GitHub.

Written with AI assistance.

Say which projects may depend on which

VX — Wed, 14 Oct 2026 17:06:45 +0000

Tag your projects by layer and say which layers may depend on which. vx lock refuses a dependency that breaks a rule.

Here UI may not depend on a utility, and packages/c (UI) depends on
packages/a:

// .vx/workspace.ts
import { defineWorkspace } from '@vzn/vx/config'

export default defineWorkspace({
  run: {
    rules: {
      dependencies: [{ from: 'tag:type:ui', deny: ['tag:type:util'] }],
    },
  },
})

$ vx lock
✗ vx lock  lock not written

  1 dependency breaks run.rules.dependencies
  packages/c depends on packages/a, which run.rules.dependencies[0] (from 'tag:type:ui') denies

  fix  drop the dependency, or change the project's tags or the rule
$ echo $?
1

The edge here is a task edge (c#build depends on a#build), not a
package.json dependency. Both count.

Demo workspace · vx 69617eb · 2026-10-23

Tags and rules

A project names its tags in its own config:

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

export default defineProject({
  tags: ['type:ui'],
  tasks: { build: { exec: { command: 'tsc -b' } } },
})

The workspace says what each tag may depend on. A selector is
tag:<glob> or a project-name glob:

// .vx/workspace.ts
import { defineWorkspace } from '@vzn/vx/config'

export default defineWorkspace({
  run: {
    rules: {
      dependencies: [
        { from: 'tag:type:app', allow: ['tag:type:feature', 'tag:type:ui'] },
        { from: 'tag:type:ui', deny: ['tag:type:feature', 'tag:type:app'] },
      ],
    },
  },
})

A dependency must match one of allow (if given) and none of deny.
A deny beats any allow. A project no rule selects is free.

vx lock checks them, runs don't

vx lock checks each project's direct dependencies: package.json and
cross-project dependsOn. It names every broken edge and writes
nothing. Fix the edge and the lock is written:

$ vx lock
✓ vx lock  6 project configs → .vx/projects.lock.json

$ vx lock --check
✓ vx lock --check  up to date (6 projects)

vx lock --check in CI fails the same way, so a pull request with a
forbidden dependency goes red.

Runs read the lock, which already passed the rules, so they pay nothing
(vx lock).

From Nx

nx() from @vzn/vx-migrate reads the depConstraints of
@nx/enforce-module-boundaries from your ESLint config and fills
run.rules.dependencies.

It reads the file without running it, so ESLint never loads on a vx run.

// eslint.config.mjs (Nx)
depConstraints: [
  { sourceTag: 'type:app', onlyDependOnLibsWithTags: ['type:feature', 'type:ui'] },
  { sourceTag: 'type:ui', notDependOnLibsWithTags: ['type:feature'] },
]

becomes:

dependencies: [
  { from: 'tag:type:app', allow: ['tag:type:feature', 'tag:type:ui'] },
  { from: 'tag:type:ui', deny: ['tag:type:feature'] },
]

One difference: Nx's lint
rule
checks source imports. vx checks declared dependencies.

allSourceTags, /regex/ tags and external-import bans are left out.
The vx-migrate
README
lists them.

The schema is in the configuration reference. More at
vznjs.github.io/vx.

Originally published on the vx blog. vx is open-source (MIT) task orchestration with a build cache: vznjs.github.io/vx · GitHub.

Written with AI assistance.

One name per setting

VX — Wed, 14 Oct 2026 17:00:43 +0000

Every vx setting has one name. Its environment variable and flag are
spelled from it, so learn one and you know all three.

Setting	Variable	Flag
`run.retries`	`VX_RUN_RETRIES`	`--retries`
`run.concurrency`	`VX_RUN_CONCURRENCY`	`--concurrency`
`cache.dir`	`VX_CACHE_DIR`	`--cache-dir`
`cache.policy`	`VX_CACHE_POLICY`	`--cache-policy`

Settings live in four groups in .vx/workspace.ts: run, cache,
lock and watch.

import { defineWorkspace } from '@vzn/vx/config'

export default defineWorkspace({
  run: { concurrency: 4, retries: 2 },
  cache: { dir: 'build/.vx' },
})

Which value wins

Left wins. exec.retries on a task beats --retries. vx info shows
each changed setting and where its value came from:

$ VX_RUN_CONCURRENCY=2 vx info
…
  settings          run.concurrency 2 (VX_RUN_CONCURRENCY), run.retries 2 (.vx/workspace)

Units are part of the value

Durations carry a unit ('500ms', '30s', '2h'), sizes too
('32KiB'). A bare number is refused. Nobody can tell if 2000 means
milliseconds or seconds:

$ VX_CONFIG_WORKER_TIMEOUT=2000 vx run build
✗ vx run  VX_CONFIG_WORKER_TIMEOUT takes a duration with its unit, like '2000ms' or '2s' (got 2000)

Unknown names are refused

A typo in a key or a flag stops the run with the line to fix:

$ vx run build
✗ vx run  config refused

  .vx/workspace.ts:4:3
  unknown field "concurrency"
  allowed: baseBranch, cache, lock, plugins, run, watch

    2 |
    3 | export default defineWorkspace({
  > 4 |   concurrency: 4,
      |   ^

A few settings, like run.outputLogs and debug.timing, are read
before the file loads, so only a variable or flag sets them.

Demo workspace · vx 22f6eb7 · 2026-10-23

Every setting: settings table. More at
vznjs.github.io/vx.

Originally published on the vx blog. vx is open-source (MIT) task orchestration with a build cache: vznjs.github.io/vx · GitHub.

Written with AI assistance.

Where a task run spends its time

VX — Wed, 14 Oct 2026 16:54:42 +0000

We traced one 8,002-task run through vx, Turborepo and Nx. A cold run is
almost all task time. A warm run is how little the tool does.

Run	vx	Turborepo 2.11.8
Cold	120.2 s	127.3 s
Warm	892 ms	2,496 ms first, 909 ms second
One source file changed	100.1 s (6,607 run)	105.8 s (6,607 run)
That edit reverted	3.6 s (1,321 tasks restored, the rest left in place)	5.2 s (all 8,002 replayed)

Synthetic bench, 1,601 projects, 9,603 graph nodes · 4 cores, concurrency 10, CI=1, local cache only, Linux · vx 9388bad8f (VX_DEBUG_TIMING=1), Turborepo 2.11.8 (--profile), Nx 23.3.0 (nx:run-commands, daemon off, .env off) · 2026-10-13/14 · method

A cold run is the tasks

vx adds about 0.4 ms per task for spawn, env and output capture. Before
the first task it spends about 640 ms on projects, graph and git.
Turborepo's precompute is about 0.7 s.

Some extra work is a safety check

Check	Cost
Graph rules (output overlap, missing edge)	none at run time, `vx lock` checks once
Input recheck after a miss	about 0.2 ms per miss
Clear outputs before a miss	about 0.15 ms per miss
Save before dependents start	at most about 0.14 s of 120 s
Blob-size check, cold cache	about 330 ms, once per git index

Remote uploads run in the background. Only the end of the run waits for
them. We measured each check and kept it.

A warm run decides not to work

Step	vx	Turborepo 2.11.8
Projects and graph	discover, then graph with rules	precompute
File hashes	git's own index (63 ms)	git index, then per-package file hashes
Keys	one per task	one per task
On a hit	checks each task's outputs on disk; restores a task's outputs only if one differs	restores every output and log

Without its daemon, Turborepo rewrites every output on a hit
(restore_outputs).

vx leaves a task's outputs alone if each file still matches its record
(size, mode, modification time, inode, change time).

Nx 23.3.0, warm: 21 to 24 s

Self time	Where
6.10 s	`hashTasksUpfront`: hands each task's environment to the native hasher
5.55 s	garbage collection
3.03 s	`getTaskSpecificEnv`: copies `process.env` for each task
2.89 s	`copyFilesFromCache`: writes every cached output back
1.56 s	`plan`, the native planner

CPU profile of the main process, all 9,603 tasks hit, 173 env vars · source nx@23.3.0 task-env.js, cache.js

getTaskSpecificEnv copies process.env for every task, so it grows
with your environment.

What a change reruns

Change	vx	Turborepo 2.11.8
Unrelated env var set	all hit	all hit
Root `package.json` edited	all hit	all 8,002 miss
One project's `package.json`	6,607 miss	6,607 miss
`bun.lock` added	all miss	all miss

vx sees root dependencies through the lockfile. A lockfile plugin such as
bun() narrows the last row to the projects whose dependencies moved.

What we checked in vx and dropped

The output check on hits looked like 655 ms. Alone it is 10.8 ms over
1,600 hits: the trace summed ten workers.

A tool that rewrites outputs with the same bytes makes vx restore them,
but a content hash on every save would cost more. Neither became a
patch.

The bench and its scripts are in the repository. More at
vznjs.github.io/vx.

Originally published on the vx blog. vx is open-source (MIT) task orchestration with a build cache: vznjs.github.io/vx · GitHub.

Written with AI assistance.

An input changes mid-run: what four task tools do

VX — Tue, 13 Oct 2026 20:29:58 +0000

You save a file while a build runs. The output may come from bytes the
cache key does not name. Here is what each tool does after the command
exits, read from its source.

After the command exits	Turborepo 2.11.7	Nx 23.3.0	Vite Task 1.1.0	vx
Inputs looked at again	no	no (batch: rehash)	files the task opened	every declared input
Writes it notices	none	none	the task's own	any process's
What it does on a change	saves	saves	skips the save	skips the save, names file
Can be relaxed per task	n/a	n/a	n/a	`inputStability`

Turborepo 2.11.7

It takes the hash before the run and saves the outputs under it.

Inputs are not checked again
(save_outputs).

Nx 23.3.0

It hashes in processTask and saves with cache.put(task.hash, …).

In batch mode, a task that reads its dependencies' outputs is hashed
again (task-orchestrator.js, cache.js).

Vite Task (vite-plus 1.1.0)

It traces the files a task opens. If the task wrote a file it also read,
it skips the save (InputModified).

Writes by other processes are not traced
(cache_update.rs).

vx

$ vx run packages/api#build
┌─ packages/api#build > $ echo "export const r = $RANDOM" > src/routes.gen.ts && mkdir -p out && cp src/index.ts out/
[vx] packages/api#build: `packages/api/src/routes.gen.ts` changed after its key was taken — the result stands, but is not saved under a key that no longer describes it; if the task writes it, declare it in cache.outputs
└─ packages/api#build ── (6ms) success
  cache     1 not saved

One-project workspace · vx c1ad075 · 2026-10-23

vx checks every declared input after the run, whoever wrote it. A
changed input keeps the result and saves nothing, and tasks downstream
skip their save too.

cache.inputStability relaxes it per task
(how).

Each one is a trade

vx pays one lstat per input on a run that saves. Turborepo and Nx skip
that work. Vite Task checks what its tracer already saw. Which fits
depends on how often your inputs move during a run.

More at vznjs.github.io/vx.

Originally published on the vx blog. vx is open-source (MIT) task orchestration with a build cache: vznjs.github.io/vx · GitHub.

Written with AI assistance.