Getting Started with SapixDB

• A computer running macOS, Linux, or Windows
• Docker Desktop installed (free at docker.com)
• A terminal / command prompt
• Basic familiarity with JSON (key-value pairs like {"name": "Alice"})

    environment:
      SAPIX_AGENT_ID: my-agent
      SAPIX_KEYPAIR_SEED_HEX: YOUR_SEED_HERE
      # ... other vars ...
      SAPIX_LICENSE_KEY: "eyJvcmdfaWQiOiJhY21lLWNvcnAiLCJwbGFuIjoiZW50ZXJwcmlzZSJ9..."

docker compose down && docker compose up -d

docker logs sapixdb | grep -i license

INFO sapix_agent::license: Enterprise license verified org_id=acme-corp plan=enterprise permanent=true

INFO sapix_agent::license: No SAPIX_LICENSE_KEY set — running in community mode

environment:
  SAPIX_CODIOS_URL:     "https://codios-api.midlantics.com"
  SAPIX_CODIOS_API_KEY: "codios_sk_..."        # from your Codios dashboard

  # Optional: fail-closed mode — agent refuses to start without Codios
  # SAPIX_REQUIRE_CODIOS: "true"

POST https://codios-api.midlantics.com/authorize
Authorization: Bearer codios_sk_...

{
  "agent_id":        "orders",
  "operation":       "write",
  "resource":        "agents/orders/records",
  "caller_identity": "orders",
  "request_id":      "req_a1b2c3d4...",
  "timestamp":       1748304000000,
  "ttl_ms":          5000
}

curl http://localhost:7475/v1/codios/stats

{
  "mode":                "enforced",
  "endpoint_configured": true,
  "authorized":          1482,
  "denied":              3,
  "errors":              0
}

environment:
  SAPIX_A2A_URL:     "https://a2a-api.midlantics.com"
  SAPIX_A2A_API_KEY: "a2a_sk_..."    # from your A2A dashboard

POST https://a2a-api.midlantics.com/events
Authorization: Bearer a2a_sk_...

{
  "agent_id":     "orders",
  "event_type":   "write",
  "record_id":    "01918d3e-7f3c-7a99-b2c8-e3a1f9d20b00",
  "timestamp_ms": 1748304005123
}

curl -X POST http://localhost:7475/v1/genesis -H "Content-Type: application/json" -d '{"zone":"governed"}'

{
  "agent_id": "my-first-agent",
  "public_key_hex": "a3f8c2...",
  "genesis_record_id": "01960000-0000-7000-0000-000000000001",
  "chain_head_hex": "3a7f2c...",
  "zone": "governed"
}

curl -X POST http://localhost:7475/v1/records/json -H "Content-Type: application/json" -d '{"data":{"type":"user","name":"Alice","email":"[email protected]","role":"admin"}}'

{
  "record_id": "01960000000000000000000000000002",
  "content_hash": "b4e91a3f...",
  "chain_head": "b4e91a3f..."
}

curl -X POST http://localhost:7475/v1/records/json -H "Content-Type: application/json" -d '{"data":{"type":"user","name":"Alice","email":"[email protected]","role":"superadmin"}}'

curl "http://localhost:7475/v1/strand/records?offset=0&limit=50"

{
  "agent_id": "my-first-agent",
  "total": 3,
  "offset": 0,
  "records": [
    {
      "record_id": "01960000000000000000000000000001",
      "content_hash": "3a7f2c...",
      "parent_hash": "0000000000000000000000000000000000000000000000000000000000000000",
      "timestamp_hlc": 1747000000000,
      "payload_b64": "..."
    },
    {
      "record_id": "01960000000000000000000000000002",
      "content_hash": "b4e91a3f...",
      "parent_hash": "3a7f2c...",
      "timestamp_hlc": 1747000001000,
      "payload_b64": "..."
    }
  ]
}

curl -X POST http://localhost:7475/v1/query -H "Content-Type: application/json" -d '{"type":"latest","limit":10}'

curl http://localhost:7475/v1/records/b4e91a3f...

curl http://localhost:7475/v1/strand/head

{
  "chain_head": "b4e91a3f...",
  "record_count": 3
}

curl http://localhost:7475/v1/records/<content_hash>

{
  "record_id": "019e27a9-...",
  "content_hash": "b4e91a3f...",
  "timestamp_hlc": 116574249022717952,
  "timestamp_ms": 1778781875957,
  "payload": {
    "type": "user",
    "name": "Alice",
    "email": "[email protected]",
    "role": "admin"
  },
  "payload_b64": "...",
  "flags": 0
}

curl -X POST http://localhost:7475/v1/query -H "Content-Type: application/json" -d '{"type":"time_range","from_ts":0,"to_ts":18446744073709551615}'

