cellz

SQLite-per-session, event-sourced state server for AI agents
Language-agnostic state & stream plane with atomic CAS leasing, Cloudflare R2 / S3 durability, and sub-millisecond local commits. Built in 100% Rust.

⚡ Positioning & Comparison with celld

While projects like denoland/celld bring Cloudflare Durable Objects to self-hosted environments by executing JavaScript/TypeScript Workers inside a sandbox, cellz takes a different, agent-focused path:

• Pure State & Stream Plane: cellz does not execute user code inside the cell. It is completely language-agnostic, exposing REST, SSE, and WebSocket interfaces so agents written in Rust, Python, TypeScript, or Go can connect instantly.
• Agent-Native Primitives: Built-in event sourcing, message materialization, key-value stores (Todos, Compactions), checkpointing, and branch rewinding.
• Atomic Single-Writer CAS Leases: Prevents split-brain across multiple distributed workers using S3 PutMode::Create / If-Match ETag conditional writes and atomic OS filesystem locks.
• Actor Mailbox Serialization: Snapshots (wal_checkpoint(TRUNCATE)) and state exports are serialized within the cell's actor mailbox, eliminating race gaps between WAL writes and backup reads.
• Lossless Realtime Reconnection: SSE stream supports Last-Event-ID and ?since= query parameters to seamlessly replay historical missed events before transitioning to live broadcast.

🏛️ Architecture

               ┌────────────────────────────────────────────────────────┐
               │              Client / Web UI / Coding Agent            │
               └──────────────────────────┬─────────────────────────────┘
                                          │ HTTP / SSE (Last-Event-ID) / WS
                                          ▼
                      ┌────────────────────────────────────────┐
                      │                 cellz                  │
                      │      (Axum REST & Real-time Mesh)      │
                      │                                        │
                      │  ┌──────────────────────────────────┐  │
                      │  │       Session Cell (Actor)       │  │
                      │  │  - Monotonic Event Sourcing       │  │
                      │  │  - Materialized Message Projection│  │
                      │  │  - Key-Value State Machine        │  │
                      │  │  - Dedicated SQLite (WAL Mode)    │  │
                      │  │  - Mailbox-Serialized Snapshots   │  │
                      │  └────────────────┬─────────────────┘  │
                      └───────────────────┼────────────────────┘
                                          │
                     ┌────────────────────┴────────────────────┐
                     ▼                                         ▼
        ┌─────────────────────────┐               ┌─────────────────────────┐
        │  Local Cell SQLite DBs  │               │   Blob Storage Engine   │
        │   `data/cells/{id}.db`  │               │ (Local FS / S3 / R2)    │
        │  (Microsecond Latency)  │               │ (CAS Leases & Snapshots)│
        └─────────────────────────┘               └─────────────────────────┘

For in-depth architectural details, refer to Architecture Specification.

🚀 Quick Start

Install from crates.io

cargo install cellz
cellz

Embed the Axum router in your own process:

[dependencies]
cellz = "0.1"

use std::sync::Arc;
use cellz::cell::CellManager;
use cellz::config::Config;
use cellz::server::create_router;
use cellz::storage::LocalBlobStore;

let config = Config::default();
let storage = Arc::new(LocalBlobStore::new(&config.storage_dir));
let manager = Arc::new(CellManager::new(
    &config.data_dir,
    storage,
    config.lease_ttl_secs,
));
let app = create_router(manager);

1. Run the Daemon from source

# Local filesystem storage
cargo run --release

# Or with Cloudflare R2 / S3
export CELLZ_STORAGE_BACKEND="s3"
export CELLZ_S3_ENDPOINT="https://<account_id>.r2.cloudflarestorage.com"
export CELLZ_S3_BUCKET="zene-cells"
export CELLZ_S3_ACCESS_KEY_ID="<your_key>"
export CELLZ_S3_SECRET_ACCESS_KEY="<your_secret>"
cargo run --release

2. Configuration Options

cellz is configured via environment variables:

3. Create a Session & Append Events

# 1. Create a new Cell
curl -X POST http://localhost:8080/api/v1/cells \
  -H "Content-Type: application/json" \
  -d '{"id": "agent-007", "name": "Refactor Agent"}'

# 2. Append a user message
curl -X POST http://localhost:8080/api/v1/cells/agent-007/events \
  -H "Content-Type: application/json" \
  -d '{
    "turn_id": "turn-1",
    "event_type": "user_message",
    "payload": { "content": "Add unit tests for cell/db.rs" }
  }'

# 3. Retrieve projected messages
curl http://localhost:8080/api/v1/cells/agent-007/messages

# 4. Subscribe to real-time events via SSE
curl -N -H "Accept: text/event-stream" http://localhost:8080/api/v1/cells/agent-007/stream

Full API documentation and request/response payloads are available in API Reference.

🧪 Testing & Quality Gates

Run full test suite:

cargo test --workspace

Run linter:

cargo clippy --all-targets -- -D warnings

📚 Documentation Index

• Architecture Specification: Deep dive into Per-Cell SQLite, Actor lifecycle, and lease management.
• API Reference: Complete REST, SSE, and WebSocket endpoints specification.
• Admin UI Kit: Admin console UI framework and component catalog.

📄 License

Licensed under either of

• Apache License, Version 2.0 (LICENSE-APACHE)
• MIT license (LICENSE-MIT)

at your option.