Summary#
Run osy restore once where there is a network; from then on the project locks, validates and tests where there is
none — a CI job with no egress, a sandboxed agent, a plane. It is the step dotnet restore or npm ci is in other
toolchains: it fills the package cache and leaves your files exactly as they were.
Signature#
osy restore # this project, into this machine's package cache
osy restore path/to/app # another project
osy lock # keeps every pin its `use` still accepts — no network for those
osy lock --offline # asks no network at all, even for what is not cachedDescription#
Two verbs make a project independent of the network. osy restore runs where there is one and fills the package
cache; osy lock reads that cache before it asks GitHub anything, and keeps every pin the lock already holds while
your use lines still accept it. osy validate and osy test read the lock and the cache and never search.
What osy restore fetches#
It resolves the project exactly as osy lock would — the same resolution, with the write left out — and keeps what
that resolution needed in the package cache:
- every release the project's
uselines and their own dependencies resolve to, and every release theosyrin.lockon disk pins today; - the release lists each package's versions were chosen from;
- the bridge search's answers — which published packages complete the ones your app uses — with the note each
was given under, so an offline lock records the same
bridgessection an online one does.
It exits 0 when all of that is in the cache, and 1 with one line per thing it could not fetch. It never writes
osyrin.lock; osy lock does that.
$ osy restore
Osysharp.Charts 1.8.0
Osysharp.Identity 0.9.0
…
✓ Restored 9 packages and the catalog answers into /home/you/.osy/packages — this project now locks, validates and tests with no networkWhere the cache is#
The package cache is packages/ under $OSY_HOME (default ~/.osy/packages), shared by every project on the
machine. Point OSY_HOME somewhere else to give a job a cache of its own — fill it with osy restore on a host with
a network, then hand the directory to the job. The job only reads it.
Locking with no network#
osy lock keeps a pin osyrin.lock already holds when the project's use still accepts that version and its
archive is in the cache: nothing is asked of the network for it. So a lock of an unchanged project, with the network
gone, writes a lock byte for byte the same as before. Moving a pin to a newer release inside its major is
osy update's job (package.osy), never osy lock's.
When GitHub cannot be reached, everything else the lock needs is answered from what the cache remembers: the release lists and the bridge search's last answer. The lock then prints one line saying the answer was read from the cache, and records the search as it was made.
--offline asks no network at all: the bridge search reads only the remembered answer, and when there is none it
records that the public search was skipped.
When it still needs the network#
A use the cache cannot answer — one you just added, a constraint you changed, a cache never filled — needs the
network, and the lock says so for each one, naming the cache and the command that fills it:
✗ PACKAGE_FETCH_FAILED: Acme.Crm: Connection refused — GitHub could not be reached, and `use Acme.Crm@0;` needs a release this machine does not hold, so it needs the network. The package cache (/home/you/.osy/packages) holds no answer to use instead — run `osy restore` where there is a network to fill it, then run this again offline.Nothing is written when that happens; the lock on disk is left as it was.
When the tools reach GitHub#
A project whose osyrin.lock pins every package it uses, with those archives in the cache, is checked with no
request at all — so a loop of validate and test never spends a GitHub token's hourly limit.
| Verb | Reaches GitHub when |
|---|---|
osy validate, lint, test, check, explain, model, compile | a pinned release is not in the cache (one download of exactly that version, not an API call), or a use is pinned by no lock this project reads (one version list) |
the same verbs in a workspace package (packages/<name>/ of an app's repository) | only as above: a package with no lock of its own is checked against the releases the app's osyrin.lock pins |
osy lock | for a use no lock pins yet, and for the bridge search |
osy update | always — its question is "what is the newest release"; a remembered version list is re-checked with a conditional request, which costs no API budget when nothing changed |
osy restore | to fill the cache |
osy kit, osy kit atoms, osy docs | never |
A version list GitHub answered is kept in the package cache. Within ten minutes it is used with no request; after that it is re-checked conditionally; and when GitHub cannot be reached, or the token's limit is spent, the kept list stands in. When nothing can stand in, the refusal names the package, the constraint and the time the limit resets:
✗ PACKAGE_FETCH_FAILED: Acme.Crm: the versions of acme/crm (to choose one for `@0`) could not be listed: GitHub's API limit for your token is spent — it resets at 21:07 (in 4 min). No lock this project reads pins it, and this machine has never listed them, so nothing can stand in. Run it again then; a project whose `osyrin.lock` pins every package it uses needs no listing at all.osy lock in the project that uses the package records the pin, after which nothing asks again.
See also#
- package.osy — what a pin is, and
osy update - Bridges — a package that arrives when an app uses the two it completes — the packages the bridge search includes by themselves
- Checking your app —
osy check, which validates, lints and tests