Push
odu cache push uploads the paths a bucket is missing, with retries, and records each one as it lands. It talks to the cache directly, so you run it on the machine that holds the paths. Plain nix copy works too, with no odu on the client.
Commands are written with the odu shorthand. An odu ci run pushes for you: see What a run pushes.
Give it a cache token
Save a write cache token for an origin once:
odu cache login http://127.0.0.1:18440
It reads the cache token from stdin, or from --token <token>, and writes one entry per origin to ~/.config/odu/cache/credentials (mode 0600). odu cache push takes the first of:
--token-file <path>$ODU_CACHE_TOKEN- the saved entry for the bucket’s origin
Tokens says how to mint one.
Push to a bucket
In CI, export the secret and name the cache by its substituter URL. This is the block a bucket’s Set up → push tab shows, with the cache token filled in when you mint one there:
# push — a write token, where the build runs
export ODU_CACHE_TOKEN=<your-write-token>
odu cache push --cache https://odu.example.com/cache/main <paths>
--cache <substituter> takes the URL already in your nix.conf, and reads the push origin and the bucket from that cache’s own nix-cache-info. A CI job then holds nothing that goes stale when a bucket gains a domain or moves stores.
In a shell where you know both, name the bucket and its origin instead:
export ODU_CACHE_TOKEN=<your-write-token>
odu cache push main <paths> --origin https://odu.example.com
--cacheand a named bucket are exclusive.- A bucket name is resolved against the origin you logged in to. A full
https://<host>/cache/<bucket>URL, asodu cache useprints, also works. - A cache that does not state its origin and bucket, or does not answer, is refused with a sentence naming the URL.
--output jsonreturnsserved,substituter,modeandpinned.
Push to the flake’s cache
With neither --cache nor a bucket, odu cache push <path>… pushes to the one odu substituter ./flake.nix’s nixConfig names. Two odu caches there is a refusal.
- It probes that substituter without a cache token, so a private bucket must be named with
--cache. - It sends only a credential saved for that origin with
odu cache login.--token-fileand$ODU_CACHE_TOKENwork for any origin, so they are not sent to a URL the repository named. - To send your own cache token, name the cache:
odu cache targetprints the URL to pass to--cache.
Naming a cache is trusting it.
--cachesends your cache token to the substituter you name, then pushes to whatever origin itsnix-cache-infostates. Name only a cache you trust, as you already do innix.conf.
What it prints
One summary line, then one line per path as the bucket answers:
118 paths in the closure: 6 to push, 108 already here, 4 upstream
✅ /nix/store/…-odu-0.1.0/bin/odu stored
⏳ /nix/store/…-big-output part 3
❌ /nix/store/…-bad-output refused: the upload was truncated or corrupted
- A path is recorded as it lands. References are names in the narinfo, so the bucket need not hold them first.
- The exit is non-zero only when a path is refused.
- The bucket keeps the upload as it arrived. Where the bytes go depends on the bucket’s store: see Direct and staged uploads.
- A large NAR goes in parts of
--part-sizeMiB (64 by default), each retried on its own.
Pin what you pushed
--pin NAME re-points that pin at the closure this push landed, so garbage collection keeps it.
- Nothing is pinned if any path was refused.
--output jsonreportspinned: {name, rootPaths}, ornullwhen you asked for no pin.- A write cache token may pin. It may already keep a closure alive by pushing it again, so pinning grants it nothing new.
Keep and reclaim says what a pin holds.
Say what built a path
--run ID and --commit SHA state what built these paths. The bucket keeps both on every path this push stores, and its page shows the commit, short, and the run as a link to its page.
- Both are opaque strings. The cache never resolves them.
- The first push to state a fact keeps it. A push that states neither leaves what a run stated, so your bare re-push of a path CI stored keeps its origin.
- The two are independent, so the GitHub action states only
--commit. odu ci runstates both without being asked. A path pushed by hand, with neither, shows neither.
Push a closure that is fetched from this bucket alone
By default a bucket skips the paths an upstream key signed, because cache.nixos.org already serves them. A client that runs nix copy --from <bucket> <path> reads that one cache, and stops at the first path the bucket lacks. For such a client, push with --whole:
odu cache push --cache https://odu.example.com/cache/main --whole <paths>
--wholestores every path of the closure the bucket lacks, upstream-signed ones included. The summary then saysskipped-upstream 0.- It applies to this push only. The bucket’s
upstreamKeysstay as they are, so a push without the flag still skips those paths. - If the service is too old to store the whole closure, the push stops before sending anything and says so.
- The upstream paths cost disk in the bucket. Each is stored once, however many closures share it.
Push with plain Nix
nix copy --to works with no odu on the client:
nix copy --to http://127.0.0.1:18440/cache/main ./result
Nix reads credentials only from the file its netrc-file setting names (/etc/nix/netrc by default), never from ~/.netrc on its own. Use the netrc lines from Use it, with a write cache token in place of <your-read-token>. odu cache use prints a placeholder rather than a cache token, because the block goes into files people read and commit.
In CI, put the cache token in the URL instead of a file. The bucket accepts any username, with the cache token as the password:
nix copy --to "http://x:$ODU_CACHE_TOKEN@127.0.0.1:18440/cache/main" ./result
Plain nix copy --to compresses each NAR in memory on the client before it uploads, and asks about one path at a time. It sends xz by default, and ?compression=zstd sends zstd. Prefer odu cache push for large closures.
Compared with cachix push and attic push
| cachix push | attic push | odu cache push |
|
|---|---|---|---|
| Closure, batched missing query, retries | yes | yes | yes |
| Skips paths cache.nixos.org already has | yes | yes | yes: the bucket drops paths an upstream key signed, cache.nixos.org-1 by default, or none with upstreamKeys: []. --whole keeps them for one push. |
| Streams NARs, parallel uploads | yes | yes | yes: nix store dump-path through zstd, several paths at a time, retried per path |
| Uploads bypass the server | yes, straight to S3 | no | yes on an S3 store: odu signs the URLs, then reads the object back and verifies it. A disk store takes them through the service. |
| Dedup | per NAR | per chunk | per NarHash, per bucket |
| Pushes every build as it happens | watch-exec, watch-store |
watch-store |
no: a job pushes the closures it names |
| Client signs with its own key | optional | no | no; the server signs |
| Client to install | cachix | attic | odu itself, or nothing: nix copy with netrc |
A bucket created with upstreamKeys: [] also stores upstream closures, which costs disk, for clients that cannot reach cache.nixos.org.