mirror of
https://github.com/hanzoai/kv.git
synced 2026-11-09 16:05:35 +00:00
forge/main
`.hanzo/workflows/deploy.yml` asks for runs-on: hanzo-linux-amd64. Across the seven repos carrying this same file it has produced zero job rows, while other workflows in the same repos dispatch normally over the same pushes -- in hanzo/engine, ci.yml and gpu-tests.yml ran 30 times in the window this file ran none. The label routes nowhere, so the job queues until it times out and no run appears to say so. The rest of the file names things that are equally gone: buildctl-daemonless.sh is absent from the runner image, secrets.GIT_CLONE_TOKEN is unset, and the closing `kubectl -n hanzo patch app` is reverted by CD, which takes the tag from hanzoai/universe. hanzoai/iam's image.yml is the repaired form of this template if this repo wants a build lane again; a file that cannot run is not one.
Hanzo KV
High-performance key-value store for the Hanzo ecosystem.
In-memory data store used as database, cache, streaming engine, and message broker.
Features
- In-memory key-value store -- sub-millisecond reads and writes
- Redis-compatible protocol -- drop-in replacement for existing Redis clients
- Persistence -- RDB snapshots and AOF (append-only file) for durability
- Replication -- primary-replica with automatic failover via Sentinel
- Lua scripting -- server-side scripting for atomic operations
- Pub/Sub -- publish and subscribe messaging
- Streams -- append-only log data structure for event sourcing
- Cluster mode -- horizontal scaling with automatic sharding
- Modules -- extensible plugin system for custom data structures
- ZAP native -- built-in ZAP binary protocol on port 9653 (17x faster than JSON-RPC)
- Multi-arch -- linux/amd64 and linux/arm64
Quick Start
Docker
docker run -d --name hanzo-kv -p 6379:6379 ghcr.io/hanzoai/kv
Connect
docker exec -it hanzo-kv kv
127.0.0.1:6379> SET hello world
OK
127.0.0.1:6379> GET hello
"world"
Any Redis-compatible CLI also works out of the box.
Build from Source
make
make test
make install
CLI Tools
| Command | Description |
|---|---|
kv |
Interactive CLI (default) |
kv-server |
Start KV server |
kv-cli |
Command-line client |
kv-sentinel |
High-availability sentinel |
kv-benchmark |
Performance benchmarking |
kv-check-aof |
AOF file integrity check |
kv-check-rdb |
RDB file integrity check |
Configuration
Pass a config file at startup:
kv-server /etc/kv/kv.conf
Or set options via command line:
kv-server --port 6379 --maxmemory 256mb --appendonly yes
ZAP Binary Protocol
Hanzo KV speaks ZAP natively on port 9653 — no sidecar needed.
ZAP is a zero-copy binary protocol that's 17x faster than JSON-RPC with 11x less memory usage.
Enable ZAP
ZAP is enabled by default. Load the module:
kv-server --loadmodule /path/to/zap.so
# or with custom port:
kv-server --loadmodule /path/to/zap.so PORT 9653
ZAP Operations
| Path | Body | Description |
|---|---|---|
/get |
{"key":"mykey"} |
GET a key |
/set |
{"key":"mykey","value":"myval"} |
SET a key |
/del |
{"key":"mykey"} |
DEL a key |
/cmd |
{"cmd":"PING","args":[]} |
Execute any command |
Module API
Develop custom modules using the KV Module API:
#include "kvmodule.h"
int KVModule_OnLoad(KVModuleCtx *ctx, KVModuleString **argv, int argc) {
if (KVModule_Init(ctx, "mymod", 1, KVMODULE_APIVER_1) == KVMODULE_ERR)
return KVMODULE_ERR;
// register commands...
return KVMODULE_OK;
}
Client SDKs
| Language | Package | Install |
|---|---|---|
| Python | hanzo-kv | pip install hanzo-kv |
| Go | hanzo/kv-go | go get github.com/hanzoai/kv-go |
| Node.js | @hanzo/kv | npm install @hanzo/kv |
Any Redis-compatible client library will also work.
Documentation
Full documentation is available at docs.hanzo.ai.
License
BSD-3-Clause
Copyright (c) 2024-2026 Hanzo AI Inc. All rights reserved.
Languages
C
69%
Tcl
26.1%
C++
3.3%
Python
0.5%
CMake
0.3%
Other
0.8%