Master Seed & Encryption

What you'll learn

How AES-256-GCM payload encryption works, what the master seed protects, and what stays plaintext.

The encryption model

SAPIX_MASTER_SEED (64 hex chars = 32 bytes)
        │
        ▼ HKDF-SHA256(salt=agent_id, info="strand-payload-encryption-v1")
        │
        ▼ Per-agent AES-256 key
        │
        ▼ AES-256-GCM encrypt(payload_msgpack, nonce=random 12 bytes)
        │
        ▼ stored: nonce(12 bytes) ‖ ciphertext(N bytes) ‖ auth_tag(16 bytes)

Each agent gets a unique AES key derived from the master seed. Compromising one agent's key does not compromise others.

What is encrypted

• Record payload (your JSON data) — YES, encrypted

What stays plaintext

• WAL entries (for crash recovery) — plaintext
• content_hash, parent_hash, ts_hlc, flags — plaintext (needed for chain verification without decryption)
• Blob storage — encrypted separately

Generate a master seed

python3 -c "import secrets; print(secrets.token_hex(32))"

Backup this value offline. If lost, stored data is permanently unreadable. The engine cannot recover it.

What "agent refuses to start" looks like

If SAPIX_MASTER_SEED is missing from the environment, the agent logs:

ERROR sapix_agent: SAPIX_MASTER_SEED not set — cannot initialize encryption. Aborting.

And exits immediately. No data is written in an unencrypted state.

Key rotation (advanced)

Rotating the master seed requires re-encrypting every segment file. See Lesson 36 for the full procedure.

Challenge

Inspect your running container logs and find the line that confirms the master seed was loaded successfully.

---