awstorage

Docs · Source · pip install awstorage · The Aither World

The Aither World is an operating system for agents — a Linux you can hand to one, the runtimes it works in, and the tools it works with. awnix is the Linux underneath it; awstorage is one of its 71 bricks — each installs on its own, runs offline, and needs no account. 5 more are in development and 15 are planned.

Start here: Scan one drive and read a ranked inventory of what fills it, with each tree marked re-fetchable or not.

Every drive on every node, indexed, classified and diffed -- so you can see what you own before you delete it.

```bash
pip install git+https://github.com/Aitherium/awstorage.git
awstorage scan E:/ --depth 3 --catalog inventory.db
awstorage inventory --catalog inventory.db
awstorage propose --catalog inventory.db --snapshot 1
awstorage apply   --catalog inventory.db --proposal 3 --root E:/        # dry run
awstorage apply   --catalog inventory.db --proposal 3 --root E:/ --yes  # quarantine it
awstorage revert  E:/.awstorage-quarantine/3-20260901T230000            # changed your mind

Stdlib only. Works alone, offline, on the box whose disk is full.

What it does

1. Scan a root into a snapshot: every directory tree to a bounded depth with its bytes, file count and newest mtime, plus the largest files. Bounded by a time budget; a scan that runs out marks the snapshot TRUNCATED instead of printing a total that looks complete and is not.
2. Classify each tree: package-cache, build-temp, model-weights, container-store, dataset, backup, repo, logs, service-state, media, vm-disk, unknown -- and whether it is re-fetchable. Heuristics offline; plug any complete(prompt) -> str model callable into LLMClassifier and every verdict records whether a rule or a model made it, so a wrong call is auditable.
3. Catalog snapshots in SQLite and diff them: what appeared, vanished, grew and shrank since last time. "What filled the disk?" becomes a query.
4. Propose actions under a written policy. Rules pre-approve only re-fetchable classes past a size and an age; service-state, dataset, vm-disk, backup and unknown are never auto. Everything else is proposed for a human to approve.
5. Apply -- dry run by default. A delete is a quarantine: the tree is renamed onto the same volume under <root>/.awstorage-quarantine/, revert puts it back byte-for-byte, and only quarantine --purge-older-than N --yes reclaims the bytes. apply refuses anything outside the declared roots, anything that changed since the scan, and anything neither pre-approved nor approved. Every outcome is ledgered.
6. Sweep -- named retention rules, unattended: live guard, harvest-first (verified, secrets withheld), link-safe removal, a receipt on every exit path. See below.
7. Index files (awstorage files ...): one row per file in files.db (the catalog's sibling), searchable by file name (SQLite FTS5, trigram), rolled up by directory, with duplicates found by size bucket, then a head+tail partial hash, then a full sha256 -- hard links collapse, and actionable_bytes counts only copies a manage action could really reclaim. Rescans are incremental: only files whose size, mtime or hash changed are written (each takes a new seq); files a COMPLETED walk no longer sees become tombstones; a truncated walk deletes nothing. On Windows NTFS a repeat scan reads the USN change journal since the last walk and re-reads only the directories it names -- no admin needed; any doubt is a full walk, and the scan JSON says which (mode, usn_fallback_reason). Credential-shaped files (.ssh, .env*, *.pem, ...) are indexed but flagged and redacted for any non-platform reader (awstorage.guards).

```bash
awstorage whoami                                  # AWSTORAGE_NODE > ~/.aither/node-id > hostname
awstorage files scan E:/ D:/Media --hash auto     # index + hash only possible dupes
awstorage files scan --all-volumes                # every fixed volume minus the never set
awstorage files find quarterly report --ext pdf   # every word, substring of the name
awstorage files dupes --min-bytes 1048576         # most waste first
awstorage files tree E:/ --depth 2                # sizes by path, from the rollup
awstorage files nodes                             # what is indexed, and how stale
awstorage files push                              # DELTA since the fleet's last seq
awstorage manage shares                           # python -m awstorage.manage

