pepper-agent

pepper-agent initializes and runs one Pepper node, creates verified offline metadata backups, and restores a backup belonging to the same node identity.

Synopsis and global options

pepper-agent [--config <PATH>] [COMMAND]

--config <PATH>

Strict TOML configuration. Defaults to ./pepper.toml when it exists, otherwise /etc/pepper/pepper.toml.

-h, --help

Print command help. --config is global and may be placed before or after a subcommand.

Run the node

pepper-agent --config /etc/pepper/pepper.toml

With no subcommand, the agent takes the node-identity lock, opens and migrates metadata, starts authenticated QUIC, recovers assigned namespace groups, starts the loopback HTTP/S3 API, reconciles publications and multipart state, resumes compute, and starts repair tasks. Stop it with SIGINT or Ctrl-C.

Only one live agent, backup, or restore operation may hold a node identity. Copying one identity into two running processes is fenced locally but remains an unsafe deployment practice.

init

pepper-agent init [--config <PATH>]

Validates the existing configuration, creates data/storage/compute directories, creates or loads the node identity, initializes or migrates metadata, and opens storage. It does not generate a configuration file.

backup

pepper-agent backup --output <PATH> [--config <PATH>]

Requires exclusive access, so stop the node first. The command verifies metadata, copies it to PATH, hashes the copy, inventories namespace consensus records, and writes PATH.manifest.json with the schema, node identity, namespace recovery information, and an identity signature.

restore

pepper-agent restore --input <PATH> --force [--config <PATH>]

Restore always requires --force and an initialized local identity. It verifies the adjacent manifest, signature, node ID/public key, BLAKE3 hash, byte length, schema, and metadata structure before atomically replacing metadata.redb. Stop the node first. Restored consensus groups may need to catch up from their peers before /readyz succeeds.

A backup is identity-bound. It cannot be restored onto a different node identity as a shortcut for adding or replacing a namespace replica.

Environment

RUST_LOG

Tracing filter, for example pepper_agent=debug or info.

PEPPER_FIRECRACKER_KERNEL_IMAGE

Guest kernel override when compute.firecracker_kernel_image is absent.

Files and endpoints

<data.path>/node.key — Ed25519 identity unless identity.key_path overrides it.
<identity key path>.lock — single-live-process identity fence (node.key.lock with the default identity path).
<data.path>/metadata.redb — schema-4 metadata, namespace consensus state, and publication state.
GET /healthz — process liveness; GET /readyz — namespace group readiness; GET /metrics — Prometheus text metrics.
/v1/* uses the optional API bearer token. S3 requests use SigV4 credentials instead. All HTTP interfaces remain loopback-only.