keychat-save

Save files and sessions to BSV blockchain. Sealed with your key, permanent on chain.

Install

npm install -g keychat-save

Installed once, for the whole machine; keychat-save then works from any folder. (npx keychat-save … also works without installing.)

Already on KeyChat? Use the key you have

If you use keychat.pro, do not run init. The tool should use the same identity as the app, so your saves show up in the app's KeyChain, RepoChain and KeyCloud and spend the Compute you already hold.

1. In the app open Settings → Download Identity Backup. It saves keychat-identity-backup.txt.
2. Put that file at ~/.keychat/identity.wif:

mkdir -p ~/.keychat && cp ~/Downloads/keychat-identity-backup.txt ~/.keychat/identity.wif

That is the whole setup. Skip to Usage.

New here? Create an identity

keychat-save init

This creates a new identity at ~/.keychat/identity.wif and shows its BSV address. Fund it with BSV to start saving. The same file works in the app: Upload Backup File on the app's first screen.

KeyChain — saves

save writes text to chain, sealed to your key. In the app this is KeyChain in the sidebar; saves made here appear there, and the other way round. A save made with this tool files under AI Sessions in the app's KeyChain (the app also keeps Passwords and Notes).

# Save content (positional: label first, then body)
keychat-save save "my notes" "content to save permanently"

# Or use --label flag explicitly
keychat-save save --label "my notes" "content to save permanently"

# Save a file
keychat-save save --label "backup" --file ./myfile.txt

# Pipe content in
cat session.log | keychat-save save --label "session log" --stdin

# Load all saves
keychat-save load

# Load most recent
keychat-save load --last

# Load a specific save by txid
keychat-save load --txid <txid>

# Search
keychat-save load --search "keyword"

load reads the index and fetches four saves at a time (since 2.6.1), so a fresh machine has its whole history in about a minute for a few hundred saves; --last is one fetch.

A save carries its text and nothing else (since 2.6.1). Earlier versions sealed a list of every prior save into each new one; nothing ever read it — loading always used the index — and it cost about five Compute per save. Older saves that carry one still open.

RepoChain — whole git repositories

save handles text. RepoChain puts an entire repository on chain: git history, working tree, untracked and gitignored files, and node_modules. Restoring needs nothing but your key — no GitHub, no npm registry, no cloud account.

# Full snapshot — git history + working tree + node_modules, in ONE transaction
keychat-save repo backup ~/my-project

# Routine save: only what changed since the last snapshot. Cheap.
keychat-save repo delta ~/my-project

# Rebuild it anywhere — replays the full chain and verifies every file
keychat-save repo restore <txid> ./restored

# Size and cost, broadcasts nothing
keychat-save repo estimate ~/my-project

keychat-save repo list

Take a delta after every commit. A full snapshot of a 34 MB repo costs ~7,300 Compute; a delta of the same repo after a few commits is ~20 Compute and one transaction. Reach for backup only when there is no snapshot yet, the chain has grown long, or node_modules churned.

Every delta embeds the ordered txids of all its ancestors, so one txid restores everything — restore replays the root and each delta in order, then verifies the rebuilt tree against a hash of its full file manifest.

Using an AI agent with terminal access? Just tell it "save git repo to repochain" and it runs the delta for you.

Why a whole tarball, not git bundle

A bundle carries only committed history. It misses uncommitted work, gitignored files, the stash, and node_modules — which means a restore depends on the npm registry still serving every package at the same version. Packages get unpublished. RepoChain carries the lot.

KeyCloud — files on chain

save handles text and RepoChain handles repositories. KeyCloud puts a file on chain, encrypted under a key made for that file alone. Nobody else can read it, including us, until you choose to share it.

# Upload — 1 MB chunks plus a manifest, whatever the size. A .srt or .vtt next
# to a video (same name, or the only one in the folder) is attached as subtitles.
keychat-save keycloud put ~/Documents/passport.pdf

# Add or replace subtitles on a video already on chain (new manifest, same chunks)
keychat-save keycloud subs <manifestTxid> episode.srt

# Fetch it back anywhere your identity key is. sha256 is verified before
# anything is written to disk.
keychat-save keycloud get <txid> ~/Downloads

# What you have uploaded from this machine
keychat-save keycloud list

# Publish identifiers for everything already on chain — see below
keychat-save keycloud catalog

Every file is chunked

