Installation

APT (Debian/Ubuntu)

# Import the signing key
curl -fsSL https://saxy.github.io/tellstone-apt/key.gpg \
  | sudo gpg --dearmor -o /usr/share/keyrings/tellstone.gpg

# Add the repository
echo "deb [signed-by=/usr/share/keyrings/tellstone.gpg] https://saxy.github.io/tellstone-apt stable main" \
  | sudo tee /etc/apt/sources.list.d/tellstone.list

# Install
sudo apt update && sudo apt install tellstone

Homebrew (macOS/Linux)

brew tap Saxy/tellstone-tap
brew install --cask tellstone

Binary downloads

Pre-built binaries for Linux, macOS, and Windows (amd64/arm64) are available on the GitHub Releases page.

# Example: Linux amd64
curl -fsSL https://github.com/Saxy/Tellstone/releases/latest/download/tellstone_1.0.0_linux_amd64.tar.gz \
  | tar xz
sudo mv tellstone /usr/local/bin/

Verify the installation:

tellstone --version

Container images

Container images are published to GitHub Container Registry on every release. The images use a distroless base with no shell or package manager, and run as a non-root user.

Pull and run

# Pull the latest release
podman pull ghcr.io/saxy/tellstone:latest

# Run with the binary protocol on port 9988
podman run --rm -p 9988:9988 ghcr.io/saxy/tellstone:latest

# Run with both binary and RESP protocols
podman run --rm -p 9988:9988 -p 6379:6379 \
  ghcr.io/saxy/tellstone:latest \
  -addr 0.0.0.0:9988 --enable-resp -resp-addr 0.0.0.0:6379

Replace podman with docker if you use Docker — the images are OCI-compliant and work with both.

Pin a version

podman pull ghcr.io/saxy/tellstone:1.2.0

Persist data

Mount a volume for the data directory:

podman run --rm \
  -p 9988:9988 \
  -v ./data:/data:Z \
  -e TSD_DATA_DIR=/data \
  ghcr.io/saxy/tellstone:latest

The :Z suffix handles SELinux relabeling for rootless Podman.

Local development image

Build a dev image from source using the Taskfile:

task podman:build     # builds ghcr.io/saxy/tellstone:dev
task podman:up        # runs on ports 9988 + 6379, mounts ./data
task podman:logs      # tail logs
task podman:down      # stop container

Kubernetes

The container image is suitable for direct use in Kubernetes. A minimal deployment:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: tellstone
spec:
  replicas: 1
  selector:
    matchLabels:
      app: tellstone
  template:
    metadata:
      labels:
        app: tellstone
    spec:
      containers:
        - name: tellstone
          image: ghcr.io/saxy/tellstone:1.2.0
          ports:
            - containerPort: 9988    # binary protocol
            - containerPort: 6379    # RESP (optional)
          env:
            - name: TSD_ADDR
              value: "0.0.0.0:9988"
            # - name: TSD_ENABLE_RESP
            #   value: "true"
            # - name: TSD_ENABLE_PERSISTENCE
            #   value: "true"
          readinessProbe:
            tcpSocket:
              port: 9988
            initialDelaySeconds: 1
            periodSeconds: 5
          resources:
            requests:
              memory: "64Mi"
              cpu: "100m"
            limits:
              memory: "512Mi"
              cpu: "500m"

See Configuration for all environment variables and flags.

Build from source

Prerequisites

• Go 1.26+
• Optional: task (go-task) for the shortcuts below
• Optional, for RESP benchmarking: redis-cli, memtier_benchmark, or redis-tools

Build

git clone https://github.com/Saxy/Tellstone
cd Tellstone
task build          # -> ./bin/tellstone

Without task, build directly with Go:

go build -o bin/tellstone ./cmd/tellstone

Run

task run            # binary protocol on 127.0.0.1:9988
task run:resp       # binary on :9988  +  Redis-compatible RESP on :6379

Or run the binary directly with flags or environment variables:

./bin/tellstone --addr 127.0.0.1:9988 --enable-resp --resp-addr 127.0.0.1:6379

TSD_ADDR=127.0.0.1:9988 TSD_ENABLE_RESP=true ./bin/tellstone

See Configuration for the full list of flags and environment variables.

Advanced Configuration

For production deployments, consider setting additional environment variables:

• TSD_GC_PERCENT=-1 to disable Go’s garbage collector for maximum performance
• TSD_MEM_LIMIT_BYTES to set a memory ceiling for the Go runtime
• TSD_ENABLE_PROFILING=1 to enable pprof profiling on 127.0.0.1:6060
• TSD_ENABLE_PERSISTENCE=true to enable WAL persistence for crash recovery

Next: run through the quickstart to store and read your first key.