curl -X POST http://localhost:7475/v1/query -H "Content-Type: application/json" -d '{"type":"time_range","from_ts":116574249022717952,"to_ts":116574350000000000}'

curl http://localhost:7475/v1/strand/verify

{
  "chain_intact": true,
  "total_records": 3,
  "content_hashes_valid": 3,
  "parent_hashes_valid": 3,
  "signatures_valid": 3
}

curl "http://localhost:7475/v1/strand/as-of?timestamp_hlc=1747000001500&limit=50"

{
  "agent_id": "my-first-agent",
  "as_of_hlc": 1747000001500,
  "total_at_time": 2,
  "records": [
    { "record_id": "...", "content_hash": "3a7f2c...", "timestamp_hlc": 1747000000000 },
    { "record_id": "...", "content_hash": "b4e91a3f...", "timestamp_hlc": 1747000001000 }
  ]
}

curl -X POST http://localhost:7475/v1/records/json -H "Content-Type: application/json" -d '{"data":{"_type":"ai_decision","model":"gpt-4o","action":"approved_loan","reason":"Credit score 780, DTI 28%","confidence":0.94}}'

# Generate seeds (run once, save both outputs)
python3 -c "import secrets; print(secrets.token_hex(32))"
# → a3f8c201b7e94d0f2c6a1b3e5d7f9a0c...  (use as seed for users-agent)
python3 -c "import secrets; print(secrets.token_hex(32))"
# → 7b2e4f91c3d85a06e1b2c4d6f8a0b3e5...  (use as seed for orders-agent)

# Create the users agent
curl -X POST http://localhost:7475/v1/agents \
-H "Content-Type: application/json" \
-d '{
  "agent_id": "users",
  "seed_hex": "a3f8c201b7e94d0f2c6a1b3e5d7f9a0c...",
  "zone": "governed"
}'

# Create the orders agent
curl -X POST http://localhost:7475/v1/agents \
-H "Content-Type: application/json" \
-d '{
  "agent_id": "orders",
  "seed_hex": "7b2e4f91c3d85a06e1b2c4d6f8a0b3e5...",
  "zone": "governed"
}'

# Write to users agent
curl -X POST http://localhost:7475/v1/agents/users/records/json \
-H "Content-Type: application/json" \
-d '{"data":{"name":"Alice","role":"admin","email":"[email protected]"}}'

# Write to orders agent — same port, completely isolated strand
curl -X POST http://localhost:7475/v1/agents/orders/records/json \
-H "Content-Type: application/json" \
-d '{"data":{"item":"Widget","qty":3,"user":"Alice","status":"pending"}}'

# Latest 10 records from the users agent
curl -X POST http://localhost:7475/v1/agents/users/query \
-H "Content-Type: application/json" \
-d '{"type":"latest","limit":10}'

# Latest 10 records from the orders agent
curl -X POST http://localhost:7475/v1/agents/orders/query \
-H "Content-Type: application/json" \
-d '{"type":"latest","limit":10}'

# Get the orders agent chain head
curl http://localhost:7475/v1/agents/orders/strand/head

# List all agents on this server
curl http://localhost:7475/v1/agents

services:
  sapixdb:
    image: sapixdb/agent:latest
    ports: ["7475:7475"]
    volumes:
      - ./data/strand:/data/strand
      - ./data/graph:/data/graph
      - ./data/blobs:/data/blobs
    environment:
      SAPIX_AGENT_ID: primary
      SAPIX_KEYPAIR_SEED_HEX: <primary-seed>
      SAPIX_AGENTS: "users:<users-seed>,orders:<orders-seed>,payments:<payments-seed>"
      SAPIX_STRAND_DIR: /data/strand
      SAPIX_GRAPH_DIR: /data/graph
      SAPIX_BLOB_DIR: /data/blobs
      SAPIX_BIND_ADDR: 0.0.0.0:7475

curl -X POST http://localhost:7475/v1/graph/edges \
-H "Content-Type: application/json" \
-d '{"src":"users","edge_type":"has_orders","dst":"orders","weight":1.0}'

curl -X POST http://localhost:7475/v1/graph/refs \
-H "Content-Type: application/json" \
-d '{
  "src_agent": "users",
  "src_content_hash": "<alice-content-hash>",
  "edge_type": "placed_order",
  "dst_agent": "orders",
  "dst_content_hash": "<order-content-hash>"
}'

curl "http://localhost:7475/v1/graph/traverse?agent_id=users&depth=2"

{
  "start_agent": "users",
  "agents_visited": ["users", "orders"],
  "edges": [
    { "src": "users", "dst": "orders", "edge_type": "has_orders", "weight": 1.0, "across_peer": false }
  ],
  "depth_reached": 1
}

curl "http://localhost:7475/v1/graph/edges/users"
# Inbound:
curl "http://localhost:7475/v1/graph/edges/orders?direction=in"