Every upload is stored as 1 MB chunks — one chunk for a small file — each encrypted under a key generated for that file alone, plus a small manifest naming them. (Versions before 1.8.6 stored files of 1 MB or less as a single transaction sealed to your own key; those still open, but cannot be shared.) Two things follow.

It can be read on any device. Reading is fetch-a-chunk, decrypt, append, release — so memory stays flat no matter how big the file is. A single-transaction file has to be held whole to be opened, which rules out a browser above a few MB.

An interrupted upload resumes. Progress is recorded after every chunk. Run the same put again after a dropped connection or an empty wallet and it continues under the same file key, pricing only the chunks still missing — nothing already paid for is sent twice.

Four chunks travel at once (since 2.6.0), each its own transaction, so an upload runs at the speed of your connection rather than one round trip per chunk — and get fetches four ahead the same way (since 2.6.1). Subtitles attached to a video are written beside it as a .vtt.

One file at a time, each way (since 2.6.3). Your connection is the limit: two uploads at once each go half speed and finish together, so the app and the web queue a second file behind the first and start it the moment the first lands. The tool moves one file per command; run one command after another and the same thing happens. Encryption uses your machine's own AES (Node's crypto) in the exact layout the SDK defines, so a chunk sealed here opens in the web app, the Mac app, or an older CLI, and theirs open here.

It can be shared for the price of a message. The file is encrypted to its own key rather than to you, so sharing means handing someone that 32-byte key and the chunk list — a fraction of a Compute, the same for a 30 MB file as a 30 KB one, and the same for the tenth recipient as the first. Nothing is re-uploaded; everyone reads the same chunks. Sharing is done from the app.

Verified end to end on a 30 MB file: 31 chunks, read back byte-for-byte identical.

Sharing is permanent. The chunks are public and immutable, so whoever receives the key can read that file forever. There is no revoking it. You are giving a copy, not lending one.

Listing without downloading

Metadata travels in its own encrypted push, separate from the file. A listing therefore costs kilobytes: names, sizes and image thumbnails are read without moving a single file body, and the bodies are fetched only when you open one.

Anything uploaded before that split has its metadata sealed inside its own body, so listing it the old way meant downloading it. keycloud catalog fixes that in one small transaction: it publishes the identifiers you already hold locally — names, sizes, hashes, and your RepoChain snapshots too — encrypted to your key. Any device with that key then lists your whole history for a few KB. Cataloguing 51 items cost 2 Compute.

Bytes are encrypted directly — never base64, which would add 33% to the size and therefore 33% to the cost. The file's sha256 travels with it and is checked on the way back, so a truncated fetch fails loudly instead of writing a corrupt file.

What it costs

Storage is priced like permanence, at the 100 sats/KB mining floor:

| File | Cost | |------|------| | 1 MB | ~200 Compute | | 10 MB | ~2,000 Compute | | 100 MB | ~20,000 Compute (0.1 BSV) |

There is no file size cap: every chunk is its own 1 MB transaction, so a 300 MB video is 300 transactions and a manifest, and it resumes if interrupted. (Miner policy caps a single transaction at 100 MB — that applies to a RepoChain snapshot, which is one transaction.)

How it works

Content is sealed with your identity key (ECIES) and broadcast as a transaction on BSV via KeyChat. Only your key can decrypt it. Saves are permanent and portable — load them on any device with your identity key.

Since 2.4.0 the tool is a thin command-line shell over the KeyChat wallet core — the same coin list, transaction builders, pricing and readers the KeyChat app runs, bundled into one file. A fix lands once and reaches the app and this tool together. The first spend on a machine builds the wallet's coin list from chain and checks every coin with the node (about two minutes on a very large wallet, once); later runs pick up only what is new.

Cost: 0.25 Compute (125 sats) minimum, scales with size. Miners charge 100 satoshis per KB — a save pays exactly that, and whatever the round-up to the next 0.25 leaves over goes to the platform (the same rule a message follows) — and the tool refuses to broadcast anything below that floor — a transaction under it is relayed and accepted, then never mined, and disappears hours later with no error.

Web UI

Everything this tool writes is also in the app at keychat.pro, under the same key: KeyChain in the sidebar for saves, RepoChain for repositories — including a one-click download that replays the whole chain into a .tar.gz — and KeyCloud for files, where sharing is done.

License

MIT