Getting started

Pepper 0.2.0 combines immutable content-addressed storage with three-replica transactional data services. Start one node for blocks, objects, directories, pins, and compute; start all three development nodes for namespaces, KV, buckets, filesystems, and S3.

Requirements

Rust 1.85 or newer and a Unix-like shell.
Three reachable Pepper agents for namespace-backed services; namespace creation requires exactly three consensus replicas.
Compute additionally requires Linux, /dev/kvm, Firecracker, mkfs.ext4, debugfs, a guest kernel, and an allowlisted ext4 rootfs containing /pepper-guest-agent.

Build the release

git clone https://github.com/peppermesh/pepper.git
cd pepper
git checkout v0.2.0
cargo build --locked --workspace --release

The host binaries are target/release/pepper-agent and target/release/pepper.

Start the development cluster

The checked-in development configs enable namespaces and S3. Create the shared development S3 secret, initialize each node, then run each agent in its own terminal:

umask 077
printf 'replace-with-a-long-development-secret' > ./dev/s3.secret

./target/release/pepper-agent init --config ./dev/node1.toml
./target/release/pepper-agent init --config ./dev/node2.toml
./target/release/pepper-agent init --config ./dev/node3.toml

# Run these in three terminals
./target/release/pepper-agent --config ./dev/node1.toml
./target/release/pepper-agent --config ./dev/node2.toml
./target/release/pepper-agent --config ./dev/node3.toml

The dev configs store state below ./dev, expose APIs on 9080–9082, and use development credentials. Do not use them unchanged for a deployed cluster.

Verify storage

./target/release/pepper node status
./target/release/pepper node peers
printf 'hello pepper
' > /tmp/input.txt
./target/release/pepper --json object put /tmp/input.txt
./target/release/pepper object get '<object-cid>' -o /tmp/output.txt

User-facing puts create a root pin. The pin protects the complete reachable DAG from garbage collection.

Create a namespace and use KV

./target/release/pepper --json namespace create --kind kv --alias demo
./target/release/pepper --json object put /tmp/input.txt
./target/release/pepper kv put demo greeting --cid '<object-cid>'
./target/release/pepper kv get demo greeting
./target/release/pepper kv scan demo --prefix greet

Aliases can be used wherever a namespace ID is accepted. Writes are linearized through the namespace's Raft leader and publish referenced content only after the required durability is met.

Try buckets and filesystems

./target/release/pepper bucket create assets
./target/release/pepper bucket put assets hello.txt /tmp/input.txt --content-type text/plain
./target/release/pepper bucket get assets hello.txt -o /tmp/from-bucket.txt

mkdir -p /tmp/tree && printf 'v1
' > /tmp/tree/file.txt
./target/release/pepper fs create workspace
./target/release/pepper fs commit workspace /tmp/tree --base-revision 0 --message 'initial import'
./target/release/pepper fs checkout workspace /tmp/checkout

Where to go next

Namespaces & KV →Transactions, history, snapshots, conflicts, and durability.Buckets, S3 & filesystems →Versioned objects, AWS-compatible access, and immutable trees.HTTP API →Routes, authentication, health, and stable errors.Operations & upgrades →Readiness, metrics, diagnostics, backup, restore, and recovery.CLI reference →Every pepper 0.2.0 command and important option.