Keep a model forever. Run it tomorrow.

pipx install darsay

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

Pinned Hub artifacts — hashed, licensed, and kept in their published formats.
Preserve the bytes. Prove supported selections still run offline.
_{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 works 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
  archive:      the whole repo — 1 negative set (28 files, 51.7 GiB); nothing here is a print
  parameters:   27.78B BF16  [upstream safetensors metadata]
  precision:    BF16 — 2.00 B/param: about one 16-bit weight copy
  family:       Qwen · generation 3.8 · member 27B  [read from the name]
  architecture: qwen3_5  [config.json]
  lineage:      no parents declared upstream
  payload:      32 files, 51.8 GiB (archive)
  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. The payload names its scope: repository, selection, or classified archive. precision: explains one complete weight variant's bytes per parameter; family: places the work in its lineage (Concepts). GGUF packs list each variant with the total of all its shards; --variants lists other repositories in the quantized ecosystem. --include '*Q4_K_M*' prices the matching variant inside a GGUF pack. For example, the 321B-parameter GLM-5.3-Flash GGUF repository contains 2.315 TiB across twelve variants, while its UD-Q4_K_XL weights occupy 186.0 GiB (case study). Archive totals can include several variants and unresolved weights; classification does not choose one precision for you. 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: selected upstream files, byte-for-byte
├── manifest.json       # machine-readable record — the source of truth
├── README.md           # human-readable summary, generated from the manifest
├── SHA256SUMS          # the payload's hash list: `sha256sum -c` verifies it with no darsay
├── 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, code/ for repositories) 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, github:owner/repo. Unprefixed owner/name / datasets/owner/name and huggingface.co URLs are Hugging Face shorthand; a github.com repository URL is GitHub's. An unprefixed owner/name that exists only as a dataset is resolved at pin time to huggingface:datasets/owner/name. A repository archives as a code bundle (Code bundles).

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   # negative/print verdicts per weight set
darsay archive  OBLITERATUS/Qwen3.8-27B-OBLITERATED --full   # every published file and layout
darsay estimate datasets/saidutta69/fable-5-premium
darsay archive  datasets/saidutta69/fable-5-premium
darsay archive  github:MiaAI-Lab/Qwen3.8-Flash-Next-Single-DGX-Spark   # a repository at a commit, payload under code/
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 --vault /Volumes/big assemble ~/darsay/<bundle> --handoff   # partial: hand verified files over, keep a skeleton
darsay migrate  <bundle>                              # a record from an older darsay → this schema; payload untouched
darsay migrate  --all -n                              # every such record in the vault: the plan, nothing written
darsay mv       <bundle> /Volumes/big                 # registered: rename or copy+verify, then remove the source
darsay cp       <bundle> /Volumes/backup              # registered: verified copy; source kept, replica recorded
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.