First Boot

What you'll learn

Start SapixDB with Docker, verify it is running, understand the health endpoint, and make your very first write.

Step 1 — Generate three secrets (if you haven't already)

`bash # Ed25519 keypair seed — the agent's permanent identity python3 -c "import secrets; print(secrets.token_hex(32))"

# Master seed — AES-256-GCM encryption (required — agent refuses to start without this) python3 -c "import secrets; print(secrets.token_hex(32))"

# Root API key python3 -c "import secrets; print('spx_root_' + secrets.token_hex(32))" `

Save all three. You need them in the next step.

Step 2 — docker-compose.yml

services:
  sapixdb:
    image: sapixdb/agent:latest
    container_name: sapixdb
    restart: unless-stopped
    ports:
      - "7475:7475"
    volumes:
      - ./data/strand:/data/strand
      - ./data/graph:/data/graph
      - ./data/blobs:/data/blobs
    environment:
      SAPIX_AGENT_ID:        my-first-agent
      SAPIX_MASTER_SEED:     YOUR_MASTER_SEED_HEX
      SAPIX_KEYPAIR_SEED_HEX: YOUR_KEYPAIR_SEED_HEX
      SAPIX_ROOT_KEY:        spx_root_YOUR_ROOT_KEY_HEX
      SAPIX_STRAND_DIR:      /data/strand
      SAPIX_GRAPH_DIR:       /data/graph
      SAPIX_BLOB_DIR:        /data/blobs
      SAPIX_BIND_ADDR:       0.0.0.0:7475

mkdir -p data/strand data/graph data/blobs
docker compose up -d

Step 3 — Health check

curl -s http://localhost:7475/v1/health | python3 -m json.tool

Expected: `json { "status": "ok", "agent_id": "my-first-agent", "record_count": 0, "chain_head": "0000000000000000000000000000000000000000000000000000000000000000" } `

Step 4 — Your first write

curl -s -X POST http://localhost:7475/v1/agents/my-first-agent/write \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer spx_root_YOUR_ROOT_KEY_HEX" \
  -d '{"payload": {"message": "Hello, SapixDB!", "ts": "2026-07-09"}}' \
  | python3 -m json.tool

Expected: `json { "content_hash": "b3a7c2...", "parent_hash": "000000...", "sequence": 1, "ts_hlc": 1751900000000000 } `

Challenge

1. Check the health endpoint again — what changed in record_count and chain_head?
2. Write a second record with any payload. What is its parent_hash?

---