SapixDB is the world's first agent-native database. It treats every record as a cryptographically signed nucleotide, hash-linked into an immutable strand — giving you built-in audit trails, time travel queries, and schema evolution without migrations.

How is SapixDB different from PostgreSQL or MongoDB?

Traditional databases store mutable rows with no built-in history. SapixDB is append-only by design: every write is cryptographically signed and linked to its predecessor. You get immutable audit trails, time travel, and agent-owned data ownership without external tooling.

Does SapixDB require schema migrations?

No. SapixDB uses Mutant-governed schema evolution — the schema evolves in place via versioned nucleotide types, never requiring ALTER TABLE or migration scripts.

Is SapixDB HIPAA and SOX compliant?

Yes. Because every record is cryptographically signed and immutably linked, SapixDB produces a tamper-evident audit trail natively. HIPAA data lineage and SOX financial audit requirements are satisfied at the storage layer without external compliance tooling.

How do I get started with SapixDB?

SapixDB is available as a Docker image. Run `docker compose up -d` and the agent starts on port 7475. See the documentation at sapixdb.com/docs for full quickstart instructions.

Phase 4 · Boboyka Integration

Boboyka Integration

SapixDB is Boboyka's production database layer. Every SaaS app Boboyka builds runs on SapixDB. Boboyka's own internal data — build history, queue state, agent health, and audit trail — are stored as SapixDB strands, making them cryptographically auditable and time-travelable from day one.

Dual-write✓ complete

Ingest to SapixDB. Mirror to Supabase if env vars set. SapixDB write always happens first.

Migrate internalsplanned

Boboyka removes its Supabase write path. SapixDB becomes the single source of truth.

Cut overplanned

New Boboyka projects use SapixDB only. Legacy projects stay on Supabase until migrated.

Dual-write Flow

When BOBOYKA_SUPABASE_URL and BOBOYKA_SUPABASE_KEY are set, every ingest writes to SapixDB first, then mirrors the payload to the matching Supabase REST table. A Supabase failure is recorded in the event metadata but does not abort or roll back the SapixDB write.

POST /v1/boboyka/ingest
1
MessagePack-encode payload (tagged with _boboyka_type)
2
Append to strand → get content hash
3
If Supabase env set → POST to matching table(failure non-fatal)
4
Write BoboykaEventRef to graph meta index
5
Return record_hash + dual_write result

ℹ Supabase table routingEach record type maps to a fixed Supabase table: project_build → project_builds, build_queue_item → build_queue, agent_health → agent_health, audit_log → agent_audit_log.

Record Types

project_build

→ project_builds

One build run for a Boboyka project — status, agent, timing, and output URL.

queuedrunningsucceededfailed

JSON schema

{
  "project_id":      "proj_abc",
  "build_id":        "bld_xyz",
  "status":          "succeeded",
  "agent_id":        "boboyka_builder",
  "started_at_ms":   1747000000000,
  "completed_at_ms": 1747000012000,
  "output_url":      "https://cdn.example.com/builds/bld_xyz.tar.gz"
}

build_queue_item

→ build_queue

A single item in Boboyka's build queue. Updated when the builder picks it up.

waitingprocessingdone

JSON schema

{
  "queue_id":       "q_001",
  "project_id":     "proj_abc",
  "priority":       1,
  "status":         "waiting",
  "enqueued_at_ms": 1747000000000,
  "dequeued_at_ms": null
}

agent_health

→ agent_health

Periodic health snapshot from a Boboyka sub-agent. CPU, memory, and status.

healthydegradedunhealthy

JSON schema

{
  "agent_id":     "boboyka_builder",
  "status":       "healthy",
  "cpu_pct":      23.4,
  "memory_mb":    512,
  "checked_at_ms": 1747000000000
}

audit_log

→ agent_audit_log

Any auditable action taken by a Boboyka agent — deployments, config changes, and more.

JSON schema

{
  "agent_id":    "boboyka_builder",
  "event":       "deploy_completed",
  "actor":       "ci_pipeline",
  "timestamp_ms": 1747000000000,
  "metadata":    { "env": "production" }
}

HTTP API

Method	Path	Description
`POST`	`/v1/boboyka/ingest`	Ingest event; dual-write to Supabase if configured
`GET`	`/v1/boboyka/status`	Integration phase, dual-write flag, per-type event counts
`GET`	`/v1/boboyka/events`	List recent events, newest first (limit, record_type params)

Ingest request / response

HTTP

POST /v1/boboyka/ingest
Content-Type: application/json

{
  "record_type": "project_build",
  "data": {
    "project_id": "proj_abc",
    "build_id":   "bld_001",
    "status":     "running",
    "agent_id":   "boboyka_builder"
  }
}

JSON — dual-write enabled

{
  "record_hash":   "a1b2c3d4e5f6...",
  "record_type":   "project_build",
  "ingested_at_ms": 1747000000042,
  "dual_write": {
    "enabled": true,
    "ok":      true,
    "error":   null
  }
}

JSON — Supabase not configured

{
  "record_hash":   "a1b2c3d4e5f6...",
  "record_type":   "project_build",
  "ingested_at_ms": 1747000000042,
  "dual_write": {
    "enabled": false,
    "ok":      null,
    "error":   null
  }
}

