Work offline

What happens

03The agent runs vibe cache add for the extra package, which resolves it and its whole dependency closure and fetches every node into the store without touching the project. It runs vibe install once online so the project's own packages are in the store too, then vibe cache check to verify every stored entry against its fingerprint. Finally it runs vibe install --offline: resolution and fetch are satisfied from the store alone, and the command fails loudly if anything is missing rather than installing a partial graph.

04 Under --offline, resolution and fetch must be satisfiable entirely from local sources — the cache (§2.7), [[mirror]] entries with a file:// URL, and the project's own vibe.lock + vibedeps/.

By hand

051. Warm the store with a package and its dependencies. Inside a project its registries are the source; outside one, the machine-wide registries:

vibe cache add org.vibevm.world/wal

Pre-warming the machine store (<TMP>/home/cache)
  ✓ created  org.vibevm.world/wal@1.0.0

1 fetched, 0 already present — nothing materialised into any project.

072. See and verify what the store holds:

vibe cache list

GROUP             NAME  VERSION
org.vibevm.world  wal   1.0.0

1 package in <TMP>/home/cache.

vibe cache check

Integrity sweep of the machine store (<TMP>/home/cache)

1 ok, 0 mismatched, 0 unrecorded.

103. Install without a network:

vibe install org.vibevm.world/wal --path hello-vibe --offline --assume-yes

Resolving 1 root package…

Materialising 1 package into vibedeps/:
  org.vibevm.world/wal@1.0.0

closure diff:
  → + org.vibevm.world/wal@1.0.0 (root-edge)
  → lane vibevm/vibespecs/boot/INDEX.md: 737 -> 854 B

Materialised 1 package into vibedeps/; regenerated boot artifacts for 1 node(s).

Three ways to switch offline mode on

12The flag --offline on any command; the environment variable VIBE_OFFLINE=1; or the setting offline = true under [net] in ~/.vibe/config.toml. The flag wins over the variable, and the variable over the setting. Online remains the default.

13 It resolves through the established CLI config layering — flag, then a VIBE_OFFLINE environment variable, then a user-config [net] key; the flag wins. This mirrors the resolved-posture pattern already used for --unattended / VIBE_UNATTENDED (output::resolve_unattended).

A whole team without a network

14For a machine that never sees the registry, vibe registry vendor writes a folder holding every package the lock file references, ready to be used as a mirror with a file:// address on the other side. The fingerprints travel with it, so the mirror is verified like any other.

15 Decision. [[mirror]] entries are parallel alternative URLs for a specific registry (or * for any). During fetch:

Edge cases and rules

16If an offline install refuses a package the store already holds, the project's registries were never cloned on this machine and vibe cannot learn which versions exist; one online install in any project clones them, and a file:// mirror needs no clone at all.

17Offline resolution sees the store as of its last refresh: a version published after you went offline is invisible until you are back and run vibe registry sync or an online install.

18 Offline resolution is therefore computed against the cache as of its last refresh. This is correct and expected — Maven mvn -o and cargo --offline have the same property — but it must be explicit: a --offline resolve may pick an older version than an online resolve would.

19A package in the store is usable even when its registry no longer lists it; a package that never reached the store is a hard error naming the missing coordinate.

20 Anything not available locally is a hard error with an actionable message: it names the missing package and version and tells the operator how to recover (run once online, vibe cache add, or vibe registry vendor).

21The program's own version manager obeys the same posture: under it vibe self update, install and reinstall refuse before their first request, naming the address they would have needed, and self ls, current and which answer from the machine as usual.

22 Every self verb honours the offline posture the process resolved — --offline, VIBE_OFFLINE or [net] offline, layered as PROP-010 ##OFFLINE-LAYERING says. Under it a release-lane verb is refused before its first request, naming the verb and the address it would have needed; a source-lane rebuild runs without fetching when the checkout and the crates are already local, and is refused the same way otherwise. The domain never reads the environment for this: the composition root hands the resolved posture in.