Caching your builds

Build in CI, push only your novel paths to Vega, and pull them back on your machines.

Vega's tenant tier is a per-namespace cache: a verified CI build publishes immediately under tenant/<owner>/<repo>, signed with a key derived for that tenant. No cross-party agreement is involved (that is the shared tier); this is the path for caching your own packages or NixOS closures.

Declare what to cache: vega.yaml

Put a vega.yaml at your repository root listing the flake outputs to build and attest. The agent reads it and builds each one:

builds:
  - packages.x86_64-linux.mytool
  - attr: nixosConfigurations.myhost.config.system.build.toplevel
reproduce: false        # request shared-tier reproduction for these outputs
privacy:
  continent: true       # publish the builder's continent (continent only)
  pseudonym: false      # attest under your GitHub handle

A bare string is shorthand for { attr: <name> }. A present-but-invalid vega.yaml is a hard error, not a silent skip.

Push from CI

Check out your repo (so the agent can read vega.yaml and your flake), then run the agent. It builds each declared output on a GitHub-hosted runner and uploads and attests the result, authenticated by a GitHub Actions OIDC token:

permissions:
  id-token: write
  contents: read
jobs:
  cache:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@<pinned-sha>
      - uses: Ad-Astra-Computing/vega-agent/agent@<pinned-sha>
        with:
          control-plane: https://vega-cache.dev
          skip-upstream: "true"

Without a vega.yaml, pass a single installable input instead (e.g. an absolute flake reference); the checkout is then optional.

Upload only novel paths

A NixOS closure is mostly stock nixpkgs that cache.nixos.org already serves. With skip-upstream: "true" the agent skips every closure path the upstream cache already has and uploads only your genuinely novel paths, so caching a system closure does not re-upload all of nixpkgs. Recommended for routine caching. Leave it off only when you deliberately want to attest the full closure for reproducibility.

Pull your builds back

Fetch your tenant's public key, then add the namespace as a substituter on each machine:

curl https://vega-cache.dev/tenant/<owner>/<repo>/key

extra-substituters = https://vega-cache.dev/tenant/<owner>/<repo>
extra-trusted-public-keys = vega-<owner>-<repo>-1:<from the endpoint above>