Getting Started
From zero to encrypted, reactive files in five steps.
1
Install FileLuYa
Install from source with Cargo, via Homebrew, or download a pre-built binary for your platform.
From source (Cargo)
# Prerequisites: Rust toolchain, MacFUSE (macOS) or libfuse3-dev (Linux)
git clone https://github.com/loveJesus/keyleluya
cd keyleluya
cargo install --path crates-chirho/keyleluya-fuse-chirhoHomebrew (macOS)
# Coming soon
brew install lovejesus/tap/keyleluyaDownload binary
# Download from the releases page:
# https://github.com/loveJesus/keyleluya/releases
curl -LO https://github.com/loveJesus/keyleluya/releases/latest/download/keyleluya-darwin-arm64
chmod +x keyleluya-darwin-arm64
sudo mv keyleluya-darwin-arm64 /usr/local/bin/keyleluya2
Mount Your First Vault
Create an encrypted mount point. All data written here is automatically encrypted with XChaCha20-Poly1305.
Mount (background daemon)
# Create and mount an encrypted vault
keyleluya mount ~/my-vault --cache-dir ~/.keyleluya
# Check that it is running
keyleluya status
# → ~/my-vault (pid 12345, cache: ~/.keyleluya)Mount (foreground)
# Stay in terminal — Ctrl+C to unmount
keyleluya mount ~/my-vault --cache-dir ~/.keyleluya --foreground3
Write and Read Files
Use the mounted vault like any folder. Files are encrypted transparently. Unmount and remount — everything persists.
Basic usage
# Write files
echo "hello world" > ~/my-vault/doc.txt
mkdir ~/my-vault/projects
cp report.pdf ~/my-vault/projects/
# Read files
cat ~/my-vault/doc.txt
# → hello world
ls ~/my-vault/
# → doc.txt projects/Persistence
# Unmount
keyleluya unmount ~/my-vault
# Remount later — your files are still there
keyleluya mount ~/my-vault --cache-dir ~/.keyleluya
cat ~/my-vault/doc.txt
# → hello world4
Share with Someone
Share individual files or directories with specific people. Each file key is wrapped with the recipient’s public key.
Sharing a file
# Share a file with a collaborator by their public key
keyleluya share ~/my-vault/doc.txt --with alice@example.com
# They can now decrypt and read doc.txt
# Nobody else can — sharing is per-file, per-keyRevoking access
# Remove access — keys are automatically rotated
keyleluya unshare ~/my-vault/doc.txt --from alice@example.com5
Reactive Files with .forge
Link files together so they react to each other’s changes. Define reactive networks in .forge files using Gears (constraints) and Waterwheels (derived outputs).
Create a .forge file
# ~/my-vault/pipeline.forge
#
# When data.csv changes, summary.json is recomputed.
# config.toml must always be valid TOML.
waterwheel summarize {
input: "data.csv"
output: "summary.json"
run: "python3 summarize.py"
}
gear validate_config {
watch: "config.toml"
check: "toml-lint config.toml"
}See it work
# Edit data.csv — summary.json updates automatically
echo "name,value\nalpha,42" > ~/my-vault/data.csv
# summary.json is recomputed by the waterwheel
cat ~/my-vault/summary.json