Organisms and Agents

What you'll learn

How to register additional named agents on this SapixDB process, and pre-load them at startup via an env var.

Agents

An agent is a named strand with its own Ed25519 keypair and encryption key — the unit of write isolation in SapixDB. One process can serve any number of agents; each is a separate, cryptographically isolated chain of records with no shared sequence counter.

> SapixDB also has a separate, optional organism concept: a group of agents created together under one organism_id, each automatically named <organism_id>::<agent_name>. A single process can host any number of organisms, each with any number of agents — organisms group agents, they don't limit how many a process can run. This lesson covers plain, flat agents (no :: namespace); organisms get their own later lesson.

Create a second agent

`bash # generate a random keypair seed for the new agent (64 hex chars = 32 bytes) python3 -c "import secrets; print(secrets.token_hex(32))"

curl -s -X POST http://localhost:7475/v1/agents \ -H "Content-Type: application/json" \ -H "Authorization: Bearer spx_root_YOUR_ROOT_KEY" \ -d '{"agent_id": "users", "seed_hex": "YOUR_GENERATED_SEED_HEX"}' \ | python3 -m json.tool `

Create a third: `bash curl -s -X POST http://localhost:7475/v1/agents \ -H "Content-Type: application/json" \ -H "Authorization: Bearer spx_root_YOUR_ROOT_KEY" \ -d '{"agent_id": "orders", "seed_hex": "ANOTHER_GENERATED_SEED_HEX"}' \ | python3 -m json.tool `

List all agents

curl -s http://localhost:7475/v1/agents \
  -H "Authorization: Bearer spx_root_YOUR_ROOT_KEY" \
  | python3 -m json.tool

Write to a specific agent

curl -s -X POST http://localhost:7475/v1/agents/users/records/json \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer spx_root_YOUR_ROOT_KEY" \
  -d '{"data": {"name": "Alice", "email": "alice@example.com", "plan": "pro"}}' \
  | python3 -m json.tool

Each agent has its own strand. Writing to users does not affect orders. There is no shared sequence counter.

Naming conventions

Good agent names are lowercase, hyphenated, descriptive: - user-profiles - order-events - payment-ledger - audit-log

Agents work like tables in spirit, but with important differences: they have identity, history, and can own their data domain autonomously.

Pre-load agents at startup

Instead of creating agents via the API, SAPIX_AGENTS loads a fixed list at boot — note the format is id:seed_hex pairs, comma-separated, not JSON:

environment:
  SAPIX_AGENTS: "users:1111111111111111111111111111111111111111111111111111111111111111,orders:2222222222222222222222222222222222222222222222222222222222222222"

Each seed must be 64 hex characters (32 bytes), generated the same way as in "Create a second agent" above.

Authorization

POST /v1/agents (create) requires the root key or a scoped key holding admin:agents — creating a new agent is instance-level configuration, not an ordinary per-tenant write, so a plain write:agents/* key is not enough.

Challenge

1. Create three agents: products, reviews, inventory
2. Write one record to each
3. Confirm with GET /v1/health that record_count reflects writes across all agents

---