Status response

JSON

{
  "integration_phase":  "Phase 1 — dual-write (SapixDB + Supabase)",
  "dual_write_enabled": true,
  "supabase_url":       "https://xyzproject.supabase.co",
  "event_counts": {
    "project_build":    142,
    "build_queue_item":  87,
    "agent_health":     310,
    "audit_log":         56
  },
  "total_events": 595
}

Configuration

Both environment variables must be set to activate dual-write. If either is absent, ingest writes to SapixDB only.

shell

# Enable Supabase dual-write (both required)
export BOBOYKA_SUPABASE_URL="https://<project-ref>.supabase.co"
export BOBOYKA_SUPABASE_KEY="<service_role_key>"

⚠ Service role key requiredDual-write uses the Supabase REST API with the service_role key. The key is never returned by GET /v1/boboyka/status — only the URL is surfaced.

Python SDK

shell

pip install sapixdb-boboyka

build_pipeline.py

import asyncio
from sapixdb_boboyka import BoboykaClient

async def on_build_complete(project_id: str, build_id: str, success: bool):
    async with BoboykaClient("http://localhost:7475") as boboyka:
        resp = await boboyka.ingest_build(
            project_id=project_id,
            build_id=build_id,
            status="succeeded" if success else "failed",
            agent_id="boboyka_builder",
            completed_at_ms=int(__import__("time").time() * 1000),
        )
        print(f"Recorded build {build_id}: {resp.record_hash[:16]}…")
        if not resp.dual_write.ok and resp.dual_write.enabled:
            print(f"  ⚠ Supabase mirror failed: {resp.dual_write.error}")

asyncio.run(on_build_complete("proj_abc", "bld_007", success=True))

health_monitor.py

import asyncio
import psutil
from sapixdb_boboyka import BoboykaClient

async def report_health(agent_id: str):
    cpu = psutil.cpu_percent(interval=1)
    mem = psutil.virtual_memory().used // (1024 * 1024)
    status = "healthy" if cpu < 80 else "degraded"

    async with BoboykaClient("http://localhost:7475") as boboyka:
        await boboyka.ingest_health(
            agent_id=agent_id,
            status=status,
            cpu_pct=cpu,
            memory_mb=mem,
        )

asyncio.run(report_health("boboyka_builder"))

audit_example.py

import asyncio
from sapixdb_boboyka import BoboykaClient

async def log_deploy(agent_id: str, env: str):
    async with BoboykaClient("http://localhost:7475") as boboyka:
        await boboyka.ingest_audit(
            agent_id=agent_id,
            event="deploy_completed",
            actor="ci_pipeline",
            metadata={"env": env, "version": "2.4.1"},
        )

        # Tail the last 10 audit events
        feed = await boboyka.audit_events(limit=10)
        for ev in feed.events:
            print(f"  [{ev.ingested_at_ms}] {ev.record_hash[:12]}…  ok={ev.dual_write_ok}")

asyncio.run(log_deploy("boboyka_builder", "production"))

via SapixClient (no extra package)

from sapixdb_agent import SapixClient

async def main():
    async with SapixClient("http://localhost:7475") as client:
        # Ingest
        resp = await client.boboyka_ingest("agent_health", {
            "agent_id":     "boboyka_builder",
            "status":       "healthy",
            "cpu_pct":      12.1,
            "memory_mb":    128,
            "checked_at_ms": 1747000000000,
        })
        print(resp["record_hash"])

        # Status
        status = await client.boboyka_status()
        print(status["total_events"])

        # Events feed
        events = await client.boboyka_events(limit=20, record_type="audit_log")
        print(events["events"])

SDK API Reference

Method	Returns	Description
`ingest(record_type, data)`	`IngestResponse`	Raw ingest — any record type
`ingest_build(...)`	`IngestResponse`	Typed helper for project_build
`ingest_queue_item(...)`	`IngestResponse`	Typed helper for build_queue_item
`ingest_health(...)`	`IngestResponse`	Typed helper for agent_health
`ingest_audit(...)`	`IngestResponse`	Typed helper for audit_log
`status()`	`BoboykaStatusResponse`	Integration phase + per-type counts
`events(limit, record_type)`	`EventsResponse`	Recent events, all types or filtered
`build_events(limit)`	`EventsResponse`	Shorthand: project_build events only
`health_events(limit)`	`EventsResponse`	Shorthand: agent_health events only
`audit_events(limit)`	`EventsResponse`	Shorthand: audit_log events only

Known Limitations

Dual-write failures are recorded in graph meta but not retried. A future release will add a retry queue for failed Supabase writes.

Phase 2 (migrate Boboyka internals) requires coordination with the Boboyka team — SapixDB provides the ingest API; Boboyka must remove its own Supabase write path.

GET /v1/boboyka/events scans a graph meta prefix. For very high ingest rates this should be paginated with a cursor (planned).

The Control Plane test ingest panel is a developer convenience only — production Boboyka services should call the ingest API directly.

Power your SaaS with SapixDB

Cryptographic audit trail, time travel, and Supabase dual-write — all wired in from day one.

Request Early Access