Skip to main content

HelioDB (Phase 1)

HelioDB is the realtime event log for autonomous agents. Today’s build is single-node SQLite + WebSocket JSON-RPC with a type-safe TypeScript client and React hooks. ULID cursors give you history + live in one stream. See Platform Semantics for the precise guarantees in this Phase 1 release (ordering, cursors, filters, durability).

What You Get Right Now

  • Durable append + read + subscribe over WebSocket
  • Contract-driven TypeScript client (@heliodb/client, @heliodb/contract)
  • React hooks for realtime UIs (@heliodb/react)
  • ULID cursors for replay; JWT/shared-secret auth

Quick Start (minimal)

See README.md for the full quick start and context. Current scope: single-node SQLite, WebSocket JSON-RPC, TypeScript client + React hooks, ULID cursors.
# From repo root
make build
HELIODB_SECRET=dev-secret cargo run -p heliodb-server -- --db :memory: --secret $HELIODB_SECRET --port 8080
cargo run -p heliodb-server -- generate-token --namespace default --subject developer --full-access --secret $HELIODB_SECRET
import { HelioDB } from "@heliodb/client";
import { heliodb } from "@heliodb/contract";
import { z } from "zod";

const contract = {
	chat: heliodb.resource("chat/{roomId}").events({
		message: z.object({ text: z.string(), userId: z.string() }),
	}),
};

const client = new HelioDB({
	url: "ws://localhost:8080/ws",
	contract,
	token: "<dev token>",
	namespace: "default",
	subject: "chat-ui",
});

const room = client.resources.chat({ roomId: "general" });
await room.log({ type: "message", data: { text: "hello", userId: "alice" } });
// Fire-and-forget for streaming; pass durable: true or await room.flush() when you need to block

const sub = await room.subscribe();
for await (const event of sub) console.log(event.id, event.type, event.data);

Roadmap (Not in This Build)

  • Additional storage backends (under evaluation), hot/cold management
  • REST/SSE/webhooks
  • Additional SDKs (Python/Rust)
  • Multi-node/sharded deployment