Keep a model forever. Run it tomorrow.

pipx install darsay

darsay archive Qwen/Qwen3-0.6B
darsay run     qwen--qwen3-0.6b "Say hello"

A pinned snapshot of the Hub — hashed, licensed, and still loadable as-is.
The Hub is a living website. A darsay bundle is a museum piece that still runs.
_{Python 3.10+ · macOS and Linux · Apache 2.0}

Start here · Concepts · Examples · All docs · Contributing

The idea in four lines

You have a vault. It holds bundles. A catalog is a list of sources you intend to archive — shareable before any payload exists.

Each bundle is one pinned revision of one source: an immutable payload (model/ or data/), a manifest.json of recorded facts, and one file you write by hand (curation.md).

archive puts the snapshot in the vault. run speaks to it offline. export packs it into a single .mvb.tar that any tar can open in 2040. list is the vault as a catalog view; list summer overlays a want-list.

The payload never changes. The Hub can.

  Hugging Face                         your disk
  ────────────                         ─────────
  Qwen/Qwen3-0.6B                      vault/
       │                                 │
       │  darsay archive                 │
       └──────────────►──────────────────┤
                                         │
                          qwen--qwen3-0.6b/<rev>/
                          ├── model/           frozen snapshot
                          ├── manifest.json    recorded facts
                          └── curation.md      your notes
                                         │
                          darsay run ────┘──► tokens, offline

New here? Take the guided first bundle (~five minutes with a tiny model). Want the mental model in full? Concepts. Want copy-paste recipes? Examples.

Install

Requires Python 3.10+. Isolated CLI tools are the intended way to run a release; see distribution.

pipx install darsay
# or, no install at all:
uvx darsay --help
# or:
uv tool install darsay

brew install darsay-io/darsay/darsay

python3 -m venv .venv
.venv/bin/pip install -e .                      # core: huggingface_hub only
.venv/bin/pip install -e ".[fast-hash,smoke]"   # + blake3, tokenizers
.venv/bin/pip install -e ".[inference]"         # + transformers/torch for in-process smoke
.venv/bin/pip install -e ".[datasets]"          # + pyarrow for measured dataset row counts
.venv/bin/pip install -e ".[dev]"               # pytest
.venv/bin/pytest                                # unit + integration; see docs/TESTING.md

The vault root defaults to ~/darsay (override with --vault or $DARSAY_HOME; --vault works before or after the subcommand). Bundles are gitignored in this checkout — they live on disk or in your backup tier, not in the git repo.

The three verbs

1. Estimate — price the source from Hub metadata. Nothing downloaded.

darsay estimate Qwen/Qwen3.8-27B

Qwen/Qwen3.8-27B @ main -> 1d4bf0f2ff60
  image-text-to-text | license apache-2.0
  parameters:   27.78B BF16  [upstream safetensors metadata]
  payload:      32 files, 51.8 GiB
  engines:      transformers
  completeness: complete
  download:     ░░░░░░░░░░░░░░░░░░░░░░░░    0.0%   0 B / 51.8 GiB
                nothing banked yet — full 51.8 GiB in 32 files to fetch
  bundle:       ~/darsay/qwen--qwen3.8-27b/1d4bf0f2ff60  (new)
  disk:         needs ~55.5 GiB, free 1022.6 GiB — OK

To archive: darsay archive Qwen/Qwen3.8-27B

Exits non-zero when free space is insufficient, so it doubles as a guard in scripts. --variants lists the quantized ecosystem. --include '*Q4_K_M*' prices one file inside a huge GGUF pack. When a partial archive already exists, the download block prices the resume instead — verified, partial, and unverified bytes are banked, and only the remainder counts against disk:

  download:     ██████▋░░░░░░░░░░░░░░░░░   27.4%   14.2 GiB / 51.8 GiB
                banked 14.2 GiB = 12.1 GiB verified in 8 files + 2.1 GiB partial in 1 file
                still to fetch 37.6 GiB in 24 files

2. Archive — pin a revision, fetch bytes, hash them, write the manifest.

darsay archive Qwen/Qwen3-0.6B

Ctrl-C is fine. Budgets are fine. The same command resumes:

darsay archive Qwen/Qwen3.8-27B --max-gb 10     # tonight
darsay archive Qwen/Qwen3.8-27B --max-gb 10     # tomorrow
darsay archive Qwen/Qwen3.8-27B                 # finish, verify, register

3. Run — isolated env, fully offline, payload untouched.

darsay run qwen--qwen3-0.6b "Say hello"

Or skip the tool and point any Hugging Face-compatible loader at the payload:

