Documentation

Changes

A change is loot's reviewable unit of history — its answer to a commit. There is no separate add/commit step: the working tree is the change at the tip. loot describe -m records it and names it; loot new finalizes and signs it, starting a fresh one. A change carries a set of paths, each with its own visibility — which is where permissions live.

Visibility & .lootattributes

Every path is public, restricted (a named set of key holders), or embargoed (encrypted to all until a reveal time). You declare it in .lootattributes, a gitattributes-style file: .env restricted=alice, *.md public. Unmatched paths default to public. The file is versioned like any other, so the policy travels to every clone.

Identity & keys

An identity is a keyholder — an ed25519 keypair minted at loot init. Visibility is ultimately enforced by who holds the decryption key for a piece of content: "permissioning is key management." Names like alice are local nicknames bound to a globally-stable public key through the peer registry.

Grants

A grant hands one content key to one identity. It's sealed to the recipient's public key (they can't be granted anything they can't unseal), signed by you so the trail is forge-evident, and recorded in an append-only manifest. Grants are how restricted content is shared after the fact — and loot maroon is how access is cut off again.

Relays & hosts

A relay stores and forwards sealed content it cannot read. Restricted keys never travel in a sync bundle, so the relay's zero-knowledge property is enforced at the wire level, not by policy. A host is just a relay that never sleeps — which makes a loot host a zero-knowledge code host: it physically cannot read your private code.

Embargo

An embargoed path is encrypted to everyone until a reveal timestamp. You can merge a security fix, cut the release, and push — the relay holds the ciphertext while withholding the key until reveal_at passes on the relay's own clock. Then anyone who pulls can read it. No lying clock, escrow inspection, or patched binary reads it early: the key bytes simply aren't there yet.

Docks (for concurrency)

A dock is an isolated working tree plus its own tip, materialized cheaply over one shared object store — loot's answer to a git worktree, without a second clone. Docks are the light-touch tool for running several agents or workstreams against one repo; concurrent edits reconcile through the merge classifier, and conflicts surface as machine-readable verdicts rather than being silently dropped.

Keep a file private in a shared repo

Declare the path restricted before you record it. Only listed identities get a key; everyone else carries ciphertext.

printf '.env restricted=alice\n' > .lootattributes
loot describe -m "add sealed .env"
loot push          # the relay stores it but cannot read it

Share a private file with a teammate

Register their public key (from loot whoami on their machine), then deliver a sealed grant over the relay.

loot peer add bob "ssh-ed25519 AAAA..."
loot grant --relay origin .env bob

# on bob's machine:
loot pull-grants   # verifies alice's signature, checks the peer registry
loot surface       # now bob can read .env

Embargo a security fix

Mark the file embargoed until a unix timestamp. Push now; the key is withheld by the relay until reveal time.

echo "VULN_DETAILS=CVE-2025-XXXX" > security-fix.txt
printf 'security-fix.txt embargoed=1800000000\n' >> .lootattributes

loot describe -m "patch for CVE-2025-XXXX"
loot push          # relay holds ciphertext; key withheld until reveal_at

At reveal_at, the relay releases the key and anyone who pulls can read the fix.

Sync over a relay

A relay is the collaboration hub. Run one anywhere; push and pull resolve origin by default.

# terminal 1: run a relay
loot serve --dir /tmp/relay --addr 127.0.0.1:4000

# terminal 2: alice publishes
loot remote add origin http://127.0.0.1:4000
loot push

# terminal 3: bob clones (sees only public content until granted)
loot clone http://127.0.0.1:4000 ./bob-repo --identity bob