Quickstart Guide

Get SAP running in 5 minutes. This guide covers the essential operations: sealing identity data and creating redundant backups.

Prerequisites

• Node.js 18+ installed
• Basic command line familiarity
• A secure passphrase (you’ll create one)

Step 1: Get the Code

git clone https://github.com/your-org/sovereign-agent.git
cd sovereign-agent

No npm install needed—SAP uses only Node.js built-in modules.

Step 2: Create Your Master Passphrase

Your master passphrase protects your agent’s identity. Choose wisely:

Good: "correct horse battery staple quantum flux capacitor"
Good: "8j#kL9$mN2@pQ5&rT7*wX0"
Bad:  "password123"
Bad:  "myagent"

Store this passphrase securely. If you lose it, your sealed backups become unrecoverable.

Step 3: Create Identity Data

Create a JSON file with your agent’s identity information:

cat > my-identity.json << 'EOF'
{
  "name": "my-first-agent",
  "version": "1.0.0",
  "created": "2026-02-06",
  "keys": {
    "operational": "placeholder-until-real-key-generation"
  },
  "services": [
    {
      "type": "AgentAPI",
      "endpoint": "https://my-agent.example.com/api"
    }
  ],
  "metadata": {
    "description": "My first SAP-enabled agent"
  }
}
EOF

Step 4: Seal Your Identity

Use the Identity Sentinel to create an encrypted backup:

node src/identity-sentinel-core.js seal \
  --key "your-master-passphrase-here" \
  --in my-identity.json \
  --out backups/my-identity-sealed.json

Expected output:

{
  "header": {
    "format": "IdentitySentinel/SealedBackup",
    "formatVersion": 1,
    "createdAt": "2026-02-06T12:00:00.000Z",
    "cipher": { "name": "aes-256-gcm" },
    ...
  },
  "ciphertextB64": "...",
  "authTagB64": "..."
}

Step 5: Verify It Works

Make sure you can unseal the backup:

node src/identity-sentinel-core.js verify \
  --key "your-master-passphrase-here" \
  --in backups/my-identity-sealed.json

Expected output:

OK formatVersion=1 createdAt=2026-02-06T12:00:00.000Z

Step 6: Create a Shadow Replica

Distribute your encrypted backup for redundancy:

# Dry run first (no network)
node src/shadow-replica.js \
  --in backups/my-identity-sealed.json \
  --dry-run

Output:

Shadow Replica complete.
Input: backups/my-identity-sealed.json
SHA256: abc123...
Bytes: 1234
Provider: catbox
Remote: DRY_RUN_NO_UPLOAD
Manifest: backups/recovery_manifest_2026-02-06T12-00-00-000Z.json
(dry-run: no network call was made)

For real upload:

node src/shadow-replica.js \
  --in backups/my-identity-sealed.json

Step 7: Save Your Recovery Manifest

The recovery manifest tells you where your backup is stored:

cat backups/recovery_manifest_*.json

{
  "format": "ShadowReplica/RecoveryManifest",
  "formatVersion": 1,
  "storage": {
    "provider": "catbox",
    "url": "https://files.catbox.moe/abc123.json"
  },
  "recovery": {
    "fetch": { "method": "GET", "url": "..." },
    "verify": { "sha256": "...", "bytes": 1234 },
    "warning": "This manifest contains NO master key material..."
  }
}

Step 8: Test Recovery

Verify you can recover from the backup:

# Fetch the remote backup (simulated)
curl -o recovered-backup.json "$(cat backups/recovery_manifest_*.json | jq -r '.storage.url')"

# Verify it's valid
node src/identity-sentinel-core.js verify \
  --key "your-master-passphrase-here" \
  --in recovered-backup.json

# Unseal to confirm
node src/identity-sentinel-core.js unseal \
  --key "your-master-passphrase-here" \
  --in recovered-backup.json

What You’ve Accomplished

✅ Created a sealed identity backup (encrypted, tamper-evident)
✅ Verified the backup can be decrypted
✅ Distributed the backup to external storage
✅ Created a recovery manifest
✅ Tested the recovery process

Security Checklist

Before going further:

• Passphrase stored securely (password manager, not plaintext file)
• Passphrase NOT in the same location as backups
• Recovery manifest saved in multiple locations
• Original my-identity.json deleted (plaintext no longer needed)

# Clean up plaintext
rm my-identity.json

Next Steps

Goal	Guide
Understand the key hierarchy	Key Hierarchy
Learn key management best practices	Key Management
Set up A2A commerce	A2A Commerce Protocol
Explore the API	Sentinel Core API

Common Issues

”Missing —key"

# Set via environment variable instead
export IDENTITY_KEY="your-master-passphrase-here"
node src/identity-sentinel-core.js verify --in backups/my-identity-sealed.json

"VERIFY_FAILED: Bad format”

Your file might not be a sealed backup. Check:

head -5 backups/my-identity-sealed.json
# Should start with { "header": { "format": "IdentitySentinel/SealedBackup"

“Wrong passphrase”

If verification fails with authentication error, double-check your passphrase. There’s no way to recover if you forget it.

CLI Reference

# Seal
node src/identity-sentinel-core.js seal \
  --key <passphrase> \
  [--in <file>] \     # defaults to stdin
  [--out <file>]      # defaults to stdout

# Unseal
node src/identity-sentinel-core.js unseal \
  --key <passphrase> \
  --in <sealed.json>

# Verify
node src/identity-sentinel-core.js verify \
  --key <passphrase> \
  --in <sealed.json>

# Shadow Replica
node src/shadow-replica.js \
  [--in <sealed.json>] \         # defaults to newest in backups/
  [--backups-dir <dir>] \        # defaults to backups/
  [--provider catbox] \          # storage provider
  [--out-manifest <file>] \      # manifest output location
  [--dry-run]                    # skip actual upload