from pathlib import Path
from transformers import AutoModelForCausalLM, AutoTokenizer

path = Path.home() / "darsay/qwen--qwen3-0.6b/<rev>/model"
tok = AutoTokenizer.from_pretrained(path)
model = AutoModelForCausalLM.from_pretrained(path)

No unpacking. No conversion. The archived files are the model.

A bundle

vault/qwen--qwen3-0.6b/<revision12>/
├── model/              # immutable payload: pristine snapshot of the upstream repo
├── manifest.json       # machine-readable record — the source of truth
├── README.md           # human-readable summary, generated from the manifest
├── VERIFICATION.md     # latest verification report
├── verification.json   # verification history (last 50 runs)
├── curation.md         # curator's notes — the only hand-edited file
├── exports.json        # log of single-file exports (after first export)
├── hydration.json      # runnable-env record + run history (after first hydrate)
├── transfer.json       # disposable resumable-transfer ledger
├── transfer.lock       # transient writer lock (only during archive/assemble)
└── LICENSE             # upstream license text, surfaced at the root

The payload under model/ (or data/ for datasets) is immutable after archiving; the bundle hash covers it alone.

Commands

Source refs are provider-qualified — huggingface:Qwen/Qwen3-0.6B, huggingface:datasets/owner/name. Unprefixed owner/name / datasets/owner/name and huggingface.co URLs are Hugging Face shorthand. An unprefixed owner/name that exists only as a dataset is resolved at pin time to huggingface:datasets/owner/name.

darsay estimate Qwen/Qwen3.8-27B --variants
darsay estimate unsloth/Qwen3.8-27B-GGUF --include '*Q4_K_M*'
darsay archive  unsloth/Qwen3.8-27B-GGUF --include '*Q4_K_M*'
darsay classify OBLITERATUS/Qwen3.8-27B-OBLITERATED   # master/print verdicts per weight set
darsay archive  OBLITERATUS/Qwen3.8-27B-OBLITERATED --full   # whole repo, skipping the masters-first default
darsay estimate datasets/saidutta69/fable-5-premium
darsay archive  datasets/saidutta69/fable-5-premium
darsay archive  Qwen/Qwen3.8-27B --revision v1.0      # pin a tag or commit instead of main
darsay archive  Qwen/Qwen3.8-27B --max-gb 10          # pause; rerun to resume
darsay archive  Qwen/Qwen3.8-27B --min-free 10G       # pause below 10 GiB free
darsay archive  Qwen/Qwen3.8-27B --yes                # bank what fits even if the disk cannot hold it all
darsay archive  Qwen/Qwen3.8-27B --max-rate 5M        # cap at 5 MiB/s
darsay archive  Qwen/Qwen3.8-27B --max-offline 4h     # wait out a lost network longer
darsay config                                         # effective settings + config files
darsay doctor                                         # offline diagnostics; writes evidence only
darsay doctor --fix --json                            # low-risk repairs + stable automation output
darsay doctor undo latest                             # restore the prior bytes/state
darsay archive  Qwen/Qwen3.8-27B --dry-run            # verified / partial / missing
darsay archive  Qwen/Qwen3.8-27B --shard 1/3 --max-gb 20
darsay --vault ./combined assemble /usb/alice/<bundle> /usb/bob/<bundle>
darsay list --json
darsay du
darsay rm       <bundle> --yes
darsay complete zsh                                   # eval "$(darsay complete zsh)"
darsay smoke    <bundle> [--inference]
darsay info     <bundle>                              # path, id, or unique prefix
darsay regen    <bundle>                              # rebuild README after editing curation.md
darsay hydrate  <bundle> [--dry-run]
darsay envs [--prune]
darsay dehydrate <bundle>
darsay rm       <bundle> -n                           # -n / --dry-run: same checks, nothing written

When you need more

verify re-hashes the payload against the manifest and exits non-zero on drift — suitable for cron. import fully re-hashes before a bundle enters the vault; failures register nothing.

run hydrates first: picks an engine from what the payload ships (safetensors → transformers, GGUF → llama-cpp), builds a dedicated venv outside the bundle under <vault>/.runtime/, and infers with HF_HUB_OFFLINE=1. Envs are disposable. Design: docs/HYDRATION.md.

Documentation

The tool is replaceable. The formats are not — plain JSON and plain tar, each documented for recovery without darsay. Full rationale: docs/DESIGN.md.

License

Apache License 2.0. See LICENSE. Bundles record upstream model and dataset licenses separately in manifest.json; those do not change the license of this tool.