One endpoint. One token. Three primitives.

The mental model

Three primitives, one client:

• KV — strings, counters, and hashes with TTLs. An ioredis-compatible method set (get/set/incr/hset…) plus a command() escape hatch and pipeline(). See KV.
• Queues — durable, at-least-once work queues with delays, idempotency keys, visibility timeouts, and a dead-letter queue. See Queues.
• Pub/sub — fan-out messaging over Server-Sent Events. See Pub/Sub.

Everything is organized into namespaces. A namespace is where you choose the storage backend and consistency, and it’s what a data-plane token is scoped to. You create namespaces and mint tokens in the control plane — see Control plane.

Connect a client

Every SDK exposes the same createClient(). Pass a connection string or a { url, token } object. On Node, calling it with no arguments reads TILLCACHE_URL from the environment.

import { createClient } from '@tillstack/cache-node'

// Reads TILLCACHE_URL from the environment (tillcache://<token>@cache.tilldev.dev):
const cache = createClient()

// …or pass a connection string / object explicitly:
const a = createClient('tillcache://tc_live_xxx@cache.tilldev.dev')
const b = createClient({ url: 'https://cache.tilldev.dev', token: process.env.TILLCACHE_TOKEN })

The connection string is tillcache://<token>@cache.tilldev.dev. The token is a data-plane token (prefix tc_) sent as a bearer credential — never in a URL you log or expose to a browser bundle. See Security.

Pick your SDK

All three wrap the same @tillstack/cache-core:

The three primitives

Each primitive has its own page with copy-pasteable examples:

• KV — get/set with TTLs, counters, hashes, mget/mset, pipelines, and the raw command() escape hatch.
• Queues — push/pull/ack/nack and the consume() convenience loop, with delays, dedupe keys, visibility timeouts, and a dead-letter queue.
• Pub/Sub — publish() and an SSE-backed subscribe().

Vendor-agnostic backends

The backend is chosen per namespace, so the same client can front managed Redis for one namespace and Cloudflare Durable Objects for another. There is no vendor lock baked into your code:

• upstash — managed Redis-over-REST, region-anchored. The default, and what ships day one.
• durable — Cloudflare Durable Objects: strong consistency, per-POP. Opt-in.
• byo — point the namespace at your own Redis-compatible HTTPS endpoint. Enterprise, no lock-in.
• auto — let TillCache place it.

Each namespace also has a consistency knob — strong vs eventual. Read the trade-offs in Backends & vendors.

Namespaces & tokens

You create namespaces and mint data-plane tokens in the dashboard at /<org>/cache, or from the CLI:

tilldev cache namespaces create sessions --backend upstash --consistency strong
tilldev cache tokens create --namespace sessions --scope read-write   # → tc_…
tilldev cache tokens create --namespace sessions --scope read-only

Tokens (prefix tc_) carry a scope — read-write or read-only — and are the token you hand a client. The control plane is where namespaces, backends, and tokens live; the data plane is the one endpoint your SDKs talk to.

It shows up in TillPulse

You don’t wire up a second dashboard. Hot keys, queue depth and lag, and slow commands surface in TillPulse automatically — the same workspace, the same alerts you already route. When a queue backs up or a command runs long, you see it where you already look.

Pricing shape

The free tier has a hard cap, so there is no surprise bill:

Security model

• Bearer-only tokens. Tokens are sent as bearer credentials, never in a URL, and are stored hashed at rest.
• Allow-listed commands only. Only a safe command set is accepted — FLUSHALL, KEYS, CONFIG, and EVAL are not in it.
• Quotas and limits. A hard daily quota plus a per-second limiter protect the namespace (and your bill).
• BYO is guarded. Bring-your-own endpoints are SSRF-guarded and their credentials are encrypted at rest.