curl -X DELETE "http://localhost:7475/v1/graph/edges/users/has_orders/orders"

# 1. Get all users
curl -s -X POST http://localhost:7475/v1/agents/users/query \
  -H "Content-Type: application/json" \
  -d '{"type":"latest","limit":100}'

# 2. Get all orders
curl -s -X POST http://localhost:7475/v1/agents/orders/query \
  -H "Content-Type: application/json" \
  -d '{"type":"latest","limit":100}'

# 3. Traverse the graph to find all agents reachable from users
curl "http://localhost:7475/v1/graph/traverse?agent_id=users&depth=2"

# 4. Follow a specific cross-agent record ref (Alice → her order)
curl "http://localhost:7475/v1/graph/refs/users/<alice-hash>"

# Encode your payloads
PAYMENT=$(python3 -c "import base64,json; print(base64.b64encode(json.dumps({'event':'payment','order_id':'o1','amount':99.99}).encode()).decode())")
INVENTORY=$(python3 -c "import base64,json; print(base64.b64encode(json.dumps({'event':'deduct','item':'Widget','qty':1}).encode()).decode())")

curl -X POST http://localhost:7475/v1/saga \
-H "Content-Type: application/json" \
-d "{
  \"steps\": [
    {\"target_agent_url\": \"http://payments-svc:7475\", \"payload_b64\": \"$PAYMENT\"},
    {\"target_agent_url\": \"http://inventory-svc:7475\", \"payload_b64\": \"$INVENTORY\"}
  ]
}"

{
  "id": "019e28550000...",
  "coordinator_agent_id": "primary",
  "state": "committed",
  "steps": [
    {
      "step_id": "step_1",
      "status": "applied",
      "record_hash": "aaaa29cb...",
      "compensation_hash": null,
      "error": null
    },
    {
      "step_id": "step_2",
      "status": "applied",
      "record_hash": "b4e91a3f...",
      "compensation_hash": null,
      "error": null
    }
  ],
  "created_at_ms": 1778793136028,
  "completed_at_ms": 1778793136035
}

{
  "state": "compensated",
  "steps": [
    {
      "step_id": "step_1",
      "status": "compensated",
      "record_hash": "aaaa29cb...",
      "compensation_hash": "3b79b8af...",
      "error": null
    },
    {
      "step_id": "step_2",
      "status": "failed",
      "record_hash": null,
      "compensation_hash": null,
      "error": "error sending request for url (http://payments-svc:7475/v1/records)"
    }
  ]
}

# All sagas (newest first)
curl http://localhost:7475/v1/saga

# One saga by ID
curl http://localhost:7475/v1/saga/<saga-id>

curl -X POST http://localhost:7475/v1/mutations \
-H "Content-Type: application/json" \
-d '{
  "target_agent_id": "orders",
  "proposer_agent_id": "primary",
  "kind": { "type": "SchemaVersion", "new_version": 2 }
}'

{
  "proposal_id": "019e2870911778e5...",
  "status": "pending",
  "policy": "TwoOfN"
}

# First approval
curl -X POST http://localhost:7475/v1/mutations/<proposal-id>/approve \
-H "Content-Type: application/json" \
-d '{"approver_agent_id": "admin-alice"}'

# Second approval — status flips to "approved"
curl -X POST http://localhost:7475/v1/mutations/<proposal-id>/approve \
-H "Content-Type: application/json" \
-d '{"approver_agent_id": "admin-bob"}'

# Apply the mutation
curl -X POST http://localhost:7475/v1/mutations/<proposal-id>/apply

{
  "proposal_id": "019e2870...",
  "applied": true,
  "target_agent_id": "orders",
  "mutation": "schema_version→2"
}

# Bump schema version
{ "type": "SchemaVersion", "new_version": 3 }

# Move agent to a different trust zone
{ "type": "ZoneChange", "new_zone": 2 }   // 0=immutable_core 1=protected 2=governed 3=free

# Propose adding a field (audit only — no storage-level enforcement in v1)
{ "type": "FieldAdd", "field_name": "phone", "field_type": "string" }

# Propose removing a field (audit only)
{ "type": "FieldRemove", "field_name": "legacy_id" }

# Propose a behavior change (audit only — for AI agent governance)
{ "type": "BehaviorPatch", "description": "rate-limit writes to 100/sec", "patch_b64": "..." }

# Reject a pending proposal
curl -X POST http://localhost:7475/v1/mutations/<id>/reject \
-H "Content-Type: application/json" \
-d '{"rejector_agent_id": "admin-charlie"}'

# Re-open a rejected proposal (creates a fresh proposal with same params)
curl -X POST http://localhost:7475/v1/mutations/<id>/reinit

# List all proposals
curl http://localhost:7475/v1/mutations

# Cage (marks agent as restricted, broadcasts event)
curl -X POST http://localhost:7475/v1/agent/cage

