This guide starts one local broker and exercises it with the in-repository Go SDK examples. See Installation for build/container details and Configuration before production use.
docker pull ghcr.io/cursus-io/cursus:latest
docker run --rm --name cursus \
-p 9000:9000 -p 9080:9080 -p 9100:9100 \
-v cursus-data:/root/broker-logs \
ghcr.io/cursus-io/cursus:latest
The default ports are:
| Port | Purpose |
|---|---|
| 9000 | Wire v2 TCP client protocol |
| 9080 | /live, /ready |
| 9100 | Prometheus /metrics |
In another terminal:
curl -f http://localhost:9080/live
curl -f http://localhost:9080/ready
curl -f http://localhost:9100/metrics
For production, mount a configuration, enable client TLS/auth, configure a separate broker-internal mTLS listener for clusters, and use durable storage.
Cursus requires Go 1.25.0 or newer.
git clone https://github.com/cursus-io/cursus.git
cd cursus
make build
./bin/cursus
Development mode:
make run
make build creates bin/cursus and bin/cursus-cli. Benchmarks are Docker/Go test workloads rather than a third binary.
With the broker running:
cd examples
go run ./publisher
Then run the consumer:
cd examples
go run ./consumer
examples/config.yaml uses localhost:9000, topic example-topic, and group example-group. The default Go consumer uses broker-owned offset resume and read_committed; after successful processing it commits the next offset. Edit the example configuration or construct sdk.ConsumerConfig directly for auto_offset_reset, TLS/auth, and other settings.
./bin/cursus-cli
The current CLI creates local broker components and executes commands in-process. It is useful for command exploration, but it is not a remote network administration client for an already running broker. Use the in-repository Go SDK or another client that passes the current Wire v2 conformance contract for remote operations.
Raw nc localhost 9000 text is not valid because every connection must complete the Wire v2 binary handshake and exchange CRS2 frames.
Standalone mode is the default. Cluster mode adds Raft metadata, partition leaders, group/transaction coordinator routing, replication quorum, and broker-internal authentication/mTLS. Client commands remain the same and redirects identify the correct owner.
Use the checked-in E2E compose topology as a development reference:
make e2e
The 100000-record standalone/cluster benchmark is intentionally opt-in:
RUN_E2E_BENCHMARK=1 go test -v -timeout 30m ./test/e2e-benchmark/...
nextOffset; commit lastProcessedOffset + 1,read_committed is the default; read_uncommitted exposes raw control records,(topic, group, member, generation) scope,