Quick Start

This page assumes a single node is already running on 127.0.0.1:4437. Starting one is a single Docker or Cargo command, see Install. The default node keeps nothing across restarts. For disk-backed persistence, set raft.wal.path (see Configuration).

Drive the HTTP API with curl from another terminal.

Validate the bucket ID (optional)

Buckets are implicit: a bucket exists once a stream is created in it, so this call is optional. It only validates the bucket ID (201, or 400 for an invalid one):

curl -X PUT http://127.0.0.1:4437/demo

Create a stream

curl -X PUT http://127.0.0.1:4437/demo/hello

Append data

curl -X POST http://127.0.0.1:4437/demo/hello \
  -H 'Content-Type: application/octet-stream' \
  --data-binary 'first message'

curl -X POST http://127.0.0.1:4437/demo/hello \
  -H 'Content-Type: application/octet-stream' \
  --data-binary 'second message'

Each successful append returns 204 No Content with a Stream-Next-Offset header. Add Producer-Id / Producer-Epoch / Producer-Seq if you need exactly-once retries.

Read everything from the beginning

curl -i 'http://127.0.0.1:4437/demo/hello?offset=-1'

The body contains the appended bytes. Response headers include Stream-Next-Offset, Stream-Up-To-Date, and an ETag.

Subscribe for live updates

Open a second terminal:

curl -N 'http://127.0.0.1:4437/demo/hello?offset=-1&live=sse'

-N keeps curl from line-buffering the SSE stream. Append more data from the first terminal and you'll see it arrive immediately as event: data lines. Binary streams are delivered as raw base64 text in event: data payloads (Stream-Sse-Data-Encoding: base64). See binary SSE for details.

Inspect runtime state

For a multi-node cluster the canonical day-2 tool is ursulactl. It speaks to every node, summarises leadership, and wraps restarts in safe drain and catch-up steps. For a single local node you can either point it at a one-line manifest:

cat > /tmp/local.json <<'JSON'
{"nodes": [{"id": 1, "http_url": "http://127.0.0.1:4437", "host": "127.0.0.1"}]}
JSON

ursulactl status --config /tmp/local.json

Or hit the underlying JSON endpoint directly:

curl http://127.0.0.1:4437/__ursula/metrics

The raw endpoint is also what ursulactl consumes. Use it directly when you want the full snapshot or are building custom tooling.

Next steps

• Deploy a Cluster: the production three-voter shape with Helm
• Configuration: persistence, presets, and S3 cold storage in one place
• ursulactl: the operator CLI you'll use once a cluster is up
• API overview: the HTTP surface Ursula currently exposes
• Streams: the core stream abstraction and lifecycle
• Architecture: thread-per-core, multi-Raft internals