# Uncage (resume normal operation)
curl -X DELETE http://localhost:7475/v1/agent/cage

{ "caged": true,  "agent_id": "orders" }
{ "caged": false, "agent_id": "orders" }

curl http://localhost:7475/v1/status | jq .caged
# true  → agent is caged
# false → agent is operating normally

# See all available profiles
curl http://localhost:7475/v1/epigenetics/profiles

# Get active profile
curl http://localhost:7475/v1/epigenetics/profile

# Switch to analytics mode (read-only writes blocked)
curl -X PUT http://localhost:7475/v1/epigenetics/profile \
-H "Content-Type: application/json" \
-d '{"name": "analytics"}'

# View profile change history
curl http://localhost:7475/v1/epigenetics/history

# Any sapix command runs inside the container
docker exec sapixdb sapix status
docker exec sapixdb sapix agents list
docker exec sapixdb sapix mutant list

# Verify users agent — quiet mode (errors only)
docker exec sapixdb sapix chain verify users

# See every block as it is checked
docker exec sapixdb sapix chain verify users --verbose

# Machine-readable output for CI pipelines
docker exec sapixdb sapix chain verify users --json

  Verifying chain: users  (42 records)

  ✓  Chain intact  ·  42/42 blocks verified

  Verifying chain: users  (42 records)

  ✗  block     15  REC  hash=deadbeef1234…  parent=99aabbcc…  expected=7f3e12ab…

  ✗  Chain BROKEN  ·  1 error(s) across 42 blocks

{"sapix_export":true,"version":1,"agent_id":"users","total":42,"chain_head":"9aead8fb…","exported_at_ms":1747347600000}
{"record_id":"…","content_hash":"…","parent_hash":"…","timestamp_hlc":…,"flags":1,"schema_version":1,"payload_b64":"…"}

# Export to a timestamped file
docker exec sapixdb sapix strand export users | gzip > users-$(date +%Y%m%d).jsonl.gz

# Or write directly to a mounted volume
docker exec sapixdb sapix strand export users -o /data/backups/users.jsonl

# From a gzip backup — pipe through stdin
gunzip -c users-20260516.jsonl.gz | docker exec -i sapixdb sapix strand import users -i /dev/stdin

# Export from users, import into users_v2 on the same node
docker exec sapixdb sapix strand export users |   docker exec -i sapixdb sapix strand import users_v2 --url http://localhost:7475 -i /dev/stdin

# Export from one server, import into another
docker exec node1 sapix strand export users |   docker exec -i node2 sapix strand import users -i /dev/stdin

# Daily export of all agents at 02:00
0 2 * * * docker exec sapixdb sapix strand export users   | gzip > /backups/users-$(date +%Y%m%d).jsonl.gz
0 2 * * * docker exec sapixdb sapix strand export orders  | gzip > /backups/orders-$(date +%Y%m%d).jsonl.gz

• .srpx bundle — one encrypted file for the whole database, recommended for disaster recovery
• NDJSON export — per-agent export for targeted restores (see Section 18)

environment:
  SAPIX_MASTER_SEED: YOUR_64_HEX_MASTER_SEED   # same seed used to bundle and unbundle

SAPIX_MASTER_SEED=<64-hex> docker compose up -d --build

curl -X POST http://localhost:7475/v1/control/recovery/bundle

{
  "created_at_ms": 1716000000000,
  "total_records": 4485,
  "total_agents": 8,
  "size_bytes": 892416,
  "duration_ms": 847
}

curl http://localhost:7475/v1/control/recovery/status

{
  "seed_available": true,
  "last_bundle": {
    "created_at_ms": 1716000000000,
    "total_records": 4485,
    "total_agents": 8,
    "size_bytes": 892416,
    "duration_ms": 847
  },
  "age_secs": 3600
}

curl -O http://localhost:7475/v1/control/recovery/bundle/download
# saves as sapixdb-recovery-YYYYMMDD.srpx

# Bundle the whole database
sapix-recover bundle \
  --db-path /var/lib/sapixdb \
  --out /backups/snapshot.srpx \
  --seed $SAPIX_MASTER_SEED \
  --primary-id primary

# Or via docker exec
docker exec sapixdb sapix-recover bundle \
  --db-path /data/strand \
  --out /data/backups/snapshot.srpx \
  --seed $SAPIX_MASTER_SEED \
  --primary-id primary

# POST to create, then download to local backup directory
0 3 * * * curl -s -X POST http://localhost:7475/v1/control/recovery/bundle \
  && curl -s -o /backups/sapixdb-$(date +%Y%m%d).srpx \
     http://localhost:7475/v1/control/recovery/bundle/download

Error: seal verification failed — wrong seed or tampered bundle

Explore the full developer reference for advanced queries, distributed mode, agent graph traversal, and SaQL — our semantic query language.