DEV Community

Cover image for The cache on your terms
VX
VX

Posted on Edited on Originally published at vznjs.github.io

The cache on your terms

Turn the cache off, refresh it, or read one layer and write another.
Every clone of a repo shares one store. A pull request never writes
what main reads.

Three switches

$ vx run build --all
  cache     local 4✓
  time      15ms

$ vx run build --all --force
  cache     local 4↑
  time      56ms

$ vx run build --all --no-cache
  cache     local 4∅
  time      42ms
Enter fullscreen mode Exit fullscreen mode

--force runs everything and saves what the cache lacks. It doesn't
upload a key that's already stored. --no-cache neither reads nor
writes. --cache-policy sets read/write per layer:

$ vx run build --all --cache-policy=local:rw,remote:r   # read the remote, never upload
$ vx run build --all --cache-policy=local:r             # read local, write nothing local
$ vx run build --all --cache-policy=local:,remote:rw    # skip local, still upload
Enter fullscreen mode Exit fullscreen mode

VX_CACHE_POLICY sets it for a shell or CI job, cache.policy in
.vx/workspace.ts sets the default. The flag wins. A lookup always asks
the local cache first, then each remote in order.

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

export default defineWorkspace({ cache: { policy: 'local:rw,remote:r' } })
Enter fullscreen mode Exit fullscreen mode

An empty spec is refused, not read as "everything on":

$ vx run build --all --cache-policy=
✗ vx run  --cache-policy needs a spec like local:r, local:rw, remote:, or local:,remote:rw — pass --no-cache to disable every axis

  see vx run --help
Enter fullscreen mode Exit fullscreen mode

One store for every checkout

Artifacts live in ~/.vx/<id>/cache, keyed by the repo's remote. Each
checkout keeps only a small index. A fresh git worktree hits what the
first one built:

$ git worktree add ../demo-wt && cd ../demo-wt
$ vx run build --all
  cache     ▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰
            local 4↓
  time      30ms
Enter fullscreen mode Exit fullscreen mode

The new worktree had no dist. All four builds came back in 30 ms.
Move the cache with --cache-dir, VX_CACHE_DIR or cache.dir.

Who may write the remote cache

A remote cache is shared, so a write affects everyone who reads it. The
policy says whether a run writes at all: off CI, the default only reads.
The cache server says where a write lands:

diagram

  • The server checks the CI token and sends a write to the branch's own scope, or nowhere. Only main's CI writes main.
  • A read tries the branch's scope first, then main's.
  • The local cache has no branches, so the same inputs hit locally on any branch.

Branch caches a server enforces
shows how a server builds its half.

Demo workspace · vx 4c308fb · 2026-10-23

Every flag: CLI reference. cache: 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.

Top comments (0)