Cache / KV

Truss ships a Redis-compatible cache / key-value store powered by Valkey (the Linux Foundation’s open-source Redis fork). Use it for caching expensive queries, session storage, rate-limit counters, and any ephemeral key/value data. Browse and edit the keyspace from the Cache panel, or connect any Redis client from your app.

Architecture

your app ──┐
           ├─► Truss API ──► Valkey (truss-valkey:6379)
dashboard ─┘     /api/cache/*        in-memory KV

The Cache panel talks to the API’s /api/cache/* routes (keyspace scan, get/set/delete, TTL, stats). Your application connects to Valkey directly with any Redis client for the hot path — the dashboard is for inspection and management, not a proxy.

Valkey runs as an ephemeral cache by default (persistence off) — a restart starts with an empty keyspace, which is the right default for a cache. Flip persistence on in the chart if you need durability.

Setup

The self-hosted stack (Helm + Compose) wires Valkey automatically. The API reads:

Variable	Description	Default
VALKEY_HOST	Valkey hostname	localhost
VALKEY_PORT	Valkey port	6379
VALKEY_PASSWORD	requirepass value (empty = no auth)	—
VALKEY_URL	Full redis:// URL (overrides the above)	—

Using the Cache panel

• Keyspace — scan keys by pattern (e.g. session:*), see each key’s type + TTL, set a new key (with optional TTL), inspect a value, or delete a key. Scanning uses SCAN (never the blocking KEYS), so it’s safe on large keyspaces. The browser is type-aware — it renders string, list, set, hash, and zset values — and pages through the keyspace with cursor-based scan pagination.
• Stats — server INFO: version, memory, connected clients, keyspace hit/miss counters.
• Developer — copy-paste client snippets.

Flushing the whole keyspace is admin-only.

HTTP API

The Cache panel is backed by these /api/cache/* routes. An unconfigured or unreachable Valkey returns 503.

Method	Endpoint	Description
GET	/api/cache/status	Health + headline stats: configured, ok, Valkey version, keys (DBSIZE), and a stats block (memory, connected clients, uptime, keyspace hits/misses).
GET	/api/cache/info	The full parsed Valkey INFO, grouped into sections (server, memory, clients, stats, …).
GET	/api/cache/keys	SCAN a page of keys. Query: pattern, cursor, count. Returns each key’s type + ttl and a cursor for the next page.
GET	/api/cache/keys/:key	Read a single value (with type + ttl).
PUT	/api/cache/keys/:key	Set a string value, optional ttl (seconds).
DELETE	/api/cache/keys/:key	Delete a key.
POST	/api/cache/flush	Admin-only. Clears the entire keyspace (FLUSHDB).

From your app

Node (ioredis)

import Redis from "ioredis";
const cache = new Redis({ host: "truss-valkey", port: 6379, password: process.env.VALKEY_PASSWORD });

await cache.set("session:42", JSON.stringify(user), "EX", 3600); // 1h TTL
const user = JSON.parse(await cache.get("session:42"));

valkey-cli

valkey-cli -a "$VALKEY_PASSWORD" SET ratelimit:ip:1.2.3.4 1 EX 60
valkey-cli -a "$VALKEY_PASSWORD" INCR ratelimit:ip:1.2.3.4

REST (via Truss API)

# set a key with a 1h TTL
curl -X PUT https://your-truss/api/cache/keys/session:42 \
  -H "content-type: application/json" \
  -d '{"value":"...","ttl":3600}'

# scan the keyspace
curl "https://your-truss/api/cache/keys?pattern=session:*"

Notes

• The single-instance core uses the whole keyspace.
• An unreachable Valkey degrades gracefully — the Cache panel reports “unavailable” and the rest of Truss keeps working.