find|dupes|tree read the FLEET index when a session bearer exists (--remote; --local reads this node's files.db).

Python

```python
import awstorage
from pathlib import Path

snap = awstorage.classify_snapshot(awstorage.scan(Path("E:/"), max_depth=3))
cat = awstorage.Catalog("inventory.db")
sid = cat.put_snapshot(snap)
for row in awstorage.rank(snap)[:10]:
    print(row["exclusive_bytes"], row["cls"], row["refetchable"], row["path"])
props = awstorage.propose(snap, awstorage.default_policy(), snapshot_id=sid)
awstorage.apply(props[0], roots=[Path("E:/")], dry_run=True)

Sweep agent scratch automatically

scan -> propose -> apply wants a person between the steps. The thing that filled drive C: on 2026-09-27 (122 MB free, a WSL root fs corrupted mid-boot) did not: 173 GB of per-session agent scratchpads under %LOCALAPPDATA%\Temp\claude\<project>\<session>\ that nothing reaped -- one dead session held 106 GB -- plus ~19k stale Temp entries. sweep is the unattended half:

```bash
awstorage sweep --rules agent-scratch,temp-toplevel                  # dry run: the full plan
awstorage sweep --rules agent-scratch,temp-toplevel --yes \
    --harvest-to E:\AitherOS-Data\harvest --emergency-free-gb 40 \
    --receipt ~/.aither/awstorage/last_sweep.json

Schedule it with awrise:

```bash
awrise add --name awstorage-sweep --every 3h --detach --timeout 3600 -- awstorage sweep --rules agent-scratch,temp-toplevel --yes --harvest-to E:\AitherOS-Data\harvest --emergency-free-gb 40 --receipt ~/.aither/awstorage/last_sweep.json
awrise set --name awstorage-sweep receipt=~/.aither/awstorage/last_sweep.json

One pass: expand rules -> measure -> guard -> harvest -> remove -> ledger -> receipt.

• Rules are data, and opt-in by name. Shipped presets: agent-scratch (%LOCALAPPDATA%\Temp\claude\*\* on Windows, $TMPDIR/claude/*/* elsewhere; idle 12h) and temp-toplevel (%LOCALAPPDATA%\Temp\* minus the claude dir; idle 3d). Nothing is swept without a rule naming it. Your own rules go in a JSON --policy file:

  ```json
  {"retention": [{"name": "build-scratch", "paths": ["~/scratch/*"], "class": "build-temp",
                  "max_idle": "2d", "action": "quarantine", "purge_after": "3d",
                  "exclude": ["~/scratch/keep-*"], "live_guard": {"window": "2h"},
                  "harvest": {"include": ["**/*.md"], "max_file_kb": 256},
                  "snapshot": false}]}

One glob match = one item. class may not be a never-auto class (service-state, dataset, vm-disk, backup, unknown). - Age is the newest file inside the item, never the item's own mtime. - Live guard. An item that changed inside live_guard.window (default 2h), or whose name is registered live, is skipped and reported skipped-live. An agent runtime registers its session scratch through AWSTORAGE_LIVE_IDS (comma/space separated) or a --live-ids file (one id per line, # comments); an id matches the item's basename. An id containing a path separator is a PATH id: it keeps that exact dir, everything under it and every ancestor -- how a runtime marks a session dir with a generic name (scratchpad, tmp) live without shielding every dir of that name. An unreadable --live-ids file stops the sweep (exit 2) -- "nobody is live" is never a guess. - Harvest first. Small text files matching the include globs (default **/*.md, **/*.json, **/*report*, **/*eval*/**, **/results/**; 512 KB/file, 20 MB/item; NUL in the first 8 KB = binary) are copied to <shelf>/<rule>/<YYYY-MM-DD>/<item>/ with a manifest.json (item, bytes, file count, top-20 subdirs, every copy's sha256, every skip's reason). Every copy is re-read and checked (size + sha256) before the item may go; any failure keeps the item and exits 1. A file matching a credential pattern (sk-, ghp_, AKIA, xoxb-, private-key blocks, password=<value>, ...) is withheld: listed by name, never copied, the match never written. --harvest-offdrive refuses a shelf on the item's own drive. - Links are never followed. A symlink or Windows junction inside an item is unlinked; its target is untouched (removal, quarantine, purge and scan all ask the same is_link(), which sees junctions on every Python). - Quarantine by default. Items move to <base>/.awstorage-quarantine/sweep-<rule>-* (awstorage revert works on them) and are purged after the rule's purge_after. action: delete deletes outright -- only with --yes, like everything else. - Emergency. --emergency-free-gb N: when an item's drive has less than N GB free, that rule's max_idle (and purge_after) halve for the pass; harvest still runs first. A rule with emergency_delete: true (the two presets; regenerable classes only) DELETES instead of quarantining there -- only after the item's harvest verified -- because a same-drive quarantine frees nothing until purge_after (the first real run removed 1130 items and freed 0 bytes). Receipt: emergency_deleted, bytes_emergency_deleted; audit/ledger action deleted-emergency. - Purge every pass. Each rule purges its expired quarantine BEFORE its items, so a pass the time budget cuts still frees bytes (bytes_purged, counted in bytes_freed). - Per-item measure cap. --measure-cap-s (default 120): an item whose age walk runs past it is judged by its top-level mtime + its first 2000 files; all old -> eligible (size unknown (capped), listed in the receipt's capped), any fresh -> live, skipped. One 106 GB dead session otherwise eats a whole pass just being measured. - Bounded. --time-budget SECONDS (default 3000, inside awrise's 3600 s timeout) stops the pass cleanly and marks the receipt truncated; a fresh item's walk stops at its first too-new file instead of measuring 100 GB it will not touch. The next pass resumes, starting with the item the budget cut (resume_first in the receipt) -- a killed sweep would have left no receipt at all. - Receipt on every exit path: {exit_code, started, finished, items_seen, items_removed, bytes_freed, bytes_quarantined, bytes_harvested, skipped_live, errors, free_before, free_after, ...}. bytes_freed counts only bytes actually gone (deleted or purged); a quarantine is reported separately. Exit 0 clean, 1 an item failed (kept, reported), 2 could not judge (bad rule, unreadable root; nothing removed). Every decision is a ledger row in the catalog (--catalog, default ~/.aither/awstorage/catalog.db).

```python
import awstorage
receipt = awstorage.sweep(["agent-scratch"], dry_run=False,
                          harvest_to="E:/AitherOS-Data/harvest", emergency_free_gb=40,
                          receipt="~/.aither/awstorage/last_sweep.json",
                          live_ids=["<my-session-id>"])

Agents suggest deletions

Dead agent sessions held 106 GB on 2026-09-28 until a person found them by hand -- and the agents that made them knew they were dead. suggest lets any agent say so, and gives it no power beyond saying so:

```bash
awstorage suggest C:/Users/me/AppData/Local/Temp/claude/proj/4f2e... \
    --reason "my session ended 2 days ago" --by lyra \
    --evidence '{"bytes": 113800000000, "idle_hours": 48}'
awstorage suggestions                       # every suggestion, newest first
awstorage suggestion approve 42 --card card.json   # a decision card, never a bare yes
awstorage suggestion reject 42
awstorage apply-suggestions                 # dry run: the plan
awstorage apply-suggestions --yes           # re-verify, harvest, quarantine, ledger
awstorage suggestion revert 42              # put it back (and the agent's trust pays)
awstorage trust                             # the per-agent ledger

```python
r = awstorage.suggest(path, reason="session ended", suggested_by="lyra",
                      action="quarantine", evidence={"bytes": n, "idle_hours": 48})
# {"id": 42, "status": "auto-approved"|"pending-card"|"refused"|"duplicate",
#  "why": "...", "class": "build-temp", "size": 113800000000, "checks": [...]}
awstorage.suggestions(status="pending-card")
awstorage.resolve_suggestion(42, "approve", card=card)
awstorage.apply_suggestions(dry_run=False, harvest_to="E:/AitherOS-Data/harvest")

• Validated twice -- at suggest time and again at apply time; each step is a named entry in checks. Refused: a path that does not exist or is a link; under the never / sensitive / OS set, a quarantine, a volume root, the home dir or a path awstorage depends on; inside a git work tree that is dirty, has commits no remote holds, or that git cannot judge (walks up for .git; git status --porcelain, git rev-list @{u}.. and HEAD --not --remotes, each with a timeout); any file changed within the live window (2 h) or a path segment registered live (AWSTORAGE_LIVE_IDS); evidence that contradicts the measurement. A second open suggestion for the same path is a duplicate of the first.
• Two lanes. auto-approved only when ALL hold: a regenerable class (build-temp, package-cache; agent scratch and temp resolve to build-temp through the sweep presets, but a tree that names itself dataset/repo/... keeps that class), action quarantine (never delete, never archive), the evidence verifies (at least one of bytes, files, idle_hours, cls checked and none contradicted), no nested work tree is dirty or unjudged, the agent's IDENTITY is verified (below), and its trust clears the threshold. Everything else is pending-card: a decision card is raised through awstorage.suggest.set_card_hook (none by default: it waits in suggestions). Approving one needs a card that passes awstorage.manage.verify_card -- a SIGNED answer receipt (see "Signed answer receipts") -- the same check manage applies. Rejecting needs no card.
• Apply trusts no status. catalog.db is a file any local process can edit, so an approved row is re-verified: the card recorded at resolve (or the live card through set_card_reader(fn)) must pass manage.verify_card again, be the card the row names, carry the receipt whose digest was recorded at resolve, and carry a content_sha256 fact equal to the digest of the row as it stands now (path, action, node, class, size, ...). An auto-approved row re-judges every lane condition from disk and the verifier (class re-classified, quarantine only, evidence re-checked, identity re-verified against the proof stored at suggest time -- so a proof must be JSON-serialisable -- and trust). Anything that does not verify is refused; a status alone never deletes.
• Apply re-validates. Re-validation refused, or size / file count / newest mtime moved since the suggestion -> drifted, nothing touched. An auto approval whose agent's trust has since fallen goes back to pending-card. Then harvest first (the sweep's verified harvest), then a quarantine under <parent>/.awstorage-quarantine/suggest-<id>-* (awstorage revert works; purged after 72 h) -- or, card-approved only, a delete or an archive through set_archive_hook. Every step is a ledger row; the outcome is recorded on the suggestion.
• Trust is derived from the suggestion rows, never a separate counter: trust = (applied - 3*reverted + 1) / (applied + rejected + 2) (Laplace-smoothed). A new agent scores 0.50, under the default threshold 0.6 (AWSTORAGE_TRUST_THRESHOLD, clamped to at least 0.51), so its first suggestions go to cards; one revert of an applied suggestion costs three applications.
• Identity (0.4.1). suggested_by is declared by the caller and every caller is in-process, so the brick cannot tell an agent from something typing its name. The auto lane therefore needs a VERIFIED identity: a verifier installed with awstorage.set_identity_verifier(fn) (fn(suggested_by, proof) -> True) accepted the identity_proof passed to suggest. Without one every suggestion records identity: unverified and goes to a card, whatever its trust. The owner may opt in to trusting in-process callers with AWSTORAGE_TRUST_INPROCESS=1 (recorded as inprocess-trusted and re-checked at apply: unset it and those approvals are withdrawn). Transports stamp what they know -- AitherOS MCP mcp-session:<uid>, awdk agent:<name> -- neither is proof.

Signed answer receipts (0.4.1)

A decision card's answered_by, answered_via and answer_attested live in files an agent on the same host can edit, so none of them approves anything. The platform's answering surface signs a receipt with an Ed25519 key that exists only in its vault and stores it on the card as answer_receipt ({alg, kid, receipt, sig}; the receipt is {v, card_id, choice, answered_by, answered_at, nonce, surface, auth_method, auth_time, facts_sha256}). awstorage.attest.verify_receipt -- called by manage.verify_card and so by manage apply, node orders and suggestion approvals -- refuses unless:

• awseal is installed (pip install awstorage[attest]; it carries the verifier) and a public key is provisioned in a FILE: AWSTORAGE_ATTEST_PUBKEY_FILE=<path> (AWSTORAGE_ATTEST_PUBKEY is accepted as a path too; a raw 64-hex key in either env var is REFUSED -- whoever starts the verifier sets its env). The FILE must be provisioned by root / the owner OUTSIDE ~/.aither (e.g. /etc/aither/attest.pub, or a %ProgramData% path whose ACL agents cannot write): a path under ~/.aither, or (POSIX) a world-writable file or directory, is refused -- whoever can swap the key can sign approvals;
• the signature verifies, and the receipt names this card, this answer and this card's facts (a fact edited after the answer is refused);
• auth_method is webauthn or totp_2fa and the sign-in was at most 15 min before the answer (AWSTORAGE_ATTEST_MAX_AUTH_AGE_S, clamped 60..3600) -- password, device flow (every agent bearer), PAT, API key, OIDC access token, magic link and internal mints never count;
• answered_by is an owner principal (AWSTORAGE_MANAGE_OWNERS);
• answered_at is inside the card's window and within 5 min of the store's own;
• the receipt is at most 7 days old by the REAL clock (AWSTORAGE_ATTEST_MAX_RECEIPT_AGE_S, clamped 1 h..30 d; verify_receipt(now=) is ignored -- an injectable clock is an injectable bypass);
• the nonce is new: the catalog table attest_nonces binds each nonce to one card and each card to one receipt (re-verifying the SAME receipt is fine).

Every card also carries content_sha256: <hex> -- the digest of WHAT is approved (manage: node, action, path, bytes, tenant, owner, params and every member's path + sha256 + bytes; suggestions: see above). manage._authorize and suggestion resolve/apply recompute it from the row and refuse a mismatch or a card without it.

manage.STORE_ATTESTS_ANSWERER is now only the master switch (True; False refuses every answer). A card without a valid receipt is refused either way.

Threat model -- what an approval does and does not prove

On a single-user host agents run as the owner's OS user. They can delete files directly, read the browser's localStorage session and, with podman exec, service state. A verified receipt therefore proves "an owner passkey/TOTP session existed within 15 minutes of this answer" -- not "the owner saw this card and chose this". Approvals are a governance gate and a tamper-evident audit trail for agents that use the tools, NOT a security boundary against a hostile local agent. That boundary needs OS isolation: agents under a separate OS user, or in a container without podman or vault access, and the verifier key provisioned where they cannot write it.

Follow-up that closes the remaining gap (review 2, a2/c3): a per-answer WebAuthn step-up whose assertion signs the digest of the RENDERED card, verified here instead of (or beside) the session-age check.

Keep drives above their floors

```bash
awstorage watch --floors C:=40,D:=60,E:=30 --once --receipt ~/.aither/awstorage/watch.json
awstorage watch --floors C:=40,D:=60,E:=30 --once --yes      # let the emergency sweep act
awrise add --name awstorage-watch --every 5m --timeout 300 -- awstorage watch --floors C:=40,D:=60,E:=30 --once --yes --receipt ~/.aither/awstorage/watch.json

The 3-hourly sweep is too slow for a drive that falls 124 -> 18 GB in an hour. watch is one disk_usage per floored drive: with every drive above its floor it walks no tree and finishes in milliseconds. Under a floor it runs the emergency sweep of the presets (--rules, default agent-scratch,temp-toplevel) on THAT drive only -- a plan unless --yes -- appends an alert to ~/.aither/awstorage/alerts.jsonl, and runs $AWSTORAGE_ALERT_CMD with the alert JSON as its last argument (a JSON list such as ["awrelay", "send", "#agents"], or a shell-like string; never run through a shell), so awrelay / Pulse plug in without being imported. Exit 0 all above, 1 a drive still under its floor, 2 could not judge. $AWSTORAGE_FLOORS holds the same spelling.

Before moving data between drives

```bash
awstorage place --size 90GB --from C:/data/models --floors C:=40,D:=60,E:=30
awstorage place --size 90GB --to C: --floors C:=40      # exit 1: refused

place ranks every drive by its free space AFTER the move and refuses any that would end under its floor (unlisted drives: --default-floor-gb, 20). Run it before moving data -- on 2026-09-28 a peer moved 89 GB onto a nearly-full C:. Python: awstorage.place("90GB", {"C:": 40, "E:": 30}, source="D:/models").

When every drive is short: offload to S3 (0.6.0)

```bash
pip install "awstorage[s3]"
awstorage offload D:/cache D:/archive --dry-run        # rank children by size + last access
awstorage offload D:/archive/old-builds --to cold      # upload, verify, THEN delete
awstorage restore D:/archive/old-builds --file a.bin --to /tmp/probe   # one file back
awstorage restore D:/archive/old-builds                # everything back, sha256-checked

The target (--to cold) is an object_stores.<name> entry (bucket, region, credential pairs) in your storage-topology file, or --bucket/--region. Each file is deleted only after S3's own SHA-256 of the STORED bytes matches the one computed locally, and only after a line for it is fsynced into the stub left in its place (AWOFFLOADED.jsonl), which is also copied to the bucket. A large file uploads in parts whose upload id is journaled, so a re-run sends only the missing parts. Credential paths, VM disks, database files and tenant/customer paths are refused.

Every node's inventory, signed, on GitHub (0.9.0)

```bash
pip install "awstorage[inventory]"            # awseal + awrtifact
awstorage inventory enroll                    # once: awseal key + nodes/<node>.pub
awstorage inventory publish                   # this node -> Aitherium/inventory
awstorage inventory pull --all                # every node, signature-verified
awstorage inventory query find invoice --node laptop-3
awstorage inventory query tree D:/ --node laptop-3 --depth 2
awstorage files tree D:/ --node laptop-3      # same answer: falls back to the pull

Each node publishes its OWN index as release <node>-<UTC stamp> in a private repo: the files.db rows for that node (gzipped, split under GitHub's 2 GiB asset cap by awrtifact), an inventory.json manifest, and an awseal.json seal made with that node's key. The node's public key lives in the repo as nodes/<node>.pub, committed through the contents API by enroll or the first publish (files schedule, which adk pair / adk enroll run, creates the key). A reader verifies against that file, pins the key locally, and REFUSES an unknown key, a changed key, a bad signature or changed bytes. Publishing to a repo that is not private needs --allow-public. What leaves the node: paths, sizes, mtimes and hashes of non-sensitive files -- never file content, never a hash of a credential-shaped file. Kinds are pluggable (files today).

Hardware, software, services -- and retention (0.10.0)

```bash
awstorage inventory publish --kind hardware   # CPU, RAM, GPUs (nvidia-smi), disks, OS
awstorage inventory publish --kind software   # winreg Uninstall / dpkg-query / macOS apps + pip
awstorage inventory publish --kind services   # systemd / Windows services, podman/docker ps
awstorage inventory pull laptop-3 --kind hardware
awstorage inventory query show laptop-3 --kind hardware [--json]
awstorage inventory nodes --remote --kind software

Each host kind is one small JSON document on the same signed transport, released as <node>-<kind>-<stamp> + <node>-<kind>-latest (files keeps <node>-<stamp>; a node id ending in -<kind> is refused so the namings never collide). Names, versions and states only: no environment variables, command lines, unit descriptions or container images, and every kept string passes a secret scrubber. A missing or failing tool (nvidia-smi, dpkg-query, systemctl, podman ...) is a row of unavailable, never a failed publish. files sync publishes the three kinds at most once per 24 h each ($AWSTORAGE_INVENTORY_KINDS_EVERY_S, state in <index_dir>/inventory_kinds.json; inventory_kinds: false in the config turns it off).

Retention: after every successful publish the node's own releases of that kind older than the newest N are deleted with their tags (--keep N, $AWSTORAGE_INVENTORY_KEEP, default 5). Never a -latest pointer, never another node's or kind's release, never a tag that is not exactly <node>[-<kind>]-<stamp>; a failed listing deletes nothing. The publish result's retention names what was pruned.

Shelf safety

The harvest shelf is a drive too (E: sat at 99 %). With floors set (--floors on sweep, $AWSTORAGE_FLOORS for apply-suggestions), an item whose harvest would be written onto a shelf drive under its floor is KEPT (harvest-skipped: shelf drive low) -- never removed without its harvest. The one exception: an act that deletes the item from the shelf's own drive (a delete rule or an emergency delete) repays the copy at once, so the emergency on a full C: with the shelf on C: still frees space. Rotate the shelf with awstorage shelf prune --older-than 30d [--yes] (the date in the day dir's name decides, not its mtime).

Agent worktrees

```json
{"retention": [{"name": "agent-worktrees", "paths": ["C:/.worktrees/*", "C:/wt/*"]}]}

awstorage sweep --rules agent-worktrees --policy wt.json --yes: idle 7 d, quarantine, purge after 7 d. Opt-in twice -- named, and its paths come from the policy. Every item must be a git work tree ROOT whose status is clean and whose commits a remote holds; dirty, ahead, not a repo, or unjudgeable -> skipped-git, kept. git's own worktree registry must then be pruned by the tool that owns it (git worktree prune); never git worktree remove, which follows junctions (it deleted a shared node_modules on 2026-09-22).

The three rules

• Measure before you delete. A du answers one question once.
• Re-fetchable is a property, not a guess. The classifier says why.
• Deleting is a policy, not a mood. Dry run, roots, fingerprints, quarantine, ledger.

Composes with

Every coupling is optional and imported lazily (pip install awstorage[harvest] for awseal + awdit + awshare); without the package the sweep says "unavailable" in its receipt rather than pretending.

• awdit -- every sweep decision (harvested, withheld-secret, skipped-live, quarantined, deleted, purged, failed) is appended to a hash-chained, truncation-evident log (--audit-log, default ~/.aither/awstorage/audit.log); the intent is recorded BEFORE a removal. awstorage audit verify checks it. --require-audit refuses to remove anything (exit 2) when awdit is absent or an append fails.
• awseal -- each harvested item dir is sealed (awseal.json, Ed25519) after its copies verify, with --seal-key or awseal's own default key. An explicit key that cannot seal keeps the item. awstorage harvest verify <shelf> reports sealed / tampered / unsealed.
• awshare -- awstorage harvest publish <shelf>/<rule>/<day> --to <dir> (or sweep --publish-to <dir>) bundles a day's harvest; fetch it back with awshare.fetch(<dir>/<name>.awshare.json, dest), which verifies the digest before a byte lands.
• awm -- sweep --land-to-awm tenant:user:project lands ONE memory per harvested item (storage.harvest.<item>: what was kept and where) through MemoryStore.remember, never SQL; an older-schema awm file is reported as a compat problem, never migrated.
• awrecover -- a rule with "snapshot": true snapshots each item before removal (--snapshot-store); without awrecover the item is KEPT and reported. For proposals, backup_hook=lambda p: awrecover.snapshot(p, store, label) turns backup-then-delete into a restorable snapshot first.
• AitherStrata (the platform's tiered storage service) -- --harvest-to strata:<hot|warm|cold> (default tier cold) uploads each verified harvested file plus manifest.json (and awseal.json when sealed) with POST /strata/write, then reads every object back with GET /strata/stat/<tier>/<path> and compares size (and sha256 when the server reports it) BEFORE the item may be removed; any mismatch keeps the item. stdlib urllib + ssl only. URL from AITHERSTRATA_URL (default https://127.0.0.1:8136; the service is TLS-only), CA from AITHER_CA_BUNDLE or <repo>/AitherOS/Library/Data/tls/ca-chain.pem, key from AWSTORAGE_STRATA_KEY (sent as X-Internal-Key, env var only). No CA, no key, or unreachable = "strata target unavailable": nothing removed, exit 2. There is no unverified-TLS mode.
• awdk -- calls awstorage.sweep(...) (returns the receipt dict) and registers its running sessions through AWSTORAGE_LIVE_IDS.
• awrise -- schedules the sweep and reads its receipt (see above).
• awdk / awnode / awsh -- run the scanner where the disk is, post snapshots to a shared catalog, render proposals in a shell or a desktop panel.
• awgraph -- awstorage graph emits nodes and typed edges (contains, duplicate_of) any graph store can ingest.

awstorage --self-test (or python -m awstorage --self-test) proves the refusals still refuse, the quarantine still reverts, and each sweep guard is seen firing: harvest-before-delete, secret withheld, live guard, junction not followed, emergency halving, emergency delete (only for a flagged rule, never without a verified harvest), the per-item measure cap both ways, receipt on failure.

Apache-2.0.

The aw family

Standalone tools that share one idea: replace something you would otherwise have to trust with something you can check.

Each installs on its own, works offline, and needs no account.

awnix is the ground floor — A Linux you can hand to an agent — immutable base, capabilities included.

The Aitherium ecosystem

Every repository here is public. Each publishes an aither-manifest.json beside its page, so any surface can read every sibling's — the network is browsable from any node in it.

Built on REA (Reverse Engineer Anything) · llama.cpp · vLLM · ComfyUI · CentOS Stream · Podman · Docker · LanceDB · WireGuard · FFmpeg · Blender + Rigify · headroom · SANA · Hunyuan3D · repowise · Playwright · Chromium · Next.js · React.