On this page
GET STARTED
Your first
durable write.
From a release image to a verified connection. Follow the steps once, then bring your own payload.
RELEASE 0.1.6 · Docker Hub ↗
Thunder is a self-hosted key-value database, distributed as thunderstrike. That is the name you will see in the image, commands, environment variables, and release kit.
The commands below use a POSIX shell: Linux, macOS, or WSL on Windows. The database runs on Linux, including the Linux VM used by Docker Desktop.
Check your machine.
- Docker with Compose v2. Linux kernel 6.8 or newer on the Docker host or VM. A new container image does not update the host kernel.
- A supported CPU. x86-64 with AVX2, or ARM64 v8.2 with Crypto Extensions. The default x86 image does not require AVX-512.
- Memory. At least 4 GiB for the default arena allocation, plus overhead. Larger core budgets increase total memory requirements.
- Storage. ext4 or XFS under Docker’s data directory. Keep Docker Desktop data in a named volume.
- OpenSSL in your shell to generate the keystore passphrase in the steps below.
Run your first instance.
01 Get the image and release kit.
The published 0.1.6 image includes a release kit. Run these commands in a new working directory. The kit contains the Compose configuration, settings, seccomp profile, product guide, and license.
mkdir thunderstrike-run
cd thunderstrike-run
docker run --rm -v "$PWD:/out" docker.io/sbansal793/thunderstrike:0.1.6 kit /outBuilding from source instead?
Run this from the repository root. The build pins the image reference inside the release kit so Compose uses the same local image.
docker build --build-arg IMAGE_REF=thunderstrike:local -t thunderstrike:local .
mkdir thunderstrike-run
cd thunderstrike-run
docker run --rm -v "$PWD:/out" thunderstrike:local kit /out02 Choose cores and memory.
Copy the example settings, then edit .env. Keep the image reference written by the kit. Start with the kit’s defaults: a physical-core budget of 2 and automatic arena sizing. Leave THUNDERSTRIKE_ARENA_BYTES empty for the sample workload.
cp .env.example .envTHUNDERSTRIKE_CORES=2
THUNDERSTRIKE_TLS_PORT=7380
THUNDERSTRIKE_ARENA_BYTES=These defaults allocate 4 GiB of arena memory in total: two 2 GiB reactors with SMT, or one 4 GiB reactor without it. Add process overhead. For 512 MiB values, explicitly set THUNDERSTRIKE_ARENA_BYTES=4294967296; see large-value sizing.
Generate the exact port mapping from the CPU topology. Run this again whenever the core budget, starting port, or available topology changes.
docker compose -f compose.yaml run --rm configure03 Create the keystore passphrase.
The passphrase unlocks the encryption keys. Keep it backed up with the data volume: losing either loses access to your values. Run these commands once in a fresh kit directory.
mkdir -p docker/secrets docker/tls
openssl rand -base64 32 > docker/secrets/passphrase
chmod 600 docker/secrets/passphrase04 Create a TLS identity.
Set THUNDERSTRIKE_TLS_NAMES in .env to the hostnames clients use. The default is localhost; retain it when running the included sample. The initialization job creates an Ed25519 CA and a server certificate.
docker compose run --rm tls-initClients trust docker/tls/ca.crt. Keep ca.key private; only the server certificate and key are mounted into the database.
05 Start the database.
docker compose up -d
docker compose psWait for healthy. The health check becomes ready after every reactor has recovered its stores and opened its port.
A healthy server and a sample that exits with code 0: every written value was read back without errors or mismatches.
Write. Read. Verify.
The included sample client writes values of 256 B, 4 KiB, 64 KiB, 2 MiB, and 16 MiB over 8 connections for 30 seconds. It reads each value back and compares the bytes. Exit code 0 means no mismatches and no errors.
docker compose run --rm sampleThis is an end-to-end correctness check, not a universal throughput guarantee. Benchmark your actual payload mix, read/write ratio, concurrency, CPU allocation, and storage. The default sample does not exercise 512 MiB values.
Fixed shards. Local ownership.
Thunder always uses 1,024 logical shards. Each reactor owns a contiguous shard range, one arena, and one port. A reactor group uses two hardware threads: one for the foreground reactor, the other shared by background workers.
| PHYSICAL CORES | THREADS / CORE | REACTORS | SHARDS / REACTOR | PORTS |
|---|---|---|---|---|
| 2 | 1 | 1 | 1,024 | 7380 |
| 2 | 2 | 2 | 512 | 7380–7381 |
| 8 | 1 | 4 | 256 | 7380–7383 |
| 8 | 2 | 8 | 128 | 7380–7387 |
The client starts with one address and asks for DISCOVER. It computes CRC32C(key) % 1024, finds the owning range in the returned layout, and connects to the corresponding reactor. All generated ports must be reachable on the same host with the same port numbers.
CPU affinity, quotas, and actual sibling relationships affect the allocation. CORES is a physical-core budget, not a reactor count. The public budget is even, from 2 through 1,024.
Give large values enough room.
Values of 512 MiB and more are first-class. Capacity depends on the arena, in-flight work, and available disk.
- Memory: one SET needs two copies of its value in the arena. Configure
THUNDERSTRIKE_ARENA_BYTES=4294967296for 512 MiB values. - Defaults: 4 GiB with one reactor, or 2 GiB per reactor when there are two or more. Arena memory is resident from boot; the container limit must exceed total arena bytes plus process overhead.
- Disk: plan for peak live bytes divided by 0.75, plus one 4 GiB chunk for workloads storing values of 512 MiB or more.
- Full disk: writes return
StorageExhausted; the server continues serving reads.
A practical example: 8 physical cores with SMT ×2 derive 8 reactors. At 4 GiB per reactor, budget 32 GiB of arena RAM, plus overhead. For 300 GiB of live values including 512 MiB objects, the documented disk-sizing rule gives 404 GiB.
Durability is part of the path.
Each write’s journal record reaches disk before acknowledgement. The product guide states that acknowledged writes survive a crash or power cut. TLS 1.3 is mandatory, and all values are encrypted at rest.
Stop cleanly.
docker compose stop thunderstrikeThe server stops accepting work, drains in-flight requests, checkpoints the index, and exits. Compose allows two minutes. A forced kill is a crash.
Back up the store and passphrase together.
Stop the server or take a filesystem snapshot, then copy the whole data volume and preserve the passphrase securely. Copying files while the database writes is not a consistent backup. Follow the complete procedure in the product guide.
Change topology after a clean stop.
Run configure again after changing the core budget, starting port, or available topology, then restart. After a crash, recover with an allocation producing the previous reactor count and stop cleanly before changing it; journals belong to reactors.
Connect your application.
The official Python client handles discovery and routing. After the server is healthy, install the client and run this example from the release-kit directory.
pip install thunderstrikefrom thunderstrike import Thunderstrike
with open("docker/tls/ca.crt") as ca:
ca_pem = ca.read()
db = Thunderstrike(
"127.0.0.1:7380",
tls_server_name="localhost",
tls_ca_pem=ca_pem,
)
db.set(b"agent:42:state", b'{"step": 4}')
print(db.get(b"agent:42:state"))Clients support Linux x86-64 / ARM64, Windows x86-64, and macOS on Intel and Apple silicon. See the official client documentation for Node.js, Go, Rust, .NET, Java, PHP, and C / C++ examples.
Thunder stores opaque bytes by key using its own binary protocol over TLS 1.3. It is not a Redis protocol endpoint and does not provide vector similarity search, model execution, automatic GPU integration, or automatic TTL expiry.
- Choose stable keys for inference artifacts, agent sessions, or media segments. Version them when your serialization or model changes.
- Serialize your payload in the application. Store the bytes as a value and deserialize after retrieval.
- Use an official client. Supply one bootstrap address. The client discovers the shard layout and manages connections to the owning reactor ports.
- Own the lifecycle. Your application decides which artifacts to reuse, invalidate, or delete. Evaluate your workload’s largest objects and concurrent writes.
For detailed configuration and operations, download the full product guide.
Explore the use cases