Kuiper

Local-first, content-addressed snapshots with block-level dedup and integrity checks.
Built in Rust for speed, safety, and a clean CLI.

Kuiper turns a directory into a series of consistent snapshots. It stores data in a content-addressed object store so identical chunks across files and versions are saved once. A small index maps snapshots → files → objects. Restores rehydrate files exactly as captured.

---

Table of contents

• Features
• Quick start
• Build from source
• How it works
• Usage
• Repository layout
• Compatibility
• Security notes
• Roadmap
• Contributing
• License

---

Features

• Local-first: no server required; works entirely offline
• Content-addressed store: identical data saved once → strong dedup across snapshots
• Integrity by default: cryptographic hashes on all stored objects
• Atomic snapshots: capture a consistent view of the source at a point in time
• Fast restore: only rehydrate what’s needed
• Simple CLI: one command to create, one to restore
• Transparent layout: human-inspectable repository on disk

---

Quick start

# Build
cargo build --release
# Show CLI help
./target/release/kuiper --help

# Create a repository snapshot (example)
kuiper create ~/kuiper-repo --src ~/kuiper-demo --name day0

# Restore a snapshot (example)
kuiper restore ~/kuiper-repo day0 /tmp/restore

Replace paths/names as needed. Commands above reflect Kuiper’s current CLI.

---

Build from source

• Rust (stable)
• A POSIX-like system (Linux recommended)

git clone https://github.com/operativesoft/kuiper
cd kuiper
cargo build --release

The binary will be at ./target/release/kuiper.

---

How it works

1. Chunk & hash source data → produce content-addressed objects.
2. Record file metadata (mode, mtime, size) and mapping from files → objects in a small index.
3. A snapshot is a consistent set of file→object mappings plus metadata.
4. Restore walks the snapshot, reads the referenced objects, and re-creates files byte-for-byte.

This design yields:

• Strong deduplication across versions/files
• Integrity via content hashes
• Predictable performance and constant-time addressability

---

Usage

# Create a snapshot
kuiper create <REPO_PATH> --src <SOURCE_DIR> --name <SNAPSHOT_NAME>

# Restore a snapshot
kuiper restore <REPO_PATH> <SNAPSHOT_NAME> <DEST_DIR>

# Help
kuiper --help

Future subcommands may include listing, pruning, verification, export, etc.

---

Repository layout

A Kuiper repository is a regular directory you can move or back up with standard tools:

repo/
├─ objects/        # content-addressed chunks (immutable)
├─ locks/          # coordination/atomicity
└─ index.sqlite    # snapshot + file/object metadata

---

Compatibility

• OS: Linux (primary target).
• FS: any POSIX filesystem; case-sensitive recommended for fewer surprises.
• CPU: x86_64/ARM64 (Rust-stable targets).

---

Security notes

• Encryption at rest: not enabled by default; rely on disk/FS encryption or store the repo on an encrypted volume.
• Integrity: objects are addressed by hash; corrupted content is detectable.
• Permissions: restores try to preserve basic file metadata; ensure you run with appropriate privileges when restoring system trees.

---

Roadmap

• Built-in encryption & compression
• Snapshot listing, diff, and verification commands
• Garbage collection / retention policies
• Parallel I/O and smarter chunking strategies
• Tar/Zip export and partial/filtered restores
• Progress meters and richer logs

Have ideas? Open an issue—design notes are welcome.

---

Contributing

PRs and issues are appreciated.

1. Fork → create a topic branch.
2. Keep commits small and well-described.
3. cargo build --release should pass locally (add tests if you can).
4. Open a PR explaining what changed and why.

---

License

Apache-2.0 — see